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
hs4
string | null

4-digit HS heading: rank importers of containers carrying it. Any other value returns 400. Use commodities/search to find one.

Maximum string length: 10
Example:

"0306"

port_of_discharge
string | null

Substring of a US port name.

Maximum string length: 200
Example:

"savannah"

origin_country
string | null

Substring of an origin country.

Maximum string length: 200
Example:

"vietnam"

months
integer
default:12

Full calendar months ending last month.

Required range: 1 <= x <= 60
limit
integer
default:20

Maximum importers to return.

Required range: 1 <= x <= 100

Response

OK

since
string
required

First month of the period (inclusive).

Example:

"2025-10"

until
string
required

Last month of the period (inclusive).

Example:

"2026-09"

ranked_by
string
required

The measure the ranking uses.

Example:

"containers"

filters
object
required

The filters that were applied.

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.

importers
object[]
required

Importers in descending order. The list does not distinguish forwarders from cargo owners and does not give each company's total volume; use companies/search for those.