openapi: 3.0.3
info:
  title: UN Comtrade Data Bulk Download Final Trade Data 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: Final Trade Data
  description: Authenticated endpoints for full final trade data extraction (up to 250,000 records per call).
paths:
  /data/v1/get/{typeCode}/{freqCode}/{clCode}:
    get:
      operationId: getFinalTradeData
      summary: Get Final Trade Data
      description: 'Extract up to 250,000 records of final trade data per call. Returns merchandise or services trade flows filtered by reporter, partner, commodity, period, and flow. Requires a valid API subscription key.

        '
      tags:
      - Final Trade Data
      security:
      - ApiKeyHeader: []
      parameters:
      - $ref: '#/components/parameters/typeCode'
      - $ref: '#/components/parameters/freqCode'
      - $ref: '#/components/parameters/clCode'
      - $ref: '#/components/parameters/reporterCode'
      - $ref: '#/components/parameters/period'
      - $ref: '#/components/parameters/cmdCode'
      - $ref: '#/components/parameters/partnerCode'
      - $ref: '#/components/parameters/partner2Code'
      - $ref: '#/components/parameters/flowCode'
      - name: maxRecords
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 250000
        description: Maximum number of records to return (max 250,000)
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/breakdownMode'
      - $ref: '#/components/parameters/includeDesc'
      - $ref: '#/components/parameters/motCode'
      - $ref: '#/components/parameters/customsCode'
      responses:
        '200':
          $ref: '#/components/responses/TradeDataResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /data/v1/getLiveUpdate:
    get:
      operationId: getLiveUpdate
      summary: Get Live Updates
      description: 'Retrieve information about recent data publications and updates to the UN Comtrade database. Useful for monitoring when new country-period data becomes available.

        '
      tags:
      - Final Trade Data
      security:
      - ApiKeyHeader: []
      parameters:
      - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: Successful live update response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ApiResponse'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/LiveUpdateRecord'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
  /data/v1/getMetadata:
    get:
      operationId: getMetadata
      summary: Get Metadata
      description: 'Retrieve reference metadata including reporter country lists, partner country lists, commodity codes, and classification reference data. Used for building valid filter values for data extraction calls.

        '
      tags:
      - Final Trade Data
      security:
      - ApiKeyHeader: []
      parameters:
      - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: Successful metadata response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ApiResponse'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/MetadataRecord'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
components:
  parameters:
    includeDesc:
      name: includeDesc
      in: query
      required: false
      schema:
        type: boolean
        default: true
      description: Include commodity and country description labels in the response.
    flowCode:
      name: flowCode
      in: query
      required: false
      schema:
        type: string
        enum:
        - M
        - X
        - MIP
        - XIP
        - MOP
        - XOP
        - RM
        - RX
      description: 'Trade flow: M=Import, X=Export, MIP=Import in-transit, XIP=Export in-transit, MOP=Import of goods for outward processing, XOP=Export for outward processing, RM=Re-import, RX=Re-export'
      example: X
    cmdCode:
      name: cmdCode
      in: query
      required: false
      schema:
        type: string
      description: Commodity code(s), comma-separated. Use TOTAL for aggregate.
      example: TOTAL
    motCode:
      name: motCode
      in: query
      required: false
      schema:
        type: string
      description: Mode of transport code.
    partner2Code:
      name: partner2Code
      in: query
      required: false
      schema:
        type: string
      description: Secondary partner country code (used for triangular trade).
    partnerCode:
      name: partnerCode
      in: query
      required: false
      schema:
        type: string
      description: UN M49 numeric country code for the partner country. Use 0 for World.
      example: '0'
    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
    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'
    breakdownMode:
      name: breakdownMode
      in: query
      required: false
      schema:
        type: string
        enum:
        - classic
        - plus
      description: 'Data breakdown mode: classic (legacy columns) or plus (extended columns)'
    customsCode:
      name: customsCode
      in: query
      required: false
      schema:
        type: string
      description: Customs procedure code.
    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
    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'
    format:
      name: format
      in: query
      required: false
      schema:
        type: string
        enum:
        - json
        - csv
        - txt
        default: json
      description: 'Response format: json (default), csv, or txt'
    freqCode:
      name: freqCode
      in: path
      required: true
      schema:
        type: string
        enum:
        - A
        - M
      description: 'Reporting frequency: A for Annual, M for Monthly'
      example: A
  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
          nullable: true
          description: Error message if request failed
        validationStatus:
          type: string
          description: Validation status of the request
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        details:
          type: string
    MetadataRecord:
      type: object
      description: Reference metadata record (reporter, partner, or commodity entry).
      properties:
        id:
          type: string
        text:
          type: string
        parent:
          type: string
        isLeaf:
          type: boolean
        aggLevel:
          type: integer
    TradeRecord:
      type: object
      description: A single international trade data record.
      properties:
        typeCode:
          type: string
          description: 'Trade type code: C or S'
        freqCode:
          type: string
          description: 'Frequency code: A or M'
        refPeriodId:
          type: integer
          description: Reference period as integer (YYYY or YYYYMM)
        refYear:
          type: integer
          description: Reference year
        refMonth:
          type: integer
          description: Reference month (1–12, or 99 for annual)
        period:
          type: string
          description: 'Period string: YYYY or YYYYMM'
        reporterCode:
          type: integer
          description: UN M49 code for the reporting country
        reporterISO:
          type: string
          description: ISO alpha-3 code for the reporting country
        reporterDesc:
          type: string
          description: Name of the reporting country
        flowCode:
          type: string
          description: Trade flow code
        flowDesc:
          type: string
          description: Trade flow description
        partnerCode:
          type: integer
          description: UN M49 code for the partner country
        partnerISO:
          type: string
          description: ISO alpha-3 code for the partner country
        partnerDesc:
          type: string
          description: Name of the partner country
        partner2Code:
          type: integer
          description: Secondary partner code
        partner2ISO:
          type: string
          description: Secondary partner ISO alpha-3 code
        partner2Desc:
          type: string
          description: Secondary partner name
        classificationCode:
          type: string
          description: Commodity classification code (HS, SITC, etc.)
        classificationSearchCode:
          type: string
          description: Classification search code used for querying
        isOriginalClassification:
          type: boolean
          description: Whether classification is the original reported classification
        cmdCode:
          type: string
          description: Commodity code
        cmdDesc:
          type: string
          description: Commodity description
        aggrLevel:
          type: integer
          description: Commodity aggregation level (e.g., 2, 4, 6 for HS)
        isLeaf:
          type: boolean
          description: Whether this is a leaf-level commodity code
        customsCode:
          type: string
          description: Customs procedure code
        customsDesc:
          type: string
          description: Customs procedure description
        mosCode:
          type: string
          description: Mode of supply code (services)
        motCode:
          type: integer
          description: Mode of transport code
        motDesc:
          type: string
          description: Mode of transport description
        qtyUnitCode:
          type: integer
          description: Quantity unit code
        qtyUnitAbbr:
          type: string
          description: Quantity unit abbreviation
        qty:
          type: number
          description: Quantity traded
        isQtyEstimated:
          type: boolean
          description: Whether quantity is estimated
        altQtyUnitCode:
          type: integer
          description: Alternative quantity unit code
        altQtyUnitAbbr:
          type: string
          description: Alternative quantity unit abbreviation
        altQty:
          type: number
          description: Alternative quantity
        isAltQtyEstimated:
          type: boolean
          description: Whether alternative quantity is estimated
        netWgt:
          type: number
          description: Net weight in kilograms
        isNetWgtEstimated:
          type: boolean
          description: Whether net weight is estimated
        grossWgt:
          type: number
          description: Gross weight in kilograms
        isGrossWgtEstimated:
          type: boolean
          description: Whether gross weight is estimated
        cifvalue:
          type: number
          description: CIF (Cost, Insurance, Freight) value in USD
        fobvalue:
          type: number
          description: FOB (Free On Board) value in USD
        primaryValue:
          type: number
          description: Primary trade value in USD
        legacyEstimationFlag:
          type: integer
          description: Legacy estimation flag
        isReported:
          type: boolean
          description: Whether data was officially reported (vs. mirrored)
        isAggrAbove:
          type: boolean
          description: Whether values are aggregated above requested level
    LiveUpdateRecord:
      type: object
      description: Information about a recent data publication or update.
      properties:
        typeCode:
          type: string
        freqCode:
          type: string
        classificationCode:
          type: string
        reporterCode:
          type: integer
        reporterISO:
          type: string
        reporterDesc:
          type: string
        period:
          type: string
        publishedDate:
          type: string
          format: date-time
  responses:
    TradeDataResponse:
      description: Successful trade data response
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ApiResponse'
            - type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/TradeRecord'
        text/csv:
          schema:
            type: string
        text/plain:
          schema:
            type: string
    TooManyRequestsError:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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/