Quickstart

Run a first rate search, from Chicago to Shanghai, with your organization's contracts. It takes about five minutes.

The examples on this site come from the sandbox's Test Client organization: a Chicago forwarder with a ZIM contract for US exports. Your own searches return your organization's contracts.

Get an API key

An admin of your organization signs in to HighQube and opens Control Panel → API Keys, then chooses Create key:

Name: what the key is for, such as "Website rate widget".
Permissions: Read rates & surcharges is enough for this guide.
Expiry: how long the key lasts. You can roll it to a new key before then.

The key is shown once, so copy it straight into your password manager or secret store.

Keep it out of your code

Store the key in an environment variable, never in source code:

export HIGHQUBE_API_KEY="hq_test_..."

Search rates

Send the key in the Authorization header. routes is a JSON list of lanes, each with UN/LOCODE port codes: USCHI is Chicago and CNSGH is Shanghai.

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

import json
import os

import requests

response = requests.get(
    "https://api-dev.highqube.ai/rate-search",
    headers={"Authorization": f"Bearer {os.environ['HIGHQUBE_API_KEY']}"},
    params={
        "routes": json.dumps([{"origin": "USCHI", "destination": "CNSGH"}]),
        "containerSizes": ["20", "40HC"],
        "limitToTopN": 2,
        "sortBy": "40HC",
        "sortOrder": "asc",
    },
    timeout=30,
)
response.raise_for_status()

for rate in response.json()["data"]["items"]:
    print(rate["carrier"], rate["originVia"], rate["rates"]["40' HC"])

const params = new URLSearchParams({
  routes: JSON.stringify([{ origin: "USCHI", destination: "CNSGH" }]),
  limitToTopN: "2",
  sortBy: "40HC",
  sortOrder: "asc",
});
params.append("containerSizes", "20");
params.append("containerSizes", "40HC");

const response = await fetch(`https://api-dev.highqube.ai/rate-search?${params}`, {
  headers: { Authorization: `Bearer ${process.env.HIGHQUBE_API_KEY}` },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);

const { data } = await response.json();
for (const rate of data.items) console.log(rate.carrier, rate.originVia, rate.rates["40' HC"]);

Read the result

Each item is one carrier's rate on a lane, for one routing and equipment type. Here is the first of the two, with some fields left out:

{
  "success": true,
  "message": "Rate search completed successfully",
  "data": {
    "items": [
      {
        "extracted_group_id": "373464df73e9342f",
        "carrier": "ZIM",
        "origin": "USCHI",
        "originCity": "Chicago, IL (USCHI)",
        "originVia": "USORF",
        "destination": "CNSGH",
        "destinationCity": "Shanghai, CN (CNSGH)",
        "commodity": "FAK",
        "type": "Dry",
        "rates": { "20'": 409.0, "40'": null, "40' HC": 572.0, "45'": null, "48'": null, "53'": null },
        "currency": "USD",
        "effective": "10/01/2026",
        "expiration": "09/30/2027",
        "remarks": ["EXCLUDING HAZARDOUS CLASS 1, 2, 4.2 (UN3341), 5 % 7; SUBJECT TO HAZARDOUS APPROVAL"],
        "pricingComplete": false,
        "unpricedCharges": {
          "40' HC": [
            { "code": "BLF", "name": null, "scope": "all", "reason": "route_not_covered", "conditional": false },
            { "code": "IMS", "name": null, "scope": "all", "reason": "route_not_covered", "conditional": false },
            { "code": "NBF", "name": null, "scope": "all", "reason": "route_not_covered", "conditional": false }
          ]
        }
      }
    ],
    "total": 2
  }
}

rates is the price per container size in USD: ocean freight plus every surcharge HighQube could price. null means the contract has no rate for that size.
originVia is the port the container sails from. Chicago is inland, so ZIM takes it by rail to Norfolk (USORF) first. The second result is the same price by way of New York (USNYC).
pricingComplete: false means the contract says more surcharges apply than rates includes. unpricedCharges names them and says why: here no published tariff covers the route. Show these to whoever books the shipment.
remarks are the contract's own conditions for the rate.

To see the surcharges behind a price, pass its extracted_group_id to Get a rate's surcharges.

Build it with your AI assistant

Coding assistants such as Claude, Cursor or Copilot can read the whole API from its description. Paste this to start:

A rate search client

Read the HighQube API description at https://api-dev.highqube.ai/apis/public-openapi.json.
Write a small client for GET /rate-search in my project's language. Read the API key from the
HIGHQUBE_API_KEY environment variable and send it as "Authorization: Bearer <key>". Pass routes
as a JSON list of {origin, destination} UN/LOCODEs. Return each result's carrier, originVia,
rates per container size, and pricingComplete with unpricedCharges. On 429, wait for the
Retry-After header before trying again. Don't log the key.

Don't know a port's code? Look it up by name.
Pricing door to port, or a shipment smaller than a container? Price a shipment.
Building something that runs on its own? Read Errors and Rate limits before going live.
Every endpoint, with a Test request button: API reference.

Introduction

API keys

Quickstart

Build it with your AI assistant

Next