canonical: https://jentic.com/apis/comtrade.un.org/comtrade-un

# Comtrade Un UN Comtrade API

The UN Comtrade API provides access to United Nations international trade statistics: it returns detailed import and export data by commodity, reporter, and partner, offers a public preview of the same data, reports data availability, and lists the reference tables used to decode the results. Use it to analyze global merchandise and services trade flows.

## For AI agents

Query UN Comtrade international trade statistics by type, frequency, and classification code, preview data without a key, check data availability, and list reference tables.

## Scope

Does not provide company-level trade records, tariffs, or real-time shipment tracking. Use for UN Comtrade aggregate trade statistics and their reference tables only.

## Capabilities

- Query detailed trade data by type, frequency, and classification code
- Preview trade data without a subscription key
- Check which data is available for a given classification
- List the reference tables used to decode trade codes
- Filter results by reporter, partner, and time period

## Use cases

### AI agent trade analysis

An AI agent analyzes a trade flow by querying the data endpoint for a commodity between two countries, then decoding the commodity and country codes with the reference tables. Through Jentic the agent finds the data and reference operations by intent and calls them with the stored subscription key, without assembling the code path itself.

Example prompt: Get the 2022 annual exports of commodity 8703 from Germany to the United States

### Public data preview

An analyst doing quick lookups uses the public preview and reference endpoints, which need no credential, to sample trade figures before committing to a full extract. The API exposes a preview of the same dataset so exploratory queries run without a subscription key.

Example prompt: Preview the recent trade data for a commodity and list the reference tables that decode it

### Data availability checks

Before scheduling a large extract, a pipeline checks which periods and classifications have data so it does not request combinations that return nothing. The API reports data availability so the pipeline can target only the datasets that exist.

Example prompt: Check whether monthly data is available for a classification before extracting it

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/data/v1/get/{typeCode}/{freqCode}/{clCode}` | Get final trade data (requires subscription key) |
| GET | `/public/v1/preview/{typeCode}/{freqCode}/{clCode}` | Preview trade data (public) |
| GET | `/public/v1/getDA/{typeCode}/{freqCode}/{clCode}` | Get public data availability |
| GET | `/files/v1/app/reference/ListofReferences.json` | List reference tables (public) |

## Key resources

- **Trade data** — Query detailed import and export data by type, frequency, and classification code
- **Public preview and availability** — Preview trade data and check data availability without a subscription key
- **Reference tables** — List the reference tables used to decode commodity and country codes

## Why Jentic

- **Setup:** Calling the UN Comtrade API by hand means assembling the type, frequency, and classification codes into the path, adding reporter and partner query parameters, and passing a subscription key for the full dataset. Through Jentic you install once, import Comtrade from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** The type, frequency, and classification codes sit in the URL path, so a rule can pin your agent to a single dataset or to the public preview endpoints only. The public preview, data-availability, and reference endpoints need no credential, so read-only exploration runs without your subscription key.
- **Credential handling:** Your UN Comtrade subscription key is stored once, encrypted, by your own Jentic One instance and injected at request time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get trade data for a commodity' or 'preview trade statistics', and Jentic returns the matching Comtrade operation with its input schema so the agent calls the right endpoint without reading the API docs.

## Related APIs

- **Country State City** — Reference data for countries, states, and cities worldwide.
- **USA.gov** — Official directory of U.S. government agencies, services, and contact data.
- **OpenFintech** — Reference data for currencies, payment methods, and financial institutions.

## FAQ

### Is there a UN Comtrade MCP server?

You don't need an MCP server to connect your agent to the UN Comtrade API. Jentic connects it directly from the API Directory: import Comtrade, store your subscription key once, and your agent queries trade statistics on demand.

### Can I limit what my agent is allowed to do with the UN Comtrade API?

Yes. You can allow your agent only the public preview and reference operations, which need no key, so it can explore trade data without touching your subscription. The classification codes sit in the URL path, and every call the agent makes is logged.

### What authentication does the UN Comtrade API use?

The full trade dataset requires an API subscription key sent in the Ocp-Apim-Subscription-Key header, while the preview and reference endpoints need no credential. Through Jentic the key is stored once by your self-hosted instance and injected at call time, so it never reaches the agent's context.

### Can I pull import and export data for a country with the UN Comtrade API?

Yes. Query the data endpoint with the trade type, frequency, and classification codes, and filter by reporter and partner country and period. Use the reference tables to decode the commodity and country codes in the response.

### What are the rate limits for the UN Comtrade API?

The OpenAPI spec does not specify rate limits. UN Comtrade caps free and subscription tiers to a set number of calls and rows per request, so check your plan's limits before large extractions.

### How do I connect the UN Comtrade API to my AI agent?

Search the Jentic API Directory for the Comtrade operation you need, such as querying trade data, and import it. To run it on your own infrastructure, install Jentic One from its GitHub repo, then your agent calls the API with your subscription key injected at execution time.