{"openapi":"3.1.0","info":{"title":"ShippingRates API","version":"2.2.0","description":"Shipping intelligence API for demurrage, detention, freight rates, local charges, transit times, port congestion, inland haulage, and risk scoring. Covers 9 shipping lines across 195 countries with 26,276 verified d&d tariffs across 2,521 ports. Supports x402 micropayments (USDC on Base and Solana) and MCP protocol for AI agent integration.","contact":{"name":"ShippingRates","email":"vinay@shippingrates.org","url":"https://shippingrates.org"},"license":{"name":"Proprietary","url":"https://shippingrates.org/terms"},"x-logo":{"url":"https://shippingrates.org/og-image.png"}},"servers":[{"url":"https://api.shippingrates.org","description":"Production API"}],"tags":[{"name":"Free","description":"Free endpoints — no authentication required"},{"name":"D&D","description":"Demurrage and detention calculation and comparison"},{"name":"Charges","description":"Local charges, surcharges, and CFS tariffs"},{"name":"Rates","description":"Freight rates and landed cost estimation"},{"name":"Port Intelligence","description":"Port details, congestion, vessel schedules, and reliability"},{"name":"Inland","description":"Inland haulage routes, rates, and facility directory"},{"name":"Schedules","description":"Transit schedules and service information"},{"name":"Risk","description":"Route risk scoring and regulatory updates"},{"name":"Bulk","description":"Batch endpoints for multiple lookups in a single request"},{"name":"Discovery","description":"Machine-readable API and payment discovery metadata"}],"paths":{"/.well-known/x402":{"get":{"tags":["Discovery"],"summary":"x402 payment discovery metadata","description":"Machine-readable x402 metadata for agents and pay-per-call clients. Alias of /.well-known/x402.json.","responses":{"200":{"description":"x402 discovery metadata","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/x402.json":{"get":{"tags":["Discovery"],"summary":"x402 payment discovery metadata","description":"Machine-readable x402 metadata for agents and pay-per-call clients.","responses":{"200":{"description":"x402 discovery metadata","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/stats":{"get":{"tags":["Free"],"summary":"API statistics","description":"Get API statistics — carrier count, country count, D&D record count, and endpoint count.","responses":{"200":{"description":"API statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stats"}}}}}}},"/api/lines":{"get":{"tags":["Free"],"summary":"Available shipping lines","description":"List all shipping lines (carriers) available in the system with their slugs.","responses":{"200":{"description":"List of shipping lines","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLine"}}}}}}}},"/api/search":{"get":{"tags":["Free"],"summary":"Search ports and routes","description":"Search for ports, routes, and shipping data by keyword.","parameters":[{"name":"keyword","in":"query","required":true,"schema":{"type":"string"},"description":"Search term (port name, code, city, or country)"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/fx":{"get":{"tags":["Free"],"summary":"Currency exchange rates","description":"Get current FX rates for shipping currencies (USD, EUR, INR, etc.).","parameters":[{"name":"base","in":"query","schema":{"type":"string","default":"USD"},"description":"Base currency (default: USD)"}],"responses":{"200":{"description":"Exchange rates","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/dd/calculate":{"post":{"tags":["D&D"],"summary":"Calculate D&D costs","description":"Calculate demurrage & detention costs for a shipping line, country, container type, and number of days. Returns slab breakdown with free days, per-diem rates, and total cost.","x-price":"$0.10","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DDCalculateRequest"},"example":{"line":"maersk","country":"IN","container_type":"40HC","days":14}}}},"responses":{"200":{"description":"D&D calculation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DDCalculateResponse"}}}},"402":{"description":"Payment required — x402 settlement needed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/dd/compare":{"post":{"tags":["D&D"],"summary":"Compare D&D across carriers","description":"Compare demurrage & detention costs across all shipping lines for a given country, container type, and days.","x-price":"$0.25","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DDCompareRequest"},"example":{"country":"IN","container_type":"40HC","days":14}}}},"responses":{"200":{"description":"D&D comparison result","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/local-charges":{"post":{"tags":["Charges"],"summary":"Port local charges","description":"Get port local charges (THC, documentation fees, seal fees, BL fees) for a shipping line and country.","x-price":"$0.05","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalChargesRequest"},"example":{"line":"maersk","country":"IN"}}}},"responses":{"200":{"description":"Local charges","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/cfs":{"post":{"tags":["Charges"],"summary":"CFS handling tariffs","description":"Get Container Freight Station (CFS) handling tariffs — charges for LCL cargo consolidation/deconsolidation.","x-price":"$0.05","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"port":{"type":"string","description":"UN/LOCODE port code"},"service":{"type":"string"},"cargo_type":{"type":"string"}},"required":["port"]},"example":{"port":"INMAA"}}}},"responses":{"200":{"description":"CFS tariffs","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/surcharges":{"get":{"tags":["Charges"],"summary":"Carrier surcharges","description":"Shipping line surcharges — BAF, EBS, and more.","x-price":"$0.02","parameters":[{"name":"line","in":"query","required":true,"schema":{"type":"string"},"description":"Shipping line slug"},{"name":"country","in":"query","schema":{"type":"string"},"description":"ISO 2-letter country code"},{"name":"direction","in":"query","schema":{"type":"string","enum":["import","export"]},"description":"Trade direction"}],"responses":{"200":{"description":"Surcharges","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/rates":{"get":{"tags":["Rates"],"summary":"Freight rates","description":"Freight rates — historical low/mid/high with trend.","x-price":"$0.03","parameters":[{"name":"origin","in":"query","required":true,"schema":{"type":"string"},"description":"Origin port UN/LOCODE"},{"name":"destination","in":"query","required":true,"schema":{"type":"string"},"description":"Destination port UN/LOCODE"},{"name":"container_type","in":"query","schema":{"type":"string"},"description":"Container type (20DV, 40DV, 40HC, etc.)"}],"responses":{"200":{"description":"Freight rates","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/total-cost":{"get":{"tags":["Rates"],"summary":"Full landed cost","description":"Full landed cost — freight + surcharges + local charges + D&D + transit.","x-price":"$0.15","parameters":[{"name":"line","in":"query","required":true,"schema":{"type":"string"},"description":"Shipping line slug"},{"name":"origin","in":"query","required":true,"schema":{"type":"string"},"description":"Origin port UN/LOCODE"},{"name":"destination","in":"query","required":true,"schema":{"type":"string"},"description":"Destination port or inland location"},{"name":"container_type","in":"query","required":true,"schema":{"type":"string"},"description":"Container type"},{"name":"detention_days","in":"query","schema":{"type":"number"},"description":"Expected detention days (default: 0)"}],"responses":{"200":{"description":"Landed cost breakdown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TotalCostResponse"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/port":{"get":{"tags":["Port Intelligence"],"summary":"Port details","description":"Port details — coordinates, operators, infrastructure, congestion level.","x-price":"$0.01","parameters":[{"name":"code","in":"query","required":true,"schema":{"type":"string"},"description":"UN/LOCODE port code"}],"responses":{"200":{"description":"Port details","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/congestion":{"get":{"tags":["Port Intelligence"],"summary":"Port congestion","description":"Port congestion — current level and history.","x-price":"$0.02","parameters":[{"name":"port","in":"query","required":true,"schema":{"type":"string"},"description":"UN/LOCODE port code"},{"name":"days_back","in":"query","schema":{"type":"number"},"description":"Days of history (default: 30)"}],"responses":{"200":{"description":"Congestion data","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/vessel-schedule":{"get":{"tags":["Port Intelligence"],"summary":"Vessel schedule","description":"Upcoming vessel calls at port.","x-price":"$0.02","parameters":[{"name":"port","in":"query","required":true,"schema":{"type":"string"},"description":"UN/LOCODE port code"},{"name":"days_ahead","in":"query","schema":{"type":"number"},"description":"Days to look ahead (default: 14)"}],"responses":{"200":{"description":"Vessel schedule","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/vessel-schedule-options":{"get":{"tags":["Schedules"],"summary":"Vessel schedule options with cutoffs","description":"Carrier vessel/voyage schedule options with port, SI, and VGM cutoff deadlines when published.","x-price":"$0.03","parameters":[{"name":"origin","in":"query","required":true,"schema":{"type":"string"},"description":"Origin UN/LOCODE"},{"name":"destination","in":"query","required":true,"schema":{"type":"string"},"description":"Destination UN/LOCODE"},{"name":"carrier","in":"query","schema":{"type":"string"},"description":"Carrier filter"},{"name":"days_ahead","in":"query","schema":{"type":"number"},"description":"Days to look ahead (default: 90)"},{"name":"limit","in":"query","schema":{"type":"number"},"description":"Maximum options to return (default: 50)"}],"responses":{"200":{"description":"Vessel schedule options with cutoff completeness","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/reliability":{"get":{"tags":["Port Intelligence"],"summary":"Schedule reliability","description":"Schedule reliability — on-time percentage, cancellations.","x-price":"$0.02","parameters":[{"name":"line","in":"query","required":true,"schema":{"type":"string"},"description":"Shipping line slug"},{"name":"trade_lane","in":"query","schema":{"type":"string"},"description":"Trade lane filter"}],"responses":{"200":{"description":"Reliability data","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/transit":{"get":{"tags":["Port Intelligence"],"summary":"Transit time","description":"Transit time between ports — days, carriers, trade lane.","x-price":"$0.02","parameters":[{"name":"origin","in":"query","required":true,"schema":{"type":"string"},"description":"Origin port UN/LOCODE"},{"name":"destination","in":"query","required":true,"schema":{"type":"string"},"description":"Destination port UN/LOCODE"}],"responses":{"200":{"description":"Transit time","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/regulatory":{"get":{"tags":["Risk"],"summary":"Regulatory updates","description":"Regulatory updates by country.","x-price":"$0.01","parameters":[{"name":"country","in":"query","required":true,"schema":{"type":"string"},"description":"ISO 2-letter country code"},{"name":"limit","in":"query","schema":{"type":"number"},"description":"Max results (default: 10)"}],"responses":{"200":{"description":"Regulatory updates","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/inland-search":{"post":{"tags":["Inland"],"summary":"Search inland routes","description":"Search inland transport routes (road/rail haulage from port to inland destination).","x-price":"$0.03","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"line":{"type":"string"},"country":{"type":"string"},"keyword":{"type":"string"}},"required":["line","country"]},"example":{"line":"maersk","country":"IN","keyword":"delhi"}}}},"responses":{"200":{"description":"Inland routes","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/inland":{"post":{"tags":["Inland"],"summary":"Inland haulage rates","description":"Get inland haulage (trucking/rail) rates for moving containers between ports and inland destinations.","x-price":"$0.05","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"},"destination":{"type":"string"},"container_type":{"type":"string"},"mode":{"type":"string"}},"required":["origin","destination"]},"example":{"origin":"INNSA","destination":"Ahmedabad"}}}},"responses":{"200":{"description":"Inland rates","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/inland/compare":{"post":{"tags":["Inland"],"summary":"Compare inland rates","description":"Compare inland haulage rates across carriers — find cheapest road/rail option for port-to-ICD moves.","x-price":"$0.08","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"},"destination":{"type":"string"},"container_type":{"type":"string","enum":["20GP","20DV","40GP","40DV","40HC"]}},"required":["origin","destination"]},"example":{"origin":"INNSA","destination":"Ahmedabad","container_type":"20GP"}}}},"responses":{"200":{"description":"Inland rate comparison","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/facilities":{"post":{"tags":["Inland"],"summary":"ICD/CFS facility directory","description":"ICD/CFS facility directory — locations, capacity, rail connectivity, and handling capabilities.","x-price":"$0.02","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["ICD","CFS"]},"state":{"type":"string"},"code":{"type":"string"},"rail_connected":{"type":"boolean"}}},"example":{"type":"ICD","state":"MH"}}}},"responses":{"200":{"description":"Facility list","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/transit-schedules":{"post":{"tags":["Schedules"],"summary":"Transit schedules","description":"Transit schedules — carrier services, transit days, routes, and transhipment ports.","x-price":"$0.03","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"carrier":{"type":"string"},"origin":{"type":"string"},"destination":{"type":"string"},"max_days":{"type":"number"}},"required":["carrier"]},"example":{"carrier":"maersk","origin":"INNSA","destination":"AEJEA"}}}},"responses":{"200":{"description":"Transit schedules","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/congestion-news":{"post":{"tags":["Port Intelligence"],"summary":"Congestion news","description":"Congestion news — port disruption alerts, severity levels, and recent headlines.","x-price":"$0.02","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"port":{"type":"string"},"severity":{"type":"string","enum":["normal","elevated","congested"]},"days_back":{"type":"number"},"limit":{"type":"number"}}},"example":{"port":"INNSA","days_back":7}}}},"responses":{"200":{"description":"Congestion news","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/risk-score":{"post":{"tags":["Risk"],"summary":"Route risk score","description":"Route risk score — congestion, news alerts, and chokepoint analysis for origin-destination pairs (0-100 scale).","x-price":"$0.10","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"},"destination":{"type":"string"}},"required":["origin","destination"]},"example":{"origin":"INNSA","destination":"AEJEA"}}}},"responses":{"200":{"description":"Risk score","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/bulk/ports":{"post":{"tags":["Bulk"],"summary":"Bulk port lookup","description":"Bulk port lookup — fetch details for up to 10 ports in a single request.","x-price":"$0.05","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ports":{"type":"array","items":{"type":"string"},"maxItems":10}},"required":["ports"]},"example":{"ports":["INNSA","AEJEA","SGSIN"]}}}},"responses":{"200":{"description":"Port details","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/bulk/transit":{"post":{"tags":["Bulk"],"summary":"Bulk transit lookup","description":"Bulk transit lookup — fetch transit times for up to 5 routes in a single request.","x-price":"$0.10","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"routes":{"type":"array","items":{"type":"object","properties":{"origin":{"type":"string"},"destination":{"type":"string"}},"required":["origin","destination"]},"maxItems":5}},"required":["routes"]},"example":{"routes":[{"origin":"INNSA","destination":"AEJEA"}]}}}},"responses":{"200":{"description":"Transit times","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}},"/api/bulk/rates":{"post":{"tags":["Bulk"],"summary":"Bulk freight rates","description":"Bulk freight rates — fetch rates for up to 5 queries in a single request.","x-price":"$0.15","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"queries":{"type":"array","items":{"type":"object","properties":{"origin":{"type":"string"},"destination":{"type":"string"},"line":{"type":"string"}},"required":["origin","destination"]},"maxItems":5}},"required":["queries"]},"example":{"queries":[{"origin":"INNSA","destination":"AEJEA","line":"maersk"}]}}}},"responses":{"200":{"description":"Freight rates","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Response"}}}}}}}},"components":{"schemas":{"Stats":{"type":"object","properties":{"carriers":{"type":"number","description":"Number of shipping carriers covered"},"countries":{"type":"number","description":"Number of countries covered"},"dd_records":{"type":"number","description":"Total D&D tariff records"},"endpoints":{"type":"number","description":"Total API endpoints"}}},"ShippingLine":{"type":"object","properties":{"slug":{"type":"string","description":"URL-safe carrier identifier"},"name":{"type":"string","description":"Full carrier name"}}},"DDCalculateRequest":{"type":"object","required":["line","country","container_type","days"],"properties":{"line":{"type":"string","description":"Shipping line slug","enum":["maersk","msc","cma-cgm","hapag-lloyd","one","cosco","zim"]},"country":{"type":"string","description":"ISO 2-letter country code"},"container_type":{"type":"string","description":"Container type","enum":["20DV","40DV","40HC","20RF","40RF","20OT","40OT","20FR","40FR"]},"days":{"type":"number","description":"Number of detention days (1-365)","minimum":1,"maximum":365}}},"DDCalculateResponse":{"type":"object","properties":{"line":{"type":"string"},"country":{"type":"string"},"container_type":{"type":"string"},"days":{"type":"number"},"free_days":{"type":"number"},"currency":{"type":"string"},"slabs":{"type":"array","items":{"type":"object","properties":{"from":{"type":"number"},"to":{"type":"number"},"rate_per_day":{"type":"number"},"days":{"type":"number"},"cost":{"type":"number"}}}},"total_cost":{"type":"number"}}},"DDCompareRequest":{"type":"object","required":["country","container_type","days"],"properties":{"country":{"type":"string","description":"ISO 2-letter country code"},"container_type":{"type":"string","description":"Container type code"},"days":{"type":"number","description":"Number of detention days","minimum":1,"maximum":365}}},"LocalChargesRequest":{"type":"object","required":["line","country"],"properties":{"line":{"type":"string","description":"Shipping line slug"},"country":{"type":"string","description":"ISO 2-letter country code"},"port_code":{"type":"string","description":"Optional port code filter"}}},"TotalCostResponse":{"type":"object","properties":{"line":{"type":"string"},"origin":{"type":"string"},"destination":{"type":"string"},"container_type":{"type":"string"},"freight":{"type":"number"},"surcharges":{"type":"number"},"local_charges_origin":{"type":"number"},"local_charges_destination":{"type":"number"},"detention":{"type":"number"},"transit_days":{"type":"number"},"total_landed_cost":{"type":"number"},"currency":{"type":"string"}}},"X402Response":{"type":"object","description":"x402 payment required response. Your x402 client should automatically settle the payment and retry.","properties":{"error":{"type":"string","example":"X-PAYMENT-REQUIRED"},"accepts":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string"},"token":{"type":"string"},"price":{"type":"string"},"payTo":{"type":"string"}}}}}}},"securitySchemes":{"x402":{"type":"apiKey","in":"header","name":"X-PAYMENT","description":"x402 payment protocol. When an endpoint returns HTTP 402, your client should use the payment details in the response to settle a USDC micropayment on Base or Solana, then retry with the X-PAYMENT header containing the settlement proof."},"freeTier":{"type":"apiKey","in":"header","name":"X-FREE-TIER-KEY","description":"Free tier key — 25 requests/month. Register at app.shippingrates.org to get a key."}}},"externalDocs":{"description":"LLM-readable API documentation","url":"https://api.shippingrates.org/llms-full.txt"}}