Skip to main content
By analyzing the many freight postings and bids on our platform, Cargado can provide a realistic rate distribution for a hypothetical piece of freight over time. You can use this for:
  • Choosing an instant bid response price when posting
  • Quoting a shipper’s spot freight or RFP
  • Comparing your previous load prices to the market
  • Placing a bid
Only four pieces of information about the freight are required: origin, destination, trailer type, and border crossing (in some cases). We’ll go over how to formulate a request below.

​
Minimal request

This request describes the movement of a dry van load from Monterrey to Chicago, crossing at the World Trade International Bridge in Laredo/Nuevo Laredo. See the API reference for all fields. 
POST /rates/history
Api-Key: <API Key>
Content-Type: application/json

{
  "requests": [
    {
      "stops": [
        {
          "type": "PICKUP",
          "placeDetails": {
            "place": {
              "type": "CITY",
              "city": "Monterrey",
              "state": "MX_NLE",
              "country": "MX"
            }
          }
        },
        {
          "type": "BORDER_CROSSING",
          "usMxBorderCrossing": "LAREDO_INTL_BRIDGE"
        },
        {
          "type": "DELIVERY",
          "placeDetails": {
            "place": {
              "type": "CITY",
              "city": "Chicago",
              "state": "US_IL",
              "country": "US"
            }
          }
        }
      ],
      "trailerRequirements": {
        "allowedTypes": ["DRY_VAN"]
      }
    }
  ]
}
Note that, per the rules of stops, the pickup is specified first and the delivery is specified last. In addition, because this load crosses the United States-Mexico border, a border crossing stop is specified. If the load remained in a single country, or only crossed the Canada-United States border, a border crossing may not be specified. See the StopInput model.

​
Batching

Note that the requests array in the request body and the results array in the response body will always have the same length and be in the same order. In other words, the first element of results will correspond to the first element of requests, and so on. Where possible, we recommend batching rate lookups by sending a single HTTP request with multiple requests elements (up to a maximum of 64 elements), rather than one HTTP request for each lookup. This will give faster responses and reduce server load. Each request may succeed or fail independently of the others. The request’s entry in the results array will indicate this via a type field whose value is either DATA or ERROR.

​
Place types

You may specify a Stop’s Place in either structured or unstructured format. In structured format, the various components of the Place are specified in separate JSON fields. Structured Places are available in three granularities:
  • City: the center of a city or neighborhood within a city
  • Postal code: the center of the extrapolated geographic area that a postal code (“zip code” in the United States) covers
  • Address: the street address of a particular building
The unstructured format for a Place is a string that encodes all of the information in a structured-format Place. Behind the scenes, we use a third-party geocoding service to map this string to a set of coordinates. It’s reasonably tolerant of a wide array of string formats, though we recommend including as much information as possible and approximating the relevant country’s standard address format.
  • “2045 W Grand Ave, Chicago, Illinois 60612”
  • “Wicker Park, Chicago, IL”
  • “60612 USA”
  • “Chicago, USA”
For more information, see the Place model.

​
Rates

All weekly rate distributions between the current date and 12 weeks ago are returned in the rates array, in descending order of date. Note that any weeks during which Cargado doesn’t have sufficient data, including the latest week, are omitted from this array; if the result would be an empty array, then an error is returned instead. Each weekly rate contains the “suggested”, “all-in”, and “per-mile” values. While we recommend using the suggested rate, which is a flat rate calculated using our best practices, you may also choose to use the all-in rate (which is also flat), or the per-mile rate multiplied by the route distance. Note that the route distance itself has two variants:
  • Without deadhead, which is the driving distance between all stops in the input array, in order
  • With deadhead, which adds a stop at the origin market’s centroid at the beginning of the array, and a stop at the destination market’s centroid at the end of the array. These market centroids represent the typical idling location for trucks within a market (generally its largest city).

​
Lookup records

Every rate lookup, whether initiated via the Cargado web UI or public API, is saved in our database for later review. This record includes both the full request body and the full response as it as at lookup time, i.e. the response is not updated in following weeks. These lookup records serve multiple purposes: review in the web UI (each one has a unique, shareable URL), metering for billing purposes, and caching to prevent unintended repeat lookups.

​
Metering

Your organization’s Cargado plan includes a certain number of lookups per month (as determined by counting lookup records), whether generated through the web UI or public API. If you exceed your plan’s limit, we will alert you according to your plan.

​
Caching

If you submit a request whose canonicalized JSON body is identical to a previous successful lookup’s request, and the result would contain no new information (e.g. a new week’s rates), then that previous lookup’s result will be returned, instead of performing and saving a new lookup. When new rates are generated weekly, they invalidate the cache for all previous lookups that would include those rates. Besides having a non-unique id field, a cached result is indistinguishable from a newly-generated result.