UN Comtrade

UN Comtrade Bulk Download API

Premium endpoints for bulk file downloads (up to 2.5M records via async processing).

GitHub OpenAPI

Operations 3

GET /bulk/v1/get/{typeCode}/{freqCode}/{clCode} Bulk Download Trade Data #
GET /bulk/v1/getTariffline/{typeCode}/{freqCode}/{clCode} Bulk Download Tariffline Data #
GET /bulk/v1/getClassic/{typeCode}/{freqCode}/{clCode} Bulk Download Classic Format #

Documentation

📖
Documentation
https://uncomtrade.org/docs/un-comtrade-api/
📖
Authentication
https://uncomtrade.org/docs/api-subscription-keys/
📖
RateLimits
https://raw.githubusercontent.com/api-evangelist/un-comtrade/refs/heads/main/rate-limits/rate-limits.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/un-comtrade/refs/heads/main/openapi/un-comtrade-bulk-download-api-openapi.yml

Other Resources

🔗
DeveloperPortal
https://comtradedeveloper.un.org/
🔗
Plans
https://raw.githubusercontent.com/api-evangelist/un-comtrade/refs/heads/main/plans/plans.yml
🔗
FinOps
https://raw.githubusercontent.com/api-evangelist/un-comtrade/refs/heads/main/finops/finops.yml
🔗
Signup
https://comtradeplus.un.org/
🔗
Pricing
https://shop.un.org/databases
🔗
Python SDK
https://github.com/uncomtrade/comtradeapicall
🔗
R Package
https://docs.ropensci.org/comtradr/
🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/un-comtrade/refs/heads/main/apis.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/un-comtrade-bulk-download-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

un-comtrade-bulk-download-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: UN Comtrade Data Bulk Download API
  description: 'REST API for extracting international merchandise and services trade statistics from the United Nations Comtrade database. Provides access to final trade data, tariffline data, data availability, metadata, live updates, and bulk file downloads. Covers over 200 reporting countries and territories with data spanning goods and services trade classified by HS, SITC, and other commodity codes. Requires a free B2C account and API subscription key for full access.

    '
  version: 1.0.0
  contact:
    name: UN Comtrade Support
    email: comtrade@un.org
  x-subscriptions-contact:
    name: UN Comtrade Subscriptions
    email: subscriptions@un.org
  x-logo:
    url: https://comtradeplus.un.org/favicon.ico
  license:
    name: UN Data Terms of Use
    url: https://uncomtrade.org/docs/
servers:
- url: https://comtradeapi.un.org
  description: UN Comtrade API Production Server
security: []
tags:
- name: Bulk Download
  description: Premium endpoints for bulk file downloads (up to 2.5M records via async processing).
paths:
  /bulk/v1/get/{typeCode}/{freqCode}/{clCode}:
    get:
      operationId: bulkGetTradeData
      summary: Bulk Download Trade Data
      description: 'Retrieve links to bulk files containing large trade datasets. Supports downloads up to 2.5 million records via asynchronous processing. Returns file URLs rather than inline data. Requires a premium subscription.

        '
      tags:
      - Bulk Download
      security:
      - ApiKeyHeader: []
      parameters:
      - $ref: '#/components/parameters/typeCode'
      - $ref: '#/components/parameters/freqCode'
      - $ref: '#/components/parameters/clCode'
      - $ref: '#/components/parameters/reporterCode'
      - $ref: '#/components/parameters/period'
      responses:
        '200':
          description: Successful bulk file listing response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ApiResponse'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/BulkFileRecord'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Premium subscription required for bulk access
  /bulk/v1/getTariffline/{typeCode}/{freqCode}/{clCode}:
    get:
      operationId: bulkGetTarifflineData
      summary: Bulk Download Tariffline Data
      description: 'Retrieve bulk file links for tariffline-level trade data. Each file contains complete tariffline data for a single reporter and period. Requires a premium subscription.

        '
      tags:
      - Bulk Download
      security:
      - ApiKeyHeader: []
      parameters:
      - $ref: '#/components/parameters/typeCode'
      - $ref: '#/components/parameters/freqCode'
      - $ref: '#/components/parameters/clCode'
      - $ref: '#/components/parameters/reporterCode'
      - $ref: '#/components/parameters/period'
      responses:
        '200':
          description: Successful bulk tariffline file listing response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ApiResponse'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/BulkFileRecord'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Premium subscription required for bulk access
  /bulk/v1/getClassic/{typeCode}/{freqCode}/{clCode}:
    get:
      operationId: bulkGetClassicData
      summary: Bulk Download Classic Format
      description: 'Retrieve bulk files in classic UN Comtrade format for backward compatibility with legacy integrations and systems that rely on the original column structure. Requires a premium subscription.

        '
      tags:
      - Bulk Download
      security:
      - ApiKeyHeader: []
      parameters:
      - $ref: '#/components/parameters/typeCode'
      - $ref: '#/components/parameters/freqCode'
      - $ref: '#/components/parameters/clCode'
      - $ref: '#/components/parameters/reporterCode'
      - $ref: '#/components/parameters/period'
      responses:
        '200':
          description: Successful classic format bulk file listing response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ApiResponse'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/BulkFileRecord'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          description: Premium subscription required for bulk access
components:
  parameters:
    typeCode:
      name: typeCode
      in: path
      required: true
      schema:
        type: string
        enum:
        - C
        - S
      description: 'Trade type: C for Goods (Commodities), S for Services'
      example: C
    freqCode:
      name: freqCode
      in: path
      required: true
      schema:
        type: string
        enum:
        - A
        - M
      description: 'Reporting frequency: A for Annual, M for Monthly'
      example: A
    period:
      name: period
      in: query
      required: false
      schema:
        type: string
      description: Year (YYYY for annual) or year-month (YYYYMM for monthly). Multiple values comma-separated, max 12 values.
      example: '2023'
    clCode:
      name: clCode
      in: path
      required: true
      schema:
        type: string
        enum:
        - HS
        - H5
        - H4
        - H3
        - H2
        - H1
        - H0
        - S4
        - S3
        - S2
        - S1
        - S0
        - B4
        - B3
        - EB02
      description: 'Commodity classification code: HS (latest), H5–H0 (HS revisions), S4–S0 (SITC revisions), B4/B3 (BEC), EB02 (Extended BEC)'
      example: HS
    reporterCode:
      name: reporterCode
      in: query
      required: false
      schema:
        type: string
      description: UN M49 numeric country code for the reporting country. Comma-separated for multiple. E.g. 156 for China, 840 for USA.
      example: '840'
  schemas:
    ApiResponse:
      type: object
      description: Standard UN Comtrade API response envelope.
      properties:
        elapsedMs:
          type: integer
          description: Time taken to process the request in milliseconds
        count:
          type: integer
          description: Number of records returned
        data:
          type: array
          items: {}
          description: Array of result records
        error:
          type:
          - string
          - 'null'
          description: Error message if request failed
        validationStatus:
          type: string
          description: Validation status of the request
    BulkFileRecord:
      type: object
      description: Bulk file download reference.
      properties:
        typeCode:
          type: string
        freqCode:
          type: string
        classificationCode:
          type: string
        reporterCode:
          type: integer
        reporterISO:
          type: string
        reporterDesc:
          type: string
        period:
          type: string
        fileUrl:
          type: string
          format: uri
        fileSize:
          type: integer
        publishedDate:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        details:
          type: string
  responses:
    UnauthorizedError:
      description: Missing or invalid API subscription key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: Ocp-Apim-Subscription-Key
      description: 'API subscription key obtained after registering a free B2C account at https://comtradeplus.un.org/ and subscribing to the relevant API product.

        '
externalDocs:
  description: UN Comtrade API Documentation
  url: https://uncomtrade.org/docs/un-comtrade-api/