> ## 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 commodities > Resolve a product description or HS code prefix to 4-digit HS headings with common goods, estimated import value, and importer counts. ## OpenAPI ````yaml post /trade_intel/commodities/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/commodities/search: post: tags: - Trade Intelligence summary: Search commodities description: >- Resolve a product description, or an HS code prefix, to 4-digit HS headings. Each result carries the heading description, goods commonly declared under it on bills of lading, 12-month estimated import value, and the number of importing companies. HS heading descriptions are truncated and headings are broader than everyday product names (HS 0306 covers all frozen crustaceans, not only shrimp), so check `common_goods` before relying on a code. Feed `hs4` into `importers/top` or into the `hs4` filter of `trends` and `breakdown`. operationId: post-trade-intel-commodities-search requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TradeIntelCommoditySearchRequest' examples: By description: value: query: laptops By HS prefix: value: query: '8541' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TradeIntelCommoditySearchResponse' example: results: - hs4: '9401' description: Seats (other than barber, dental, etc), and part estimated_value: 9800000000 companies: 4200 common_goods: - office chairs - sofas - car seats score: 0.91 '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: TradeIntelCommoditySearchRequest: type: object properties: query: type: string description: Product description in plain words, or an HS code prefix. minLength: 1 maxLength: 200 example: office chairs limit: type: integer description: Maximum results to return. minimum: 1 maximum: 50 default: 10 required: - query TradeIntelCommoditySearchResponse: type: object properties: results: type: array items: $ref: '#/components/schemas/TradeIntelCommoditySearchResult' description: Matches ordered by `score`. required: - results TradeIntelCommoditySearchResult: type: object properties: hs4: type: string description: >- 4-digit HS heading. Pass it to `importers/top` or as an `hs4` filter. example: '9401' description: type: string description: HS heading description (truncated). estimated_value: type: number description: 12-month modelled USD import value, not declared customs value. companies: type: integer description: Companies importing this heading in the index window. common_goods: type: array items: type: string description: >- Goods commonly declared under this heading on bills of lading. Use these to confirm the heading covers what you mean; HS 0306, for example, covers all frozen crustaceans, not only shrimp. score: type: number description: Match quality; higher is better. required: - hs4 - description - estimated_value - companies - common_goods - 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 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.