> ## 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. # Get an import breakdown > Get nested totals with subtotals at every level of a dimension hierarchy such as region, country, and port, or HS chapter and heading. ## OpenAPI ````yaml post /trade_intel/breakdown 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/breakdown: post: tags: - Trade Intelligence summary: Get an import breakdown description: >- Nested totals over a dimension hierarchy (for example region > country > port, or HS2 > HS4), with a grand total at level 0 and subtotals at every level, keeping the top N children under each parent. Volume is physical containers, each counted once; estimated value is a modelled USD estimate. Defaults to the last 12 months including the current, partial month; set `since` and `until` to full months for comparisons. The `company` filter is a substring match. Countries, ports, and carriers use the manifests' spellings, so filter with substrings and merge carrier variants before computing shares. Do not add values across HS codes or companies; use a breakdown without a `company` filter for market totals. operationId: post-trade-intel-breakdown requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TradeIntelBreakdownRequest' examples: Region, country, port: value: dims: - origin_region - origin_country - pod filters: hs2: '03' top: 5 Value by HS chapter and heading: value: dims: - hs2 - hs4 filters: pod: savannah measure: estimated_value responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TradeIntelBreakdown' example: measure: containers dims: - pod_coast - pod filters: hs4: '9401' since: 2026-01 until: 2026-06 fact: hs_lane_month notes: - volume is physical containers, each counted once rows: - level: 0 value: 60000 - level: 1 pod_coast: WEST value: 32000 - level: 2 pod_coast: WEST pod: LOS ANGELES value: 18000 - level: 2 pod_coast: WEST pod: LONG BEACH value: 14000 - level: 1 pod_coast: EAST value: 28000 '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: TradeIntelBreakdownRequest: type: object properties: dims: type: array items: $ref: '#/components/schemas/TradeIntelDimension' description: >- Hierarchy, outermost first, for example `["origin_region", "origin_country", "pod"]` or `["hs2", "hs4"]`. minItems: 1 maxItems: 3 measure: $ref: '#/components/schemas/TradeIntelMeasure' filters: $ref: '#/components/schemas/TradeIntelFilters' since: type: string description: First month, `YYYY-MM` inclusive. Defaults to 12 months ago. pattern: ^\d{4}-(0[1-9]|1[0-2])$ example: 2025-10 nullable: true until: type: string description: >- Last month, `YYYY-MM` inclusive. Defaults to the current, partial month. pattern: ^\d{4}-(0[1-9]|1[0-2])$ example: 2026-09 nullable: true top: type: integer description: Top N children under each parent. minimum: 1 maximum: 50 default: 10 required: - dims TradeIntelBreakdown: type: object properties: measure: $ref: '#/components/schemas/TradeIntelMeasure' dims: type: array items: $ref: '#/components/schemas/TradeIntelDimension' description: The hierarchy, outermost first. filters: $ref: '#/components/schemas/TradeIntelFilters' since: type: string description: First month (inclusive). example: 2025-10 until: type: string description: Last month (inclusive). example: 2026-10 fact: type: string description: Name of the fact table the rollup was computed from. 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. rows: type: array items: $ref: '#/components/schemas/TradeIntelBreakdownRow' description: >- Grand total first, then subtotals per level, keeping the top N children under each parent. required: - measure - dims - filters - since - until - fact - notes - rows TradeIntelDimension: type: string enum: - carrier - scac - origin_country - origin_region - pod - pod_coast - dest_state - reefer - pol - pol_country - container_type - company - company_state - hs4 - hs2 description: >- A dimension to group or break down by. `pod` is the US port of discharge, `pol` the foreign port of lading, `pod_coast` is `EAST`, `WEST`, or `GULF`, `dest_state` is the destination US state, `company_state` the importer's state, `hs2` and `hs4` are HS chapter and heading codes, and `reefer` splits refrigerated from dry containers. TradeIntelMeasure: type: string enum: - containers - teus - estimated_value default: containers description: >- What to measure. `containers` counts physical containers (each box once). `teus` sums twenty-foot equivalent units. `estimated_value` sums modelled USD estimates, not declared customs values. TradeIntelFilters: type: object description: >- Filters for `trends` and `breakdown`. Name-like fields match case-insensitive substrings; codes (`hs4`, `hs2`, `pod_coast`, states, `scac`) match exactly. Omit a field to leave it unfiltered. properties: company: type: string description: >- Case-insensitive **substring** match on the company name, so `IKEA` also matches `IKEA SUPPLY AG`. For one company's own figures use `companies/profile`, which matches the exact name. maxLength: 200 example: CATERPILLAR nullable: true company_state: type: string description: Two-letter US state of the importer; exact match. maxLength: 2 example: IL nullable: true hs4: type: string description: >- 4-digit HS heading; exact match. Use `commodities/search` to find one. pattern: ^\d{4}$ example: '0306' nullable: true hs2: type: string description: 2-digit HS chapter; exact match. pattern: ^\d{2}$ example: '03' nullable: true carrier: type: string description: >- Substring of the ocean carrier name as it appears on manifests. Carriers appear under spelling variants; prefer `scac` for an exact match. maxLength: 200 example: MAERSK nullable: true scac: type: string description: Carrier SCAC; exact match. maxLength: 4 example: MAEU nullable: true origin_country: type: string description: >- Substring of the origin country as spelled on manifests, for example `china` matches `PEOPLES REP OF CHINA`. maxLength: 200 example: vietnam nullable: true origin_region: type: string description: Substring of the origin region. maxLength: 200 nullable: true pol: type: string description: Substring of the foreign port of lading. maxLength: 200 nullable: true pol_country: type: string description: Substring of the port-of-lading country. maxLength: 200 nullable: true pod: type: string description: Substring of the US port of discharge. maxLength: 200 example: savannah nullable: true pod_coast: type: string enum: - EAST - WEST - GULF description: US coast of the port of discharge; exact match. nullable: true dest_state: type: string description: Two-letter destination US state; exact match. maxLength: 2 example: TX nullable: true container_type: type: string description: Substring of the container type description. maxLength: 200 nullable: true reefer: type: boolean description: Only refrigerated (`true`) or only dry (`false`) containers. nullable: true TradeIntelBreakdownRow: type: object description: >- One row of the rollup. Besides `level` and `value`, each row carries one property per dimension down to its level (for example `pod_coast` and `pod`). properties: level: type: integer description: >- Depth in the hierarchy: `0` is the grand total, `1` a subtotal for the first dimension, and so on. A row at level N carries a property for each of the first N dimensions. value: type: number description: The measure for this row. required: - level - value additionalProperties: true 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.