> ## Documentation Index > Fetch the complete documentation index at: https://terminal49-feat-trade-intel-sdk.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Rank importers > Rank US importers by physical containers for an HS4 heading, port of discharge, or origin country over full calendar months. ## OpenAPI ````yaml post /trade_intel/importers/top openapi: 3.0.0 info: title: Terminal49 API Reference version: 0.2.0 contact: name: Terminal49 API support url: https://www.terminal49.com email: support@terminal49.com description: >- The Terminal 49 API offers a convenient way to programmatically track your shipments from origin to destination. Please enter your API key into the "Variables" tab before using these endpoints within Postman. x-label: Beta termsOfService: https://www.terminal49.com/terms servers: - url: https://api.terminal49.com/v2 description: Production security: - authorization: [] tags: - name: Containers - name: Custom Field Definitions - name: Custom Field Options - name: Custom Fields - name: Shipments - name: Locations - name: Events - name: Tracking Requests - name: Webhooks - name: Webhook Notifications - name: Ports - name: Metro Areas - name: Terminals - name: Routing (Paid) - name: Documents - name: Email Submissions - name: Document Schemas - name: Search - name: Parties - name: Trade Intelligence description: >- Trade intelligence answers questions about who imports what into the US, from where, on which carriers, and how that changes over time. The data is US import bill-of-lading records (US Customs vessel manifests): every ocean container landed at a US port (plus US-bound cargo landed at Vancouver, BC) from January 2022 to today, refreshed daily. It does not include air freight, exports, or domestic moves. **Access.** Trade intelligence is enabled per account. Accounts without it receive `403 Forbidden` with `{"error": "Trade intelligence is not enabled for this account"}`; contact sales@terminal49.com to enable it. Requests are limited to roughly 120 per minute per account (`429` with `{"error": "Rate limit exceeded; retry in a minute"}`). **Format.** These endpoints accept and return plain JSON, not JSON:API. Send `Content-Type: application/json` on `POST` requests and authenticate exactly like every other v2 endpoint (`Authorization: Token YOUR_API_KEY`). **Typical flow.** Resolve a name or product first, then analyze: `companies/search` or `commodities/search` give you the exact `company_name` or `hs4` to pass to `companies/profile`, `importers/top`, `trends`, or `breakdown`. Container and bill of lading numbers go straight to `containers/lookup` and `bills_of_lading/lookup`. **Reading the numbers.** - **Volume is physical containers.** Each box is counted once, even when it appears on several bills of lading. A container carrying several HS codes counts once per code and companies can share containers, so do not add volumes across HS codes or companies; take market totals from `trends` or `breakdown` without a company filter. - **Estimated value is a modelled USD estimate**, not the declared customs value. - **The current month is partial.** `trends` and `breakdown` include it by default; `companies/profile` and `importers/top` use full calendar months. Compare full months against the same months a year earlier. - **Absent volume is not small volume.** Importers can ask US Customs to withhold their name from manifests, and much large-retail freight is booked under forwarders or suppliers. Treat a company's figures as a floor, never as its size. - **One company, many names.** Company names are normalized but split by state, and large importers use several names (distribution, merchandising, and DC entities). Related entities are separate companies; report them separately. `companies/search` ranks by match quality, not by size. - **Companies are the consignee or notify party on the bill.** Forwarders, NVOCCs, and customs brokers appear alongside cargo owners. A high notify-party share, or LOGISTICS, FREIGHT, SHIPPING, CUSTOMS, or BROKERAGE in the name, usually indicates a logistics provider. - **Carriers, countries, and ports use the manifests' spellings**, and carriers appear under spelling variants (for example `CMA CGM` and `CMA CGM AMERICA LLC`). Filter with substrings and merge variants before computing shares. - **HS4 descriptions are truncated.** Check `common_goods` from `commodities/search` before relying on a code. paths: /trade_intel/importers/top: post: tags: - Trade Intelligence summary: Rank importers description: >- Rank US importers by physical containers over `months` full calendar months, optionally restricted to one HS4 heading, a port of discharge, or an origin country. Estimated value is included when `hs4` is given. The ranking is built from US import bill-of-lading records (US Customs vessel manifests), so it lists consignees and notify parties: forwarders, NVOCCs, and customs brokers appear alongside cargo owners, and the response does not say which is which or give each company's total volume. Run `companies/search` on shortlisted names to get the consignee/notify split and totals. Large importers can be split across several names and states, and some have their names withheld from manifests, so absence from the ranking does not mean low volume. operationId: post-trade-intel-importers-top requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TradeIntelTopImportersRequest' examples: By HS heading: value: hs4: '0306' months: 3 By port, last month: value: months: 1 port_of_discharge: savannah responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TradeIntelTopImporters' example: since: 2025-10 until: 2026-09 ranked_by: containers filters: hs4: '9401' notes: - volume is physical containers, each counted once importers: - company_name: EXAMPLE OUTDOOR SUPPLY states: - GA - CA containers: 800 teus: 1500 estimated_value: 31000000 '400': $ref: '#/components/responses/TradeIntelBadRequest' '401': $ref: '#/components/responses/TradeIntelUnauthorized' '403': $ref: '#/components/responses/TradeIntelNotEnabled' '422': $ref: '#/components/responses/TradeIntelValidationFailed' '429': $ref: '#/components/responses/TradeIntelRateLimited' '502': $ref: '#/components/responses/TradeIntelUnavailable' '504': $ref: '#/components/responses/TradeIntelUnavailable' components: schemas: TradeIntelTopImportersRequest: type: object properties: hs4: type: string description: >- 4-digit HS heading: rank importers of containers carrying it. Any other value returns `400`. Use `commodities/search` to find one. maxLength: 10 example: '0306' nullable: true port_of_discharge: type: string description: Substring of a US port name. maxLength: 200 example: savannah nullable: true origin_country: type: string description: Substring of an origin country. maxLength: 200 example: vietnam nullable: true months: type: integer description: Full calendar months ending last month. minimum: 1 maximum: 60 default: 12 limit: type: integer description: Maximum importers to return. minimum: 1 maximum: 100 default: 20 TradeIntelTopImporters: type: object properties: since: type: string description: First month of the period (inclusive). example: 2025-10 until: type: string description: Last month of the period (inclusive). example: 2026-09 ranked_by: type: string description: The measure the ranking uses. example: containers filters: type: object description: The filters that were applied. properties: hs4: type: string port_of_discharge: type: string origin_country: type: string notes: type: array items: type: string description: >- 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: type: array items: $ref: '#/components/schemas/TradeIntelTopImporter' description: >- 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. required: - since - until - ranked_by - filters - notes - importers TradeIntelTopImporter: type: object properties: company_name: type: string description: >- Normalized company name; pass it to `companies/search` or `companies/profile`. states: type: array items: type: string description: US states the company's volume is split across. containers: type: integer description: Physical containers matching the filters. teus: type: number description: Twenty-foot equivalent units. estimated_value: type: number description: Modelled USD estimate; present when `hs4` was given. required: - company_name - states - containers - teus TradeIntelError: type: object description: >- Plain JSON error body returned by trade intelligence endpoints (not JSON:API). properties: error: type: string description: >- What was wrong with the request, or why trade intelligence could not answer. example: >- hs4 must be a 4-digit HS code, e.g. '0306'; use commodities/search to find one required: - error TradeIntelValidationError: type: object description: >- Schema validation failure (for example a `limit` above its maximum or a malformed month). properties: detail: type: array items: type: object properties: loc: type: array items: oneOf: - type: string - type: integer description: Path to the offending field, for example `["body", "limit"]`. msg: type: string description: Human-readable validation message. type: type: string description: Validation error type, for example `less_than_equal`. required: - loc - msg - type description: One entry per field that failed schema validation. required: - detail responses: TradeIntelBadRequest: description: >- Bad Request - the request was understood but a value is invalid, for example an `hs4` that is not a 4-digit HS code. content: application/json: schema: $ref: '#/components/schemas/TradeIntelError' example: error: >- hs4 must be a 4-digit HS code, e.g. '0306'; use commodities/search to find one TradeIntelUnauthorized: description: Unauthorized - the API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/TradeIntelError' example: error: Terminal49 API key could not be verified TradeIntelNotEnabled: description: >- Forbidden - trade intelligence is not enabled for this account. Contact sales@terminal49.com. content: application/json: schema: $ref: '#/components/schemas/TradeIntelError' example: error: Trade intelligence is not enabled for this account TradeIntelValidationFailed: description: >- Unprocessable Entity - the body failed schema validation (a value out of range, a malformed month, or an unknown enum value). content: application/json: schema: $ref: '#/components/schemas/TradeIntelValidationError' example: detail: - loc: - body - limit msg: Input should be less than or equal to 50 type: less_than_equal TradeIntelRateLimited: description: >- Too Many Requests - about 120 requests per minute are allowed per account. content: application/json: schema: $ref: '#/components/schemas/TradeIntelError' example: error: Rate limit exceeded; retry in a minute TradeIntelUnavailable: description: >- Bad Gateway or Gateway Timeout - trade intelligence is temporarily unavailable; retry shortly. content: application/json: schema: $ref: '#/components/schemas/TradeIntelError' example: error: Trade intelligence is temporarily unavailable; try again shortly securitySchemes: authorization: name: Authorization type: apiKey in: header description: >- Use a Terminal49 API key in the `Authorization` header with the `Token` prefix. `Authorization: Token YOUR_API_KEY` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.