> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindcase.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Customs Trade Statistics API

> Ranks and value shares of customs trade aggregated by HS code, origin country, destination country, or time period. Covers customs filings and trade statistics from about 95 countries, including the United States, Mexico, Brazil, Colombia, India, Indonesia, Vietnam, Pakistan, Russia, Turkey, the UK and the EU.

`POST /v1/data/customs/trade-stats/run`

**Pricing:** $0.04 per aggregate bucket ($35.00 per 1,000).

## Request

Send the inputs under `params`. Only the keys below are accepted; any other key returns `422 invalid_params`.

**groupBy** `string` (default: hsCode)

How to bucket matching trade records: by HS code, origin country, destination country, or time period.

Allowed values: `hsCode` (HS code), `originCountry` (Origin country), `destinationCountry` (Destination country), `period` (Time period).

**direction** `string` (default: imports)

Whether to aggregate import records or export records.

Allowed values: `imports` (Imports), `exports` (Exports).

**product** `string[]`

Product description keywords to match; one of product, HS code, importer or exporter is required.

**hsCode** `string`

A customs HS code of 4 or more digits (a 2-digit chapter code needs another filter alongside it).

**importer** `string`

An importing company name to filter records by.

**exporter** `string`

An exporting company name to filter records by.

**originCountry** `string[]`

Restrict to these origin countries, as ISO 3166 alpha-3 codes (e.g. COL, USA). Pick from the list; English country names are also accepted.

248 allowed values, for example `AFG` (Afghanistan), `ALA` (Aland Islands), `ALB` (Albania), `DZA` (Algeria), `ASM` (American Samoa), `AND` (Andorra), `AGO` (Angola), `AIA` (Anguilla), `ATA` (Antarctica), `ATG` (Antigua and Barbuda). Fetch the full list with `GET /v1/data/customs/trade-stats?expand=options`.

**destinationCountry** `string[]`

Restrict to these destination countries, as ISO 3166 alpha-3 codes (e.g. COL, USA). Pick from the list; English country names are also accepted.

248 allowed values, for example `AFG` (Afghanistan), `ALA` (Aland Islands), `ALB` (Albania), `DZA` (Algeria), `ASM` (American Samoa), `AND` (Andorra), `AGO` (Angola), `AIA` (Anguilla), `ATA` (Antarctica), `ATG` (Antigua and Barbuda). Fetch the full list with `GET /v1/data/customs/trade-stats?expand=options`.

**startDate** `date`

Start of the query window, defaults to one year before the end date.

**endDate** `date`

End of the query window, defaults to today.

**periodUnit** `string` (default: months)

Bucket size used only when grouping by time period.

Allowed values: `months` (Months), `quarters` (Quarters), `years` (Years).

**maxResults** `integer` (default: 100)

How many aggregate buckets to return in total. Defaults to 100; use 0 for all.

Max `100`.

## Example

```bash cURL theme={null}
curl -X POST "https://api.mindcase.co/v1/data/customs/trade-stats/run?wait=true" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "params": {
    "groupBy": "originCountry",
    "direction": "imports",
    "product": [
      "coffee"
    ],
    "destinationCountry": [
      "USA"
    ],
    "maxResults": 5
  }
}'
```

```python Python theme={null}
import os, requests

r = requests.post(
    "https://api.mindcase.co/v1/data/customs/trade-stats/run",
    params={"wait": "true"},
    headers={"Authorization": f"Bearer {os.environ['MINDCASE_API_KEY']}"},
    json={"params": {
    "groupBy": "originCountry",
    "direction": "imports",
    "product": [
        "coffee"
    ],
    "destinationCountry": [
        "USA"
    ],
    "maxResults": 5
}},
)
job = r.json()
rows = job.get("data", [])  # if job["status"] == "running", poll /v1/jobs/{job_id}/results
```

```javascript Node.js theme={null}
const r = await fetch("https://api.mindcase.co/v1/data/customs/trade-stats/run?wait=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MINDCASE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: {
  "groupBy": "originCountry",
  "direction": "imports",
  "product": [
    "coffee"
  ],
  "destinationCountry": [
    "USA"
  ],
  "maxResults": 5
} }),
});
const job = await r.json();
const rows = job.data ?? []; // if job.status === "running", poll /v1/jobs/{job_id}/results
```

## Response fields

Each row in `data` is one aggregate bucket, keyed by these fields.

| Field | Name | Type |
| - | - | - |
| `bucketKey` | Bucket Key | text |
| `groupBy` | Grouped By | text |
| `descriptionEn` | Description | text |
| `countryCode` | Country Code | text |
| `countryName` | Country Name | text |
| `period` | Period | text |
| `weightKg` | Weight (kg) | number |
| `quantity` | Quantity | number |
| `valueUsd` | Reported Value (USD) | currency |
| `unitPricePerKgUsd` | Unit Price per kg (USD) | currency |
| `unitPriceUsd` | Unit Price (USD) | currency |
| `tradeCount` | Trade Count | integer |
| `valueSharePct` | Value Share (%) | percentage |

## Example response

Abridged: long text and lists are shortened.

```json theme={null}
{
  "job_id": "7f3a1c2e-0b9d-4c55-9a51-3f2e8d1b6a40",
  "agent": "customs/trade-stats",
  "status": "completed",
  "row_count": 1,
  "truncated": false,
  "data": [
    {
      "countryName": null,
      "tradeCount": 19686,
      "weightKg": 521629199.08,
      "unitPricePerKgUsd": 4.3812,
      "descriptionEn": null,
      "unitPriceUsd": 10.8148,
      "valueSharePct": 0.1585296792196071,
      "valueUsd": 2285335899,
      "period": null,
      "groupBy": "originCountry",
      "countryCode": "COL",
      "quantity": 211315973,
      "bucketKey": "COL"
    }
  ]
}
```

## Related APIs

For the companies behind the trade use [`customs/companies`](https://docs.mindcase.co/apis/customs/companies); for individual shipments use [`customs/shipments`](https://docs.mindcase.co/apis/customs/shipments).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.