API documentation

Get UN Comtrade data straight into your own programs: what each API offers, how to call it, and examples to copy.

Get started

Get a subscription key

The public API needs no key. The others need a subscription key, free with any account, from My API portal.

Log in
Send the key with each request

Put it in this request header:
```
Ocp-Apim-Subscription-Key: your subscription key
```
Or add it to the address as subscription-key=

Try a first request

This one needs no key: open it in your browser, or call it from your program.

GET https://comtradeapi.un.org/public/v1/preview/C/A/HS?reporterCode=36&period=2023&partnerCode=0&cmdCode=TOTAL&flowCode=X

API products

Public API

Previews of trade data (up to 500 rows), data availability, releases and reference lists, with no key.

No key needed 8 endpoints
Bulk API

Complete datasets as compressed files, one per reporter and period.

Premium See the subscription plans
Async API

Large queries prepared in the background; you get an email when the file is ready.

Premium See the subscription plans

Try it out

The interactive console (Swagger UI) sends requests from this page and shows the answers. Choose an API at the top, open an endpoint, then Try it out; for keyed APIs, enter your key under Authorize.

The console is a third-party tool, in English, and not fully accessible: everything it describes is also in the reference below.

Public API

Free API to preview trade data. Results are limited to 500 records. No subscription key required. See examples at https://unstats.un.org/go/498d8e

Address: https://comtradeapi.un.org/public/v1
Subscription key: Not needed

GET /preview/{typeCode}/{freqCode}/{clCode}

Get Trade Data (limited selection)

Parameters of /preview/{typeCode}/{freqCode}/{clCode}
Name	Where	Required	What it is
`typeCode`	In the path	Yes	Type of trade: C for commodities and S for service Values: `C, S`
`freqCode`	In the path	Yes	Trade frequency: A for annual and M for monthly Values: `A, M`
`clCode`	In the path	Yes	Product classifications: HS, SITC, BEC (for goods) or EBOPS (for services). Values: `HS, H6, H5, H4, H3, H2, H1, H0, S4, S3, S2, S1, BE, BE5, EB, EB10, EB02, EBS`
`reporterCode`	In the query	No	Reporter code (Possible values are code of the countries separated by comma (,))
`period`	In the query	No	Year or month. Year should be 4 digit year. Month should be six digit integer with the values of the form YYYYMM. Ex: 201002 for 2010 February. Maximum 1 period for preview
`partnerCode`	In the query	No	Partner code (Possible values are code of the countries separated by comma (,))
`cmdCode`	In the query	No	Commodity code. Maximum 1 commodity code for preview
`flowCode`	In the query	No	Trade flow code. Multi value input should be in the form of csv (Codes separated by comma (,)) Allowed values (case-insensitive): M, X, RX, RM, MIP, XIP, MOP, XOP, MIF, XIF, DX, FM. Omit to not filter.

Example request

GET https://comtradeapi.un.org/public/v1/preview/C/A/HS?reporterCode=36&period=2023&partnerCode=0&cmdCode=TOTAL&flowCode=X

Answers

200 Success
400 Invalid or missing parameters.
500 Unexpected server error.

Example answer

{
  "elapsedTime": "1.07 secs",
  "count": 1,
  "data": [
    {
      "typeCode": "C",
      "freqCode": "A",
      "refPeriodId": 20220101,
      "refYear": 2022,
      "refMonth": 52,
      "period": "2022",
      "reporterCode": 842,
      "reporterISO": null,
      "reporterDesc": null,
      "flowCode": "M",
      "flowDesc": null,
      "partnerCode": 0,
      "partnerISO": null,
      "partnerDesc": null,
      "partner2Code": 0,
      "partner2ISO": null,
      "partner2Desc": null,
      "classificationCode": "H6",
      "classificationSearchCode": "HS",
      "isOriginalClassification": true,
      "cmdCode": "TOTAL",
      "cmdDesc": null,
      "aggrLevel": null,
      "isLeaf": null,
      "customsCode": "C00",
      "customsDesc": null,
      "mosCode": "0",
      "motCode": 0,
      "motDesc": null,
      "qtyUnitCode": -1,
      "qtyUnitAbbr": null,
      "qty": 0.0,
      "isQtyEstimated": false,
      "altQtyUnitCode": -1,
      "altQtyUnitAbbr": null,
  …

GET /previewTariffline/{typeCode}/{freqCode}/{clCode}

Get Tariffline Data (limited selection)

Parameters of /previewTariffline/{typeCode}/{freqCode}/{clCode}
Name	Where	Required	What it is
`typeCode`	In the path	Yes	Type of trade: C for commodities and S for service Values: `C, S`
`freqCode`	In the path	Yes	Trade frequency: A for annual and M for monthly Values: `A, M`
`clCode`	In the path	Yes	Product classifications: HS (for goods). Values: `HS, H6, H5, H4, H3, H2, H1, H0`
`reporterCode`	In the query	No	Reporter code (Possible values are code of the countries separated by comma (,))
`period`	In the query	No	Year or month. Year should be 4 digit year. Month should be six digit integer with the values of the form YYYYMM. Ex: 201002 for 2010 February. Multi value input should be in the form of csv (Codes separated by comma (,))
`partnerCode`	In the query	No	Partner code (Possible values are code of the countries separated by comma (,))
`partner2Code`	In the query	No	Second partner/consignment code (Possible values are code of the countries separated by comma (,))
`cmdCode`	In the query	No	Commodity code. Multi value input should be in the form of csv (Codes separated by comma (,))
`flowCode`	In the query	No	Trade flow code. Multi value input should be in the form of csv (Codes separated by comma (,)) Allowed values (case-insensitive): M, X, RX, RM, MIP, XIP, MOP, XOP, MIF, XIF, DX, FM. Omit to not filter.
`customsCode`	In the query	No	Customs code. Multi value input should be in the form of csv (Codes separated by comma (,)) Allowed values: C00, C01, C02, C03, C04, C05, C06, C07, C08, C09, C10, C11, C12, C13, C14, C15, C20. Omit to not filter.
`motCode`	In the query	No	Mode of transport code. Multi value input should be in the form of csv (Codes separated by comma (,)) Allowed values: 0, 1000, 2000, 2100, 2200, 2900, 3000, 3100, 3200, 3900, 9000, 9100, 9110, 9120, 9190, 9200, 9300, 9900. Omit to not filter.

Example request

GET https://comtradeapi.un.org/public/v1/previewTariffline/C/A/HS?reporterCode=36&period=2023&partnerCode=0&cmdCode=TOTAL&flowCode=X

Answers

200 Success
400 Invalid or missing parameters.
500 Unexpected server error.

Example answer

{
  "elapsedTime": "38.07 secs",
  "count": 1,
  "data": [
    {
      "typeCode": "C",
      "freqCode": "M",
      "refPeriodId": 20230101,
      "period": 202301,
      "reporterCode": 36,
      "reporterDesc": null,
      "reporterISO": null,
      "flowCode": "X",
      "flowDesc": null,
      "partnerCode": 344,
      "partnerDesc": null,
      "partnerISO": null,
      "partner2Code": -1,
      "partner2Desc": null,
      "partner2ISO": null,
      "classificationCode": "H6",
      "cmdCode": "010121",
      "cmdDesc": null,
      "customsCode": "-1",
      "customsDesc": null,
      "mosCode": "-1",
      "motCode": 9900,
      "motDesc": null,
      "qtyUnitCode": 5,
      "qtyUnitAbbr": null,
      "qty": 10.0,
      "altQtyUnitCode": 5,
      "altQtyUnitAbbr": null,
      "altQty": 10.0,
      "netWgt": 0.0,
      "grossWgt": 5000.0,
      "cifvalue": 0.0,
      "fobvalue": 2739872.41,
      "primaryValue": 2739872.41
    }
  …

GET /getComtradeReleases

Get list of recent data releases

Example request

GET https://comtradeapi.un.org/public/v1/getComtradeReleases

Answers

200 Success
500 Unexpected server error.

Example answer

{
  "elapsedTime": "0.33 secs",
  "count": 1,
  "data": [
    {
      "reporterCode": 364,
      "flagCode": "IR",
      "datasetDesc": "Iran CA 2023",
      "nr": "N",
      "dateRelease": "2026-09-24T00:00:00"
    }
  ],
  "error": ""
}

GET /getMetadata/{typeCode}/{freqCode}/{clCode}

Get Metadata (i.e., exchange rate, publication notes) for specific datasets

Parameters of /getMetadata/{typeCode}/{freqCode}/{clCode}
Name	Where	Required	What it is
`typeCode`	In the path	Yes	Values: `C, S`
`freqCode`	In the path	Yes	Values: `A, M`
`clCode`	In the path	Yes	Values: `HS, H6, H5, H4, H3, H2, H1, H0, S4, S3, S2, S1, BE, BE5, EB, EB10, EB02, EBS`

Example request

GET https://comtradeapi.un.org/public/v1/getMetadata/C/A/HS

Answers

200 Success
400 Invalid or missing parameters.
500 Unexpected server error.

Example answer

{
  "elapsedTime": "0.01 secs",
  "count": 1,
  "data": [
    {
      "reporterCode": 842,
      "period": 2022,
      "typeCode": "C",
      "freqCode": "A",
      "datasetCode": 20842202201202100,
      "notes": [
        {
          "datasetCode": 20842202201202100,
          "typeCode": "C",
          "freqCode": "A",
          "period": 2022,
          "reporterCode": 842,
          "reporterDescription": "USA",
          "currency": "USD",
          "importConvFactor": "1",
          "exportConvFactor": "1",
          "tradeSystem": "General",
          "classificationCode": "H6",
          "importValuation": "CIF",
          "exportValuation": "FOB",
          "importPartnerCountry": "Origin",
          "exportPartnerCountry": "Last Known Destination",
          "importPartner2Country": "N/A",
          "exportPartner2Country": "N/A",
          "publicationNote": "New Data: Data for this period is published for the first time; the new data was collected from US Census Bureau on 09 Feb 23.",
          "publicationDate": "2023-03-09T17:58:13.15",
          "publicationDateShort": "2023-03-09"
        }
      ]
    }
  ],
  "error": ""
}

GET /getDA/{typeCode}/{freqCode}/{clCode}

Get Trade Data Availability

Parameters of /getDA/{typeCode}/{freqCode}/{clCode}
Name	Where	Required	What it is
`typeCode`	In the path	Yes	Values: `C, S`
`freqCode`	In the path	Yes	Values: `A, M`
`clCode`	In the path	Yes	Values: `HS, H6, H5, H4, H3, H2, H1, H0, S4, S3, S2, S1, BE, BE5, EB, EB10, EB02, EBS`

Example request

GET https://comtradeapi.un.org/public/v1/getDA/C/A/HS

Answers

200 Success
400 Invalid or missing parameters.
500 Unexpected server error.

Example answer

{
  "elapsedTime": "0.12 secs",
  "count": 1,
  "data": [
    {
      "datasetCode": 20842202201202100,
      "typeCode": "C",
      "freqCode": "A",
      "period": 2022,
      "reporterCode": 842,
      "reporterISO": "USA",
      "reporterDesc": "USA",
      "classificationCode": "H6",
      "classificationSearchCode": "HS",
      "isOriginalClassification": true,
      "isExtendedFlowCode": true,
      "isExtendedPartnerCode": true,
      "isExtendedPartner2Code": false,
      "isExtendedCmdCode": true,
      "isExtendedCustomsCode": false,
      "isExtendedMotCode": false,
      "totalRecords": 1210614,
      "datasetChecksum": 1750866618,
      "firstReleased": "2023-03-09T19:23:39.45",
      "lastReleased": "2023-03-09T19:23:39.45"
    }
  ],
  "error": ""
}

GET /getDATariffline/{typeCode}/{freqCode}/{clCode}

Get Tariffline Data Availability

Parameters of /getDATariffline/{typeCode}/{freqCode}/{clCode}
Name	Where	Required	What it is
`typeCode`	In the path	Yes	Values: `C, S`
`freqCode`	In the path	Yes	Values: `A, M`
`clCode`	In the path	Yes	Values: `HS, H6, H5, H4, H3, H2, H1, H0, S4, S3, S2, S1, BE, BE5, EB, EB10, EB02, EBS`

Example request

GET https://comtradeapi.un.org/public/v1/getDATariffline/C/A/HS

Answers

200 Success
400 Invalid or missing parameters.
500 Unexpected server error.

Example answer

{
  "elapsedTime": "0.06 secs",
  "count": 1,
  "data": [
    {
      "datasetCode": 30036202301202100,
      "typeCode": "C",
      "freqCode": "M",
      "period": 202301,
      "reporterCode": 36,
      "reporterISO": "AUS",
      "classificationCode": "H6",
      "isOriginalClassification": true,
      "isExtendedFlowCode": false,
      "isExtendedPartnerCode": true,
      "isExtendedPartner2Code": false,
      "isExtendedCmdCode": true,
      "isExtendedCustomsCode": false,
      "isExtendedMotCode": true,
      "totalRecords": 250125,
      "datasetChecksum": 1356064231,
      "lengthCmdCode": 6,
      "firstReleased": "2023-04-27T00:23:19.56",
      "lastReleased": "2024-03-14T08:42:10.66"
    }
  ],
  "error": ""
}

GET /getWorldShare/{typeCode}/{freqCode}

Get the World Share (including estimates)

Parameters of /getWorldShare/{typeCode}/{freqCode}
Name	Where	Required	What it is
`typeCode`	In the path	Yes	Values: `C, S`
`freqCode`	In the path	Yes	Values: `A, M`
`period`	In the query	No	Period(s): YYYY (annual) or YYYYMM (monthly), comma-separated, or 'recent'
`reporterCode`	In the query	No	Reporter code(s): codes separated by comma (,)

Example request

GET https://comtradeapi.un.org/public/v1/getWorldShare/C/A?period=2023&reporterCode=36

Answers

200 Success
400 Invalid or missing parameters.
500 Unexpected server error.

Example answer

{
  "elapsedTime": "0.12 secs",
  "count": 1,
  "data": [
    {
      "typeCode": "C",
      "freqCode": "A",
      "period": 2022,
      "year": 2022,
      "month": 52,
      "datasetDesc": "USA CA 2022",
      "reporterCode": 842,
      "reporterISO": "USA",
      "reporterDesc": "USA",
      "worldShare": 0.10664732844975196,
      "isAvailable": true,
      "dataCount": 1,
      "firstReleased": "2023-03-09T19:23:39.45",
      "lastReleased": "2023-03-09T19:23:39.45",
      "created": "2024-05-13T21:12:45.5666667",
      "updated": "2026-07-28T18:04:08.32"
    }
  ],
  "error": ""
}

GET /getMBS

The MBS data API gives users access to historical time series of MBS trade tables, notably Tables 38 and 35. Data availability and frequency of update depend on data series. T35 Total trade - value (1946-) T38 Conversion factors (1946-)

Parameters of /getMBS
Name	Where	Required	What it is
`series_type`	In the query	No	Combination of table number, frequency, type of measurement and currenty. T35.Q.V.$ T35.A.V.$ T38.Q.CF. T38.A.CF. T35.M.V.$ T38.M.CF. Values: `T35.Q.V.$, T35.A.V.$, T38.Q.CF., T38.A.CF., T35.M.V.$, T38.M.CF.`
`year`	In the query	No	Reference year (default = any):The reference year of period. As an example: 2015,2016
`country_code`	In the query	No	Country code (Possible values are code of the countries separated by comma (,))
`period`	In the query	No	Year or month. Year should be 4 digit year. Month should be six digit integer with the values of the form YYYYMM. Ex: 201002 for 2010 February. Multi value input should be in the form of csv (Codes separated by comma (,))
`period_type`	In the query	No	data set frequency: Valid values: A Annual Q Quarterly M Monthly Values: `A, Q, M`
`table_type`	In the query	No	(default = any) MBS Table numbers: MBS and ITSY table identifier. Values: `T35, T38`
`format`	In the query	No	Output format (default = json): Valid value are json, txt or csv Values: `csv, txt, json`

Example request

GET https://comtradeapi.un.org/public/v1/getMBS?series_type=T35.A.V.%24&year=2023&country_code=36&period=2023&period_type=A&table_type=T35

Answers

200 Success (JSON by default; CSV/TXT when format is set)
400 Invalid or missing parameters.
500 Unexpected server error.

Example answer

{
  "elapsedTime": "1.72 secs",
  "count": 1,
  "data": [
    {
      "series_Type": "T35.A.V.$",
      "table_Type": "T35",
      "table_Type_Desc": "Total trade - value",
      "country_Code": 842,
      "country_Type": "C",
      "country_English_Name": "United States",
      "year": 2022,
      "period_Type": "A",
      "period_Number": 0,
      "period": "202252",
      "period_In_Date": "01/01/2022",
      "trade_Flow": "X",
      "trade_Flow_Desc": "Exports",
      "commodity_Classification": "",
      "commodity_Group_Code": "1",
      "commodity_Group_Name": "Total",
      "partner_Country_Code": 0,
      "partner_Country_English_Name": "World",
      "base_Year": null,
      "currency_Type": "$",
      "value": 2065156.971,
      "value_Unit": "M",
      "value_Type": "V",
      "value_Type_Desc": "Value",
      "estimation_Type": "A",
      "estimation_Type_Desc": "Actual"
    }
  ],
  "error": ""
}

API documentation

Get started

Get a subscription key

Send the key with each request

Try a first request

API products

Public API

Bulk API

Async API

Try it out

Public API

Example request

Answers

Example request

Answers

Example request

Answers

Example request

Answers

Example request

Answers

Example request

Answers

Example request

Answers

Example request

Answers