Price a shipment

This guide prices an export from a warehouse near Chicago to Shanghai. You'll find the port codes, get ocean rates, see what's inside a price, add the truck from the warehouse, and price a smaller shipment that doesn't fill a container. Every call here needs a key with Read rates & surcharges (rates:read).

Find the port codes

Rate searches take UN/LOCODEs, the five-character codes for ports and places, such as USCHI for Chicago. Look them up by name:

curl -G "https://api-dev.highqube.ai/unlocations" \
  -H "Authorization: Bearer $HIGHQUBE_API_KEY" \
  -d search=Shanghai -d limit=2

{
  "success": true,
  "message": "UN locations fetched successfully",
  "data": [
    {
      "id": 20083,
      "port_code": "CNSGH",
      "port_name": "Shanghai",
      "city_name": "Shanghai",
      "state": "Shanghai Shi",
      "country_name": "CN",
      "custom_port_code": null
    },
    {
      "id": 19967,
      "port_code": "CNPVG",
      "port_name": "Shanghai Pudong International Apt",
      "city_name": "Shanghai Pudong International Apt",
      "state": "Shanghai Shi",
      "country_name": "CN",
      "custom_port_code": null
    }
  ]
}

Use a result's port_code in rate searches: CNSGH is the seaport, CNPVG the airport. The best matches come first: an exact code, then codes starting with what you typed, then place names. Search also matches your organization's own codes (custom_port_code).

For airports by their IATA code, use GET /unlocations/iata_codes. A search for Chicago returns O'Hare (ORD) and Midway (MDW).

Get ocean rates

curl -G "https://api-dev.highqube.ai/rate-search" \
  -H "Authorization: Bearer $HIGHQUBE_API_KEY" \
  --data-urlencode 'routes=[{"origin":"USCHI","destination":"CNSGH"}]' \
  -d containerSizes=20 -d containerSizes=40HC \
  -d limitToTopN=2 -d sortBy=40HC -d sortOrder=asc

Each result is one carrier's rate on a lane, for one routing and equipment type:

Useful filters:

• Several lanes at once: add more objects to routes. They're searched together in one request.
• containerSizes: 20, 40, 40HC, 45, 48 or 53, repeated for several. Leave it out for every size.
• containerType: DRY, REEFER, TANK and so on.
• dateFrom, dateTo: rates you can book during a window, as YYYY-MM-DD.
• coreCarriersOnly=true: only carriers your organization marked as core. Carriers you blacklisted are always left out.
• limitToTopN: only the N cheapest. limitToOneCarrierPerRow=true keeps the cheapest per carrier.

See what's inside a price

Pass a result's extracted_group_id to get every surcharge behind its price, per container size:

curl -G "https://api-dev.highqube.ai/rate-groups/373464df73e9342f/surcharges" \
  -H "Authorization: Bearer $HIGHQUBE_API_KEY" \
  -d container_size=40HC

The heart of the answer is total_charges_summary, one entry per size:

{
  "container_size": "40'HC",
  "base_rate": "572.00",
  "total_surcharge": "0.00",
  "total_rate": "572.00",
  "counted_charges": [],
  "unpriced_charges": [
    { "surcharge_code": "BLF", "scope": "all", "reason": "route_not_covered", "conditional": false },
    { "surcharge_code": "IMS", "scope": "all", "reason": "route_not_covered", "conditional": false },
    { "surcharge_code": "NBF", "scope": "all", "reason": "route_not_covered", "conditional": false }
  ],
  "complete": false
}

• counted_charges are in total_rate. Here there are none yet, so the total is the base rate.
• unpriced_charges apply under the contract but have no price, so they're left out. complete: false says the same thing.

Where the contract fixes a surcharge's amount, it's priced and counted. From Jacksonville to Guanta, Venezuela, for example, /rate-groups/198a512e1d51022f/surcharges counts the contract's fixed IMS of $324 per 40'HC: base_rate is 2746.00 and total_rate is 3070.00.

The answer also lists the charges themselves: surcharges in effect today, future_surcharges filed to start later, and subjectToSurcharges, which apply only in special circumstances (the carrier's conditions are in notes).

Add the truck from the warehouse

A rate search can price the truck leg itself. Mark the route's origin as a door and give the address:

curl -G "https://api-dev.highqube.ai/rate-search" \
  -H "Authorization: Bearer $HIGHQUBE_API_KEY" \
  --data-urlencode 'routes=[{"origin":"USCHI","destination":"CNSGH","isOriginDoorDelivery":true,"originDoorLocation":{"city":"Joliet","state":"IL","country":"US","zip":"60431"}}]' \
  -d containerSizes=40HC -d limitToTopN=1

Each result then carries the truck leg in originDrayage, and rates includes it. From Joliet, the 40'HC comes to $1,118.13: $572.00 ocean, plus $425.00 to truck the box to the Chicago rail ramp, plus a 28.5% fuel surcharge on the truck rate ($121.13).

"originDrayage": {
  "40' HC": {
    "port": { "city": "Chicago", "state": "IL", "country": "US", "zip": null },
    "doorCity": "Joliet",
    "charges": {
      "base_charge": "425.00",
      "currency": "USD",
      "accessorial_charges": [
        { "surcharge_code": "FSC", "rate": "28.5000", "rate_basis": "PERCENTAGE", "amount": "121.13", "included_in_total": true },
        { "surcharge_code": "CHS", "rate": "40.0000", "rate_basis": "PER_DAY", "amount": null, "included_in_total": false,
          "note": "Billed per day of actual usage; not included in this quote's total since usage is unknown at quote time." }
      ],
      "total": "546.13"
    }
  }
}

Charges billed by the day or hour, such as chassis and waiting time, are listed with included_in_total: false: no one knows how many days a box will need when it's quoted.

For delivery at the other end, use isDestDoorDelivery and destinationDoorLocation the same way; the leg comes back in destinationDrayage.

Trucking on its own

To price only the truck, between a port or rail ramp and an address, use GET /drayage/rates. origin and destination are JSON objects with city, country and optionally state and zip:

curl -G "https://api-dev.highqube.ai/drayage/rates" \
  -H "Authorization: Bearer $HIGHQUBE_API_KEY" \
  --data-urlencode 'origin={"city":"Los Angeles","state":"CA","country":"US"}' \
  --data-urlencode 'destination={"city":"Ontario","state":"CA","country":"US"}' \
  -d container_size=40HC

From the Port of Los Angeles to Ontario, CA, a 40'HC is $575.00 plus $163.88 fuel surcharge: total is 738.88.

To turn what a person typed into a city, state and ZIP, use GET /drayage/locations?q=....

Smaller shipments (LCL)

For less than a container load, use POST /contracts/lcl-rates. Describe the cargo either piece by piece (packages, with dimensions and weight) or as a total (totalWeight, and totalVolume in CBM):

curl "https://api-dev.highqube.ai/contracts/lcl-rates" \
  -H "Authorization: Bearer $HIGHQUBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin": "USCHI", "destination": "CNSGH", "totalWeight": 1200, "totalVolume": 4.5, "weightUnit": "KG"}'

LCL is priced per revenue ton (rt): the larger of the volume in CBM and the weight in metric tons. This cargo is 4.5 CBM and 1.2 t, so it's charged as 4.5. The rates come cheapest first:

{
  "origin": "USCHI",
  "destination": "CNSGH",
  "items": [
    {
      "carrier": "Pacific CFS Lines",
      "via": "Long Beach",
      "transit_time": "35",
      "etd": "Weekly, Mon",
      "transshipment": "Direct",
      "rt": 4.5,
      "billable_rt": 4.5,
      "rate_per_rt": 58.0,
      "base_freight": 261.0,
      "currency": "USD"
    },
    {
      "carrier": "Lakeview Consolidators",
      "via": "Los Angeles",
      "transit_time": "32",
      "etd": "Weekly, Thu",
      "transshipment": "Direct",
      "rt": 4.5,
      "billable_rt": 4.5,
      "rate_per_rt": 62.0,
      "base_freight": 279.0,
      "currency": "USD"
    }
  ],
  "total": 2
}

billable_rt is at least the contract's minimum: Pacific CFS Lines charges no less than 2 RT, so a 1 CBM shipment would still pay for 2. LCL prices are base ocean freight only; surcharges aren't included.

An empty items list isn't an error. It means no LCL contract covers the lane.