Get public-data benchmark bands for a lane and HS code

GET/benchmarks/{lane}/{hs}$0.05 per call

Returns the percentile bands for one lane and HS code, with no shipment and no score. Served from public-domain data (U.S. Census) whatever the caller's plan. The destination must be a U.S. port or US. Resolution falls back from customs district to country, region and HS4, and the response says which level it used and how confident it is.

Parameters

Name	In	Type	Description
lanerequired	path	string	Lane key `{origin}-{destination}-{mode}`, e.g. CNSHA-USLAX-ocean_container or CN-US-air.
hsrequired	path	string	HS code, 4–10 digits. 8–10 digits are truncated to 6 (reason Q03).
measuresoptional	query	string	Comma-separated subset of measures. Default all.
windowoptional	query	string	Benchmark window. Only 24m is built in this release; 12m and 36m return 422 `unsupported_window`. one of "12m", "24m", "36m" · default "24m"
as_ofoptional	query	string	Return the benchmark version current on this date (audit replay). format date
resolutionoptional	query	string	one of "auto", "exact" · default "auto"

Response fields

Field	Type	Description
id	string
lane_requested	string
lane_used	string	The lane the benchmark was built for. A district benchmark is written CN-US:27-ocean_container.
hs_used	string
resolution	string
window	object
window.from	string
window.to	string
as_of	string
confidence	string
sources	array of string
district	object	Present when the benchmark is at customs-district level: the U.S. Customs district of unlading.
district.code	string
district.name	string or null
cells	object	The data behind the bands.
cells.n_cells	integer
cells.weight_kg_covered	number
next_refresh	string
object	string
hs_description	string
source_tier	string
measures	object

Fields are read from a real response captured 2026-11-04. Optional fields may be absent in other responses.

Errors

400 invalid request
401 missing or bad key
403 not in your plan
429 rate limited, see Retry-After
402 payment required
404 not found
500 server error, retry with backoff
503 temporarily unavailable
5xx retry with backoff

This endpoint reports errors as RFC 9457 problem details (application/problem+json) with a stable code and a request_id.

curl "https://api.compliancegrid.ai/benchmarks/CN-US-ocean_container/640399" \
  -H "Authorization: Bearer $CG_API_KEY"

Try it in the sandbox

Runs against sandbox.api.compliancegrid.ai with your own sandbox key, which stays in this browser. Sandbox responses are mock data. Get a free key.

Sandbox key

Remember for this tab

lane (path, required)

hs (path, required)

measures (query)

window (query)

as_of (query)

resolution (query)

Example response · captured from production 2026-11-04

{
  "id": "bm_2026-08_CN-US-ocean_container_640399",
  "lane_requested": "CN-US-ocean_container",
  "lane_used": "CN-US-ocean_container",
  "hs_used": "640399",
  "resolution": "country_pair",
  "window": {
    "from": "2024-09-01",
    "to": "2026-08-31"
  },
  "as_of": "2026-11-03",
  "next_refresh": null,
  "confidence": "high",
  "sources": [
    "us_census_imports_hs"
  ],
  "cells": {
    "n_cells": 571,
    "weight_kg_covered": 109352766
  },
  "object": "benchmark",
  "hs_description": "Other:",
  "source_tier": "public",
  "measures": {
    "freight_per_kg": {
      "unit": "USD/kg",
      "band": {
        "p5": 0.251287,
        "p10": 0.39781,
        "p25": 0.464254,
        "p50": 0.500509,
        "p75": 0.569831,
        "p90": 0.666855,
        "p95": 0.753766,
        "robust_sigma": 0.078263,
        "n_cells": 571,
        "weight_kg_covered": 109352766
      }
    },
    "freight_pct_of_value": {
      "unit": "%",
      "band": {
        "p5": 2.764528,
        "p10": 2.867785,
        "p25": 3.202857,
        "p50": 3.760077,
        "p75": 4.390064,
        "p90": 5.330824,
        "p95": 6.611085,
        "robust_sigma": 0.880064,
        "n_cells": 571,
        "weight_kg_covered": 109352766
      }
    },
    "value_per_kg": {
      "unit": "USD/kg",
      "band": {
        "p5": 4.741886,
        "p10": 10.318421,
        "p25": 12.020925,
        "p50": 13.915038,
        "p75": 15.597979,
        "p90": 16.276972,
        "p95": 16.900252,
        "robust_sigma": 2.651634,
        "n_cells": 571,
        "weight_kg_covered": 109352766
      }
    }
  }
}