Identify a neutral ocean freight rate API provider (such as Freightos, Flexport, or a similar freight intelligence platform) and obtain API credentials through the platform's developer program.
Submit a rate query specifying origin port (UN/LOCODE), destination port, cargo weight, container type (20GP, 40GP, 40HC, 45HC), commodity (for surcharge eligibility), and requested shipment date.
Parse the rate response array; for each quote extract the base ocean freight rate, applicable surcharges (BAF, CAF, PSS, GRI), transit time, carrier name, and validity expiry date.
Sort quotes by total all-in cost including surcharges, then by transit time, and present the top options to the booking decision workflow; do not compare base rates alone as surcharges can represent 40-80% of total cost.
Before booking, re-validate the rate with the carrier directly or through the platform's booking API; spot rates may expire between quote and booking, especially in volatile markets.
Store rate quotes with their validity window and all-in breakdown for freight audit purposes; compare invoiced amounts against quoted rates to detect overbilling at the auditing stage.
Known gotchas
Ocean freight rates are highly volatile and carrier-quoted rates may expire within 24-72 hours on spot markets; never display a cached rate without checking its validity timestamp.
General Rate Increases (GRIs) can be announced by carriers with as little as 30 days notice and may not be reflected in existing quotes; subscribe to carrier rate advisory feeds to detect GRI timing.
All-in rate comparisons must normalise surcharges to the same port pair and container type; BAF and PSS rates vary by trade lane and comparing them across different port pairs produces misleading cost comparisons.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp