Get an import breakdown

Get nested totals with subtotals at every level of a dimension hierarchy such as region, country, and port, or HS chapter and heading.

POST /trade_intel/breakdown

cURL

Region, country, port

curl --request POST \
  --url https://api.terminal49.com/v2/trade_intel/breakdown \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dims": [
    "origin_region",
    "origin_country",
    "pod"
  ],
  "filters": {
    "hs2": "03"
  },
  "top": 5
}
'

200

{
  "measure": "containers",
  "dims": [
    "pod_coast",
    "pod"
  ],
  "filters": {
    "hs4": "9401"
  },
  "since": "2026-01",
  "until": "2026-06",
  "fact": "hs_lane_month",
  "notes": [
    "volume is physical containers, each counted once"
  ],
  "rows": [
    {
      "level": 0,
      "value": 60000
    },
    {
      "level": 1,
      "pod_coast": "WEST",
      "value": 32000
    },
    {
      "level": 2,
      "pod_coast": "WEST",
      "pod": "LOS ANGELES",
      "value": 18000
    },
    {
      "level": 2,
      "pod_coast": "WEST",
      "pod": "LONG BEACH",
      "value": 14000
    },
    {
      "level": 1,
      "pod_coast": "EAST",
      "value": 28000
    }
  ]
}

Authorizations

Authorization · string · header · required

Use a Terminal49 API key in the Authorization header with the Token prefix.

Authorization: Token YOUR_API_KEY

Body

application/json

dims · enum<string>[] · required

Hierarchy, outermost first, for example ["origin_region", "origin_country", "pod"] or ["hs2", "hs4"].

Required array length: 1 - 3 elements

A dimension to group or break down by. pod is the US port of discharge, pol the foreign port of lading, pod_coast is EAST, WEST, or GULF, dest_state is the destination US state, company_state the importer's state, hs2 and hs4 are HS chapter and heading codes, and reefer splits refrigerated from dry containers.

Available options: carrier, scac, origin_country, origin_region, pod, pod_coast, dest_state, reefer, pol, pol_country, container_type, company, company_state, hs4, hs2

measure · enum<string> · default: containers

What to measure. containers counts physical containers (each box once). teus sums twenty-foot equivalent units. estimated_value sums modelled USD estimates, not declared customs values.

Available options: containers, teus, estimated_value

filters · object

Filters for trends and breakdown. Name-like fields match case-insensitive substrings; codes (hs4, hs2, pod_coast, states, scac) match exactly. Omit a field to leave it unfiltered.

Show child attributes

since · string | null

First month, YYYY-MM inclusive. Defaults to 12 months ago.

Pattern: ^\d{4}-(0[1-9]|1[0-2])$

Example:

"2025-10"

until · string | null

Last month, YYYY-MM inclusive. Defaults to the current, partial month.

Pattern: ^\d{4}-(0[1-9]|1[0-2])$

Example:

"2026-09"

top · integer · default: 10

Top N children under each parent.

Required range: 1 <= x <= 50

Response

200

application/json

OK

measure · enum<string> · default: containers · required

What to measure. containers counts physical containers (each box once). teus sums twenty-foot equivalent units. estimated_value sums modelled USD estimates, not declared customs values.

Available options: containers, teus, estimated_value

dims · enum<string>[] · required

The hierarchy, outermost first.

A dimension to group or break down by. pod is the US port of discharge, pol the foreign port of lading, pod_coast is EAST, WEST, or GULF, dest_state is the destination US state, company_state the importer's state, hs2 and hs4 are HS chapter and heading codes, and reefer splits refrigerated from dry containers.

Available options: carrier, scac, origin_country, origin_region, pod, pod_coast, dest_state, reefer, pol, pol_country, container_type, company, company_state, hs4, hs2

filters · object · required

Filters for trends and breakdown. Name-like fields match case-insensitive substrings; codes (hs4, hs2, pod_coast, states, scac) match exactly. Omit a field to leave it unfiltered.

Show child attributes

since · string · required

First month (inclusive).

Example:

"2025-10"

until · string · required

Last month (inclusive).

Example:

"2026-10"

fact · string · required

Name of the fact table the rollup was computed from.

notes · string[] · required

Counting caveats that apply to this response, for example that volume is physical containers or that the window includes a partial month. Surface these to end users.

rows · object[] · required

Grand total first, then subtotals per level, keeping the top N children under each parent.

Show child attributes