openapi: 3.0.3
info:
  title: UN Comtrade Data Bulk Download Tariffline 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: Tariffline Data
  description: Tariffline-level trade data with 6-digit or national commodity code detail.
paths:
  /data/v1/getTariffline/{typeCode}/{freqCode}/{clCode}:
    get:
      operationId: getTarifflineData
      summary: Get Tariffline Trade Data
      description: 'Extract tariffline-level trade data with full 6-digit HS or national commodity code detail. Provides more granular breakdown than final aggregated data. Requires a valid API subscription key.

        '
      tags:
      - Tariffline 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/flowCode'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/includeDesc'
      responses:
        '200':
          $ref: '#/components/responses/TradeDataResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
components:
  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
    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
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        details:
          type: string
  parameters:
    includeDesc:
      name: includeDesc
      in: query
      required: false
      schema:
        type: boolean
        default: true
      description: Include commodity and country description labels in the response.
    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'
    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'
    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
    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
    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'
    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
    format:
      name: format
      in: query
      required: false
      schema:
        type: string
        enum:
        - json
        - csv
        - txt
        default: json
      description: 'Response format: json (default), csv, or txt'
    cmdCode:
      name: cmdCode
      in: query
      required: false
      schema:
        type: string
      description: Commodity code(s), comma-separated. Use TOTAL for aggregate.
      example: TOTAL
    freqCode:
      name: freqCode
      in: path
      required: true
      schema:
        type: string
        enum:
        - A
        - M
      description: 'Reporting frequency: A for Annual, M for Monthly'
      example: A
  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/