compare_modes
Compare ocean, air, and sea-air transport modes based on total economic cost, including capital, holding, and stockout costs, to recommend the most cost-effective option for your shipment.
Instructions
Decide the TRANSPORT MODE for a shipment — OCEAN vs AIR vs SEA-AIR — on TOTAL economic cost, not just freight. The other tools price the ocean move; this one answers the importer's prior question: should these goods even go by sea? It costs all three modes and recommends the economically optimal one. Air is priced correctly on the IATA CHARGEABLE WEIGHT = max(actual gross weight, volumetric weight at 167 kg/m³) with an air fuel (FSC) + security (SSC) + handling stack — so bulky-but-light cargo is properly penalised (the lever a naïve 'air is just faster' estimate misses). Sea-air is modeled via the real hubs (Asia→Europe via Dubai/Jebel Ali, Asia→US-East via a US-West gateway): a cheap ocean leg to the hub + a short air final leg. The recommendation runs a real DECISION MODEL: cost of CAPITAL tied up in transit (value × annual rate × days), a p90 safety-stock HOLDING cost from each mode's variability, and — if you pass a deadline — an EXPECTED STOCKOUT cost from the probability the mode arrives late. So for high-value goods (or a tight deadline) air/sea-air can win even though the freight is far dearer, while for cheap goods ocean's much lower freight dominates. Returns the full ocean/air/sea-air table (freight, p50/p90 transit, capital, holding, stockout, total economic cost) + the recommended mode + the trade-off math. Every figure is modeled and tagged; air rates are volatile so they are honest BANDS, not a quote. PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| origin_port | Yes | Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate. | |
| dest_port | Yes | Destination port (city name, UN/LOCODE, or 'City, Country'). | |
| container_type | No | Container size '20ft'/'40ft'/'40HC' for the ocean leg. Optional; defaults to '40ft'. | |
| value | Yes | Merchandise value in USD — REQUIRED. It is the capital tied up in transit and the basis of the whole mode trade-off. | |
| weight_kg | No | Shipment gross weight in kg. Provide this and/or volume_m3 — air is billed on the chargeable weight (max of actual and volumetric). | |
| volume_m3 | No | Shipment volume in cubic metres. Drives the IATA volumetric weight (m³ × 167 kg). Provide this and/or weight_kg. | |
| deadline | No | Optional hard arrival deadline (ISO 'YYYY-MM-DD'). If given, the engine adds an expected-stockout cost from each mode's probability of arriving late. | |
| stockout_penalty | No | USD penalty if the goods miss the deadline (lost sale / line-down / expedite). Defaults to the goods' value when a deadline is given without one. Optional. | |
| annual_capital_rate_pct | No | Annual cost-of-capital as a fraction (e.g. 0.12 = 12%/yr) for goods in transit. Optional; default 0.12. | |
| annual_holding_rate_pct | No | Annual inventory holding/carrying rate as a fraction (e.g. 0.25 = 25%/yr) for the p90 safety-stock buffer. Optional; default 0.25. | |
| band | No | Air/sea-air rate band to use: 'low', 'typical' or 'high'. Optional; default 'typical'. | |
| jet_fuel_proxy | No | Optional jet-fuel proxy to drive the air FSC. Omit for a modeled reference level. | |
| ship_date | No | Intended ship date (ISO). Drives the ocean seasonal surcharges & transit window. Optional; defaults to today. | |
| estimated_days_at_port | No | Days the box dwells at destination (adds D&D to the ocean freight leg). Optional. | |
| free_days | No | Carrier free days before D&D on the ocean leg (default 5 if a dwell is given). Optional. | |
| overweight | No | Flag an overweight ocean load (freight surcharge). Optional. | |
| fuel_proxy | No | Optional VLSFO $/tonne for the ocean BAF model. Optional. |