Get market rates through the API

The Market Rates API puts the same Low, Mid and High band you see in the app into your own TMS, pricing tool or quoting screen. You send a lane, and you get back a weekly series of rates, one entry per week with its own confidence label. Each entry is built from the 12 weeks of bids up to that week, and the newest one is what the app shows. The full reference is at docs.cargado.com.

Step 1: Get a key

Keys are created by the Cargado team. Email success@cargado.com, name the integration, and ask for the market rates permission. See Get an API key for your integration for how keys work and how to keep them safe. Send the key in an api-key header on every request to https://api.cargado.com.

Step 2: Send a lookup

Call POST /rates/history with a requests list of 1 to 16 lanes. Each lane needs:

• Stops: a pickup first and a delivery last. Places can be a structured city, a postal code, an address, or a free-text address.
• Trailer: exactly one trailer type.
• Crossing (optional, Mexico lanes only): add a border-crossing stop, or leave it out and Cargado uses its recommended crossing and tells you which one.
• Route miles (optional): your own distance, if you want it to override Cargado's.

Add currency (USD, MXN or CAD) to the request. It defaults to USD.

Step 3: Read the results

Results come back in the same order as your requests. Each one succeeds or fails on its own, marked DATA or ERROR, so one bad lane does not sink the batch. A DATA result includes:

• The priced lane: origin and destination markets (and whether either is an extended market), trailer category and crossing.
• suggestedRates, allInRates and perMileRates: one entry per week, oldest first. Each has p25, p50 and p75 in cents or centavos, plus margin of error and confidence.
• latestSuggestedRate: the figure the app shows as Low, Mid and High.
• Route miles, with and without deadhead to the market centers.

Weeks without enough data are left out. If a lane has none, you get an ERROR result with code RATE_HISTORY_NOT_FOUND.

Step 4: Test before you go live

Ask the Cargado team for access to the sandbox at https://api.sandbox.cargado.com. Sandbox returns simulated rates, so use it to test your integration, never to quote.

Caching and usage

Every POST /rates/history call is recorded as a lookup and counts toward the same monthly allowance as lookups in the app and in Excel. If you send the exact same request again in the same week, Cargado returns the earlier result instead of creating a new lookup. You can also fetch a saved lookup by its id with GET /rates/history/{id}. See Plan limits, and what the usage warning emails mean.

Important: where docs.cargado.com and this article differ, go by this article: a request holds up to 16 lanes, and weekly rates come back oldest first.