> ## 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. # Search importers > Find US importers by name or by what they import, with 12-month container volumes, TEUs, estimated value, and top ports, origins, carriers, and commodities. ## OpenAPI ````yaml post /trade_intel/companies/search 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/companies/search: post: tags: - Trade Intelligence summary: Search importers description: >- Find US importers by name, by what they import, or both, from US import bill-of-lading records (US Customs vessel manifests). `name` is a fuzzy match (partial or misspelled names are fine); `imports` is a semantic match on product descriptions. With neither, the largest importers matching the other filters are returned. Each result carries 12-full-month containers (split by consignee and notify party), TEUs, estimated value, and top ports, origins, carriers, and HS4 headings. **Results are ranked by match quality, not size.** A fuzzy search for a well-known retailer can return a small, similarly named company above the retailer itself; check `containers` before choosing a row. Companies are split by state and large importers use several names, so look through the whole list before concluding a company is small. Importers can also have their names withheld from manifests, so absent volume does not mean low volume. Take `company_name` from a result and pass it unchanged to `companies/profile` for monthly history. operationId: post-trade-intel-companies-search requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TradeIntelCompanySearchRequest' examples: By name: value: name: home depot By product and state: value: imports: frozen shrimp state: FL limit: 5 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TradeIntelCompanySearchResponse' example: index: since_month: 2025-09 until_month_exclusive: 2026-09 months: 12 min_containers: 5 companies: 250000 hs_codes: 1200 facts_since_month: 2022-01 facts_until_exclusive: 2026-11 partial_month: 2026-10 mode: local facts_hash: 3f9c1a7e refreshed_since: '2026-10-01' fact_rows: lane_month: 1200000 company_month: 9800000 commodity_month: 6400000 hs_lane_month: 15000000 volume_measure: containers built_at: '2026-10-08T06:12:44Z' results: - company_name: EXAMPLE OUTDOOR SUPPLY company_state: GA containers: 1240 containers_as_consignee: 1180 containers_as_notify_party: 60 teus: 2310.5 estimated_value: 48200000 reefer_share: 0 first_month: 2025-09 last_month: 2026-08 top_ports: - name: SAVANNAH containers: 900 top_origins: - name: VIETNAM containers: 700 top_carriers: - name: MAERSK LINE containers: 500 top_commodities: - hs4: '9401' description: Seats (other than barber, dental, etc), and part estimated_value: 31000000 containers: 800 score: 0.97 '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: TradeIntelCompanySearchRequest: type: object description: >- Give `name`, `imports`, or both. With neither, lists the largest importers matching the filters. properties: name: type: string description: >- Company name; partial or misspelled is fine (fuzzy match). Results are ranked by match quality, not size, so a close but small match can outrank a large importer. maxLength: 200 example: home depot nullable: true imports: type: string description: What the company imports, in plain words (semantic match). maxLength: 200 example: frozen shrimp nullable: true state: type: string description: US state code of the importer. maxLength: 2 example: FL nullable: true port_of_discharge: type: string description: Substring of a US port name. maxLength: 200 example: Long Beach nullable: true origin_country: type: string description: Substring of an origin country. maxLength: 200 example: Vietnam nullable: true min_containers: type: integer description: Minimum containers in the index window. minimum: 1 nullable: true limit: type: integer description: Maximum results to return. minimum: 1 maximum: 50 default: 10 TradeIntelCompanySearchResponse: type: object properties: index: $ref: '#/components/schemas/TradeIntelMeta' results: type: array items: $ref: '#/components/schemas/TradeIntelCompanySearchResult' description: Matches ordered by `score`. required: - index - results TradeIntelMeta: type: object description: >- Index window, freshness, and counts. Also returned as `index` by `companies/search`. properties: since_month: type: string description: >- First month of the 12-full-month window that search results and rankings cover. example: 2025-09 until_month_exclusive: type: string description: Month after the last full month in the search window (exclusive). example: 2026-09 months: type: integer description: Number of full months in the search window. example: 12 min_containers: type: integer description: >- Minimum containers in the window for a company to be in the search index. example: 5 companies: type: integer description: Companies in the search index. example: 250000 hs_codes: type: integer description: HS4 codes in the search index. example: 1200 facts_since_month: type: string description: >- First month of history available to `companies/profile`, `importers/top`, `trends`, and `breakdown`. History starts in January 2022. example: 2022-01 facts_until_exclusive: type: string description: Month after the latest month with data (exclusive). example: 2026-11 partial_month: type: string description: >- The current calendar month, which is still being loaded and is incomplete. example: 2026-10 mode: type: string description: Serving mode of the index. example: local facts_hash: type: string description: >- Fingerprint of the current fact build. It changes whenever the data is refreshed. refreshed_since: type: string description: Start of the period covered by the most recent daily refresh. example: '2026-10-01' fact_rows: $ref: '#/components/schemas/TradeIntelFactRowCounts' volume_measure: type: string description: >- Unit of every `containers` figure: physical containers, each counted once. example: containers built_at: type: string description: When the index was built. format: date-time example: '2026-10-08T06:12:44Z' required: - since_month - until_month_exclusive - months - min_containers - companies - hs_codes - facts_since_month - facts_until_exclusive - partial_month - mode - facts_hash - refreshed_since - fact_rows - volume_measure - built_at TradeIntelCompanySearchResult: type: object properties: company_name: type: string description: Normalized company name. Pass it unchanged to `companies/profile`. example: CATERPILLAR company_state: type: string description: US state this row covers, or `null` when the row spans all states. example: IL nullable: true containers: type: integer description: Physical containers in the index window. containers_as_consignee: type: integer description: Containers where the company is the consignee. containers_as_notify_party: type: integer description: >- Containers where the company is the notify party. A share above about 70% usually indicates a logistics provider rather than the cargo owner. teus: type: number description: Twenty-foot equivalent units. estimated_value: type: number description: Modelled USD estimate, not declared customs value. reefer_share: type: number description: Share of containers that were refrigerated, 0 to 1. first_month: type: string description: First month with volume in the window. example: 2025-09 last_month: type: string description: Last month with volume in the window. example: 2026-08 top_ports: type: array items: $ref: '#/components/schemas/TradeIntelNamedContainers' description: Top US ports of discharge. top_origins: type: array items: $ref: '#/components/schemas/TradeIntelNamedContainers' description: Top origin countries. top_carriers: type: array items: $ref: '#/components/schemas/TradeIntelNamedContainers' description: Top ocean carriers. top_commodities: type: array items: $ref: '#/components/schemas/TradeIntelCommodityVolume' description: Top HS4 headings. score: type: number description: Match quality; higher is better. Not a measure of size. required: - company_name - company_state - containers - containers_as_consignee - containers_as_notify_party - teus - estimated_value - reefer_share - first_month - last_month - top_ports - top_origins - top_carriers - top_commodities - score 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 TradeIntelFactRowCounts: type: object description: Row counts of the monthly fact tables behind the analytics endpoints. properties: lane_month: type: integer description: Rows in the lane-by-month fact table. company_month: type: integer description: Rows in the company-by-month fact table. commodity_month: type: integer description: Rows in the commodity-by-month fact table. hs_lane_month: type: integer description: Rows in the HS-code-by-lane-by-month fact table. required: - lane_month - company_month - commodity_month - hs_lane_month TradeIntelNamedContainers: type: object properties: name: type: string description: Port, country, or carrier name as spelled on manifests. containers: type: integer description: Physical containers. required: - name - containers TradeIntelCommodityVolume: type: object properties: hs4: type: string description: 4-digit HS heading. example: '9401' description: type: string description: >- HS heading description. Descriptions are truncated; check `common_goods` from `commodities/search` before relying on one. containers: type: integer description: Physical containers carrying this heading. estimated_value: type: number description: Modelled USD estimate, not declared customs value. required: - hs4 - description - containers - estimated_value 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.