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.

Pattern: ^\d{4}$
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, keyed by the names the service uses: a port_of_discharge request comes back as pod. Only filters that were given appear.

​
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.