Skip to main content
POST

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
​
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
​
group_by
enum<string>[]

Split the series by up to two dimensions, keeping the top top groups.

Maximum array length: 2

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. Lane dimensions (pol, pol_country, container_type) can't be combined with company or product dimensions (company, company_state, hs4, hs2) in one request, whether as dimensions or filters, and estimated_value isn't available by lane dimension; such requests return 400 with the reason.

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

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. Lane dimensions (pol, pol_country, container_type) can't be combined with company or product dimensions (company, company_state, hs4, hs2) in one request, whether as dimensions or filters, and estimated_value isn't available by lane dimension; such requests return 400 with the reason.

​
interval
enum<string>
default:month

Bucket size for a time series. Every period is labelled by its first month, YYYY-MM: a quarter starting in April 2026 is 2026-04 and the year 2026 is 2026-01.

Available options:
month,
quarter,
year
​
since
string | null

First period, YYYY-MM inclusive. Defaults to 23 months before until, so the default series covers 24 months; history is available back to January 2022 (facts_since_month in meta).

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

"2024-01"

​
until
string | null

Last period, 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

Keep the top N groups by total over the range.

Required range: 1 <= x <= 50

Response

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
​
interval
enum<string>
default:month
required

Bucket size for a time series. Every period is labelled by its first month, YYYY-MM: a quarter starting in April 2026 is 2026-04 and the year 2026 is 2026-01.

Available options:
month,
quarter,
year
​
since
string
required

First period (inclusive).

Example:

"2024-10"

​
until
string
required

Last period (inclusive).

Example:

"2026-10"

​
group_by
enum<string>[]
required

The dimensions the series is split by.

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. Lane dimensions (pol, pol_country, container_type) can't be combined with company or product dimensions (company, company_state, hs4, hs2) in one request, whether as dimensions or filters, and estimated_value isn't available by lane dimension; such requests return 400 with the reason.

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. Lane dimensions (pol, pol_country, container_type) can't be combined with company or product dimensions (company, company_state, hs4, hs2) in one request, whether as dimensions or filters, and estimated_value isn't available by lane dimension; such requests return 400 with the reason.

​
fact
string
required

Name of the fact table the series 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.

​
series
object[]
required

Points ordered by period, then by group.