name: UN Comtrade
description: United Nations international trade statistics database with a REST API for accessing import/export data, commodity trade flows, and bilateral trade statistics. Covers over 200 reporting countries and territories with data spanning goods and services trade classified by HS, SITC, and other commodity codes.
image: https://comtradeplus.un.org/favicon.ico
tags:
  - Trade
  - International Trade
  - Import
  - Export
  - Statistics
  - United Nations
  - Economics
  - Commodities
  - Bilateral Trade
  - HS Codes
  - SITC
url: https://raw.githubusercontent.com/api-evangelist/un-comtrade/refs/heads/main/apis.yml
created: '2026-06-13'
modified: '2026-06-13'
specificationVersion: '0.23'
apis:
  - name: UN Comtrade Data API
    description: REST API for extracting international merchandise and services trade statistics. Provides access to final trade data, tariffline data, data availability, metadata, live updates, and bulk file downloads. Requires a free B2C account and API subscription key for full access.
    humanURL: https://comtradedeveloper.un.org/
    baseURL: https://comtradeapi.un.org
    tags:
      - Trade
      - Import
      - Export
      - Commodities
      - Bilateral Trade
      - Statistics
    properties:
      - type: Documentation
        url: https://uncomtrade.org/docs/un-comtrade-api/
      - type: DeveloperPortal
        url: https://comtradedeveloper.un.org/
      - type: OpenAPI
        url: https://comtradedeveloper.un.org/
      - type: Authentication
        url: https://uncomtrade.org/docs/api-subscription-keys/
      - type: Plans
        url: https://raw.githubusercontent.com/api-evangelist/un-comtrade/refs/heads/main/plans/plans.yml
      - type: RateLimits
        url: https://raw.githubusercontent.com/api-evangelist/un-comtrade/refs/heads/main/rate-limits/rate-limits.yml
      - type: FinOps
        url: https://raw.githubusercontent.com/api-evangelist/un-comtrade/refs/heads/main/finops/finops.yml
      - type: Signup
        url: https://comtradeplus.un.org/
      - type: Pricing
        url: https://shop.un.org/databases
      - type: Python SDK
        url: https://github.com/uncomtrade/comtradeapicall
      - type: R Package
        url: https://docs.ropensci.org/comtradr/
    contact:
      - FN: UN Comtrade Support
        email: comtrade@un.org
      - FN: UN Comtrade Subscriptions
        email: subscriptions@un.org
    endpoints:
      - name: Preview Final Trade Data
        description: Preview up to 500 records of final trade data without authentication. Returns merchandise or services trade flows by reporter, partner, commodity, and period.
        method: GET
        path: /public/v1/preview/{typeCode}/{freqCode}/{clCode}
        parameters:
          - name: typeCode
            in: path
            required: true
            description: "Trade type: C for Goods, S for Services"
          - name: freqCode
            in: path
            required: true
            description: "Frequency: A for Annual, M for Monthly"
          - name: clCode
            in: path
            required: true
            description: "Classification: HS, H5, H4, H3, S3, S2, S1"
          - name: reporterCode
            in: query
            required: false
            description: UN country numeric code for the reporting country
          - name: period
            in: query
            required: false
            description: "Year (YYYY) or month (YYYYMM). Multiple values comma-separated."
          - name: cmdCode
            in: query
            required: false
            description: Commodity code(s) comma-separated
          - name: partnerCode
            in: query
            required: false
            description: Partner country UN numeric code
          - name: flowCode
            in: query
            required: false
            description: "Trade flow: M=Import, X=Export, MIP=Import (in-transit), XIP=Export (in-transit)"
          - name: maxRecords
            in: query
            required: false
            description: Maximum records to return (max 500 for preview)
          - name: format
            in: query
            required: false
            description: "Response format: json (default), csv, txt"

      - name: Get Final Trade Data
        description: Extract up to 250,000 records of final trade data per call. Requires valid API subscription key.
        method: GET
        path: /data/v1/get/{typeCode}/{freqCode}/{clCode}
        authentication:
          type: apiKey
          in: header
          name: Ocp-Apim-Subscription-Key
        parameters:
          - name: typeCode
            in: path
            required: true
            description: "Trade type: C for Goods, S for Services"
          - name: freqCode
            in: path
            required: true
            description: "Frequency: A for Annual, M for Monthly"
          - name: clCode
            in: path
            required: true
            description: "Classification: HS, H5, H4, H3, S3, S2, S1"
          - name: reporterCode
            in: query
            required: false
            description: UN country numeric code for the reporting country
          - name: period
            in: query
            required: false
            description: "Year (YYYY) or month (YYYYMM). Comma-separated, max 12 values."
          - name: cmdCode
            in: query
            required: false
            description: Commodity code(s) comma-separated
          - name: partnerCode
            in: query
            required: false
            description: Partner country UN numeric code
          - name: flowCode
            in: query
            required: false
            description: "Trade flow: M=Import, X=Export"
          - name: maxRecords
            in: query
            required: false
            description: Maximum records to return
          - name: format
            in: query
            required: false
            description: "Response format: json (default), csv, txt"

      - name: Get Tariffline Trade Data
        description: Extract tariffline-level trade data with full 6-digit or national commodity code detail. Requires valid API subscription key.
        method: GET
        path: /data/v1/getTariffline/{typeCode}/{freqCode}/{clCode}
        authentication:
          type: apiKey
          in: header
          name: Ocp-Apim-Subscription-Key

      - name: Get Data Availability
        description: Retrieve information about which reporting countries have submitted trade data for given periods and classifications.
        method: GET
        path: /data/v1/getDa/{typeCode}/{freqCode}/{clCode}
        authentication:
          type: apiKey
          in: header
          name: Ocp-Apim-Subscription-Key

      - name: Get Data Availability for Tariffline
        description: Retrieve data availability information specific to tariffline datasets.
        method: GET
        path: /data/v1/getDaTariffline/{typeCode}/{freqCode}/{clCode}
        authentication:
          type: apiKey
          in: header
          name: Ocp-Apim-Subscription-Key

      - name: Get Live Updates
        description: Retrieve information about recent data publications and updates to the UN Comtrade database.
        method: GET
        path: /data/v1/getLiveUpdate
        authentication:
          type: apiKey
          in: header
          name: Ocp-Apim-Subscription-Key

      - name: Get Metadata
        description: Retrieve metadata including reporter lists, partner lists, commodity codes, and classification reference data.
        method: GET
        path: /data/v1/getMetadata
        authentication:
          type: apiKey
          in: header
          name: Ocp-Apim-Subscription-Key

      - name: Bulk Download Trade Data
        description: Retrieve links to bulk files containing large trade datasets. Supports downloads up to 2.5M records via async processing. Requires premium subscription.
        method: GET
        path: /bulk/v1/get/{typeCode}/{freqCode}/{clCode}
        authentication:
          type: apiKey
          in: header
          name: Ocp-Apim-Subscription-Key

      - name: Bulk Download Tariffline Data
        description: Retrieve bulk file links for tariffline-level trade data. Requires premium subscription.
        method: GET
        path: /bulk/v1/getTariffline/{typeCode}/{freqCode}/{clCode}
        authentication:
          type: apiKey
          in: header
          name: Ocp-Apim-Subscription-Key

      - name: Bulk Download Classic Format
        description: Retrieve bulk files in classic UN Comtrade format for backward compatibility with legacy integrations. Requires premium subscription.
        method: GET
        path: /bulk/v1/getClassic/{typeCode}/{freqCode}/{clCode}
        authentication:
          type: apiKey
          in: header
          name: Ocp-Apim-Subscription-Key

      - name: Get Reference Data - Country Groups
        description: Retrieve reference data for country groups used in trade reporting and partner aggregation.
        method: GET
        path: /files/v1/app/reference/country_groups.json
        authentication:
          type: none

common:
  - type: AgenticAccess
    url: agentic-access/un-comtrade-agentic-access.yml
contact:
  - FN: UN Comtrade Support
    email: comtrade@un.org
  - FN: UN Comtrade Subscriptions
    email: subscriptions@un.org
links:
  - rel: self
    href: https://comtradeplus.un.org/
  - rel: developer-portal
    href: https://comtradedeveloper.un.org/
  - rel: documentation
    href: https://uncomtrade.org/docs/
  - rel: pricing
    href: https://shop.un.org/databases
  - rel: sign-up
    href: https://comtradeplus.un.org/
  - rel: python-sdk
    href: https://github.com/uncomtrade/comtradeapicall
  - rel: r-package
    href: https://docs.ropensci.org/comtradr/