gtt logo

REST API

version 2408
all versions

Parameters

Beside the authorization token which has to be provided either in the request HEADER or as parameter “token”, the following parameters MUST be provided with valid values, otherwise a GTT report cannot be created:

One of the following parameters is required (in order of precedence):

accumulatecommoditygroups

allowed values
true, false
default value if missing/not set:
false
description:
If a commodity group is used (see hscode parameter) and if accumulatecommoditygroups is set to true, then all commodity codes (HS Codes) defined for that group will be aggregated. If set to false, the data set will list trade for each commodity code listed in that group.

accumulateotherpartners

allowed values
true, false
default value if missing/not set:
false
description:
If a set of countries is defined for partner countries (see partner parameter) and accumulateotherpartners is set to true, then trade with all countries other than those specified in partner countries will be aggregated as a total. If set to false, then the trade will be listed for each other partner country.

accumulatepartnergroups

allowed values
true, false
default value if missing/not set:
false
description:
If country groups are listed for partner countries (see partner parameter) and if accumulatepartnergroups is set to true, then trade will be aggregated for each of these country groups. If set to false, trade will be listed for each partner country.

accumulatereportergroups

allowed values
true, false
default value if missing/not set:
false
description:
If country groups are listed for reporting countries (see reporter parameter) and if accumulatereportergroups is set to true, then trade will be aggregated for each of these country groups. If set to false, trade will be listed for each partner country.

currency

allowed values
one of the currency 3-letter ISO codes supported by GTT (see below)
default value if missing/not set:
original currency (as reported)
description:
The following currencies are supported in GTT and can be used:
  • AUD - Australian Dollar
  • BHD - Bahraini Dinar
  • BWP - Botswana Pula
  • BZD - Belize Dollar
  • CAD - Canadian Dollar
  • CHF - Swiss Franc
  • EGP - Egyptian Pound
  • ETB - Ethiopian Birr
  • EUR - Euro
  • GBP - British Pound
  • GHS - Ghanaian New Cedi
  • HKD - Hong Kong Dollar
  • INR - Indian Rupee
  • ISK - Island Kron
  • JOD - Jordanian Dinar
  • JPY - Japanese Yen
  • KES - Kenian Shilling
  • MAD - Moroccan Dirham
  • MOP - Macau Pataca
  • MYR - Malaysian Ringgit
  • NOK - Norvegian Kroner
  • NZD - New Zealand Dollar
  • QAR - Qatari Rial
  • SAR - Saudi Riyal
  • SGD - Singapore Dollar
  • THB - Thai Baht
  • TWD - Taiwan Dollar
  • USD - US Dollar
  • XOF - CFA Franc BCEAO
  • ZAR - South African Rand

customconversionrules

allowed values
true, false
default value if missing/not set:
true
description:
If set to true, this option allows to apply custom conversion rules (defined on the options page in the GTT web application) for that userid or shared with that userid. If set to false, then only the standard conversion rules will be used to convert the reported quantities to the requested quantity unit (see unit parameter).

dataelements

allowed values
Comma or semicolon separated list of constants ‘V’, ‘Q1’ or ‘Q2’
default value if missing/not set:
V,Q1,Q2
description:
This parameter defines the data elements which should be included in the report:
  • V  - monetary values
  • Q1 - primary quantity
  • Q2 - secondary quantity

decimalscale

allowed values
must be an integer, e.g. 1 or 2 or 3 etc.
default value if missing/not set:
0
description:
This parameter allows to specify the precision with which the results are reported. The default of 0 will round decimals to an integer value.

excludeintratrade

allowed values
true, false
default value if missing/not set:
false
description:
This parameter allows to exclude intra trade amongst a country group. If several country groups are listed, then intra trade is removed within each individual group. In this case, the result will be external trade for each country group. E.g. if Nafta and EU28 are listed and this parameter is set to true, then the result would be a data set listing external trade of EU28 with the world (including NAFTA) and external trade of NAFTA with the world (including EU28). If set to false, then all reported trade is returned.

fallbacktomirrordata

allowed values
true, false
default value if missing/not set:
false
description:
This parameter allows to use the mirror data if the country specified in the reporter parameter does not provide the trade data.

fetchsameperiodnyears

allowed values
positive number
default value if missing/not set:
-
description:
The requested period (defined with from, to, latestmonths or latestavailablemonths parameters) for the specified number of previous months is included in the report.

field

allowed values
Comma or semicolon separated list of field ids.
default value if missing/not set:
-
description:
This parameter allows to define the fields in the generated report.
The list of available report fields can be obtained from the service Report fields.
If this parameter is not specified, the report will contain the default set of fields.
The names of the report JSON properties or CSV/XLSX columns are defined by the layout parameter. (see parameter)

filterbysource

allowed values
DEFAULT, NATIONAL, EUROSTAT, COMTRADE
default value if missing/not set:
-
description:
This parameter defines the source of the data. For some European countries there are two sources available (e.g. France, Germany, etc.). NATIONAL will provide the national statistics data while EUROSTAT will provide the one from Eurostat. If this parameter is specified, only the reporting countries with the defined data source will be used in the report. If the country does not have the requested source available, it will be skipped. If the value DEFAULT is specified, the countries with the national data source will be selected if they exit, otherwise the country with the other data source will be used. This parameter cannot be used together with the source parameter.

Please note: This parameter is used only if the reporter code is specified without suffix (i.e. without e.g. “FR_eurostat” or FR_national.

format

allowed values
JSON, CSV, XLSX
default value if missing/not set:
JSON
description:
This parameter defines the report format which is either JSON, XLSX (Microsoft Excel Open XML format) or CSV.

from

allowed values
The start of the date period in the format YYYY-MM or YYYYMM.
If yearly data is requested (see periodtype parameter) then the date can be in the format YYYY.
default value if missing/not set:
-
description:
This parameter defines the start date for which data should be considered from.
This is a required parameter.

hscode

allowed values
Comma or semicolon separated list of HS codes or commodity group names. Sections can as well be referenced as e.g. S01 for Section 01.
default value if missing/not set:
This parameter is required.
description:
This parameter defines the hs codes for the data set. Please note that you will need to have a valid subscription to access all of the listed HS codes whether they are directly listed or indirectly defined via your commodity groups.

hslevel

allowed values
  • -1 - explode to tariff level
  •  0 - do not explode
  •  2 - Explode to HS2 level
  •  4 - Explode to HS4 level
  •  6 - Explode to HS6 level
default value if missing/not set:
0
description:
This parameter allows to explode the commodity codes defined in hscode parameter to the desired level.
The codes in the commodity groups are not exploded if the parameter accumulatecommoditygroups is set to true.

impexp

allowed values
  • I   - for Imports plus Re-Imports
  • E   - for Exports plus Re-Exports
  • IE  - for Imports and Exports in the same report
  • TB  - for trade balance (Exports – Imports)
  • TT  - for total trade (Exports + Imports)
  • RI  - Re-Imports only
  • RE  - Re-Exports only
  • RIE - Re-Imports and Re-Exports in the same report
  • RTB - Re-Exports – Re-Imports
  • RTT - Re-Exports + Re-Imports
  • NI  - Net Imports
  • NE  - Net Exports
  • NIE - Net Imports and Net Exports in the same report
  • NTB - Net Exports – Net Imports
  • NTT - Net Exports + Net Imports
default value if missing/not set:
This parameter is required.
description:
This parameter defines the tradeflow of interest.

Please note: Only ONE value is allowed, i.e. the different values (even if they are all import or export) can NOT be combined in a call!

includeotherpartners

allowed values
true, false
default value if missing/not set:
false
description:
If partner countries are filtered using a list of countries or country groups, then it is possible to list all other countries as well by specifying this parameter to true. If it is set to false, then only the countries defined in the accumulateotherpartners parameter.

lang

allowed values
  • de    - German
  • en    - English
  • es    - Spanish
  • fr    - French
  • hi    - Hindi
  • zh_CN - Chinese (Simplified)
default value if missing/not set:
en
description:
Defines the language used for the translation of the country names and commodity descriptions.

latestavailablemonths

allowed values
positive number from 1 to max 36 months
default value if missing/not set:
-
description:
Selects the latest N available months for the specified reporters.
This is a required parameter.

latestmonths

allowed values
positive number from 1 to max 36 months
default value if missing/not set:
-
description:
Selects the latest N months back from the current month – or if to parameter is set: the latest N months back from “to”.
Example: to=2018-12 latestmonths=6. Will get data from 2018-06 to 2018-12.
This is a required parameter.

layout

allowed values
default, brief
default value if missing/not set:
default
description:
If the ‘default’ layout is specified, the column headers in CSV and Excel formats and property values in the JSON format are verbose, human readable and translated to the language, defined in the lang parameter. This layout is mainly intended to be used with the CSV and Excel formats, but can be used with JSON as well:
"Trade flow", "Period Type", "Year", "Month", "Reporter”, "Partner", "HS Code", "Commodity Description", "Currency", "Value", "Unit1", "Quantity1", "Unit2", "Quantity2"

The ‘brief’ layout is mainly intended for the JSON format and will produce the fixed property names (or column headers): 

{
    "tradeFlow": "import",
    "periodType": "MONTH",
    "year": 2016,
    "month": 1,
    "reporterCode": "BR",
    "reporterName": "Brasilien",
    "partnerName": "world",
    "hsCode": "84",
    "commodityDescriptionOriginal": "NUCLEAR REACTORS, BOILERS, MACHINERY AND MECHANICAL APPLIANCES",
    "commodityDescriptionTranslation": "KERNREAKTOREN, Kessel, Maschinen und mechanische Geräte",
    "currency": "USD",
    "value": 491008922, "unit1": "KG", "quantity1": 25716978, "unit2": "KGL", "quantity2": 25716978
}
The default set of the report fields can be overridden with the field parameter.

Please note: If the ‘layout’ and ‘field’ parameters are missing and the JSON format is requested, the report will be generated in a legacy JSON format, used in the versions 1.16.x and earlier.
It is discouraged to skip the ‘layout’ parameter and use the the legacy JSON format – it might not be supported in future.

maxQ1

allowed values
any number
default value if missing/not set:
not used
description:
If specified, the generated report will contain only trade data with the quantity1 numbers less or equal to the provided number.

maxQ2

allowed values
any number
default value if missing/not set:
not used
description:
If specified, the generated report will contain only trade data with the quantity2 numbers less or equal to the provided number.

maxV

allowed values
any number
default value if missing/not set:
not used
description:
If specified, the generated report will contain only trade data with the valur numbers less or equal to the provided number.

metadata

allowed values
true, false
default value if missing/not set:
false
description:
If set to true, metadata of the generated report will be added as well.

Please note: metadata is ONLY supported in JSON and XLSX format but not in CSV!

minQ1

allowed values
any number
default value if missing/not set:
not used
description:
If specified, the generated report will contain only trade data with the quantity1 numbers greater or equal to the provided number.

minQ2

allowed values
any number
default value if missing/not set:
not used
description:
If specified, the generated report will contain only trade data with the quantity2 numbers greater or equal to the provided number.

minV

allowed values
any number
default value if missing/not set:
not used
description:
If specified, the generated report will contain only trade data with the value numbers greater or equal to the provided number.

mirrored

allowed values
true, false
default value if missing/not set:
false
description:
This parameter defines whether the data should be generated as a mirrored data set (set to true) or as reported (set to false).

mirrormissingperiods

allowed values
true, false
default value if missing/not set:
false
description:
This parameter allows to use the mirror data if the country specified in the reporter parameter does not provide the trade data for some of the requested periods.

onlycompleteperiods

allowed values
true, false
default value if missing/not set:
false
description:
Include only the periods for which all reporters have complete data (typically used for Eurostat data)

partner

allowed values
Comma or semicolon separated list of Geonom alpha-2 codes or GTT country group names.
See http://ec.europa.eu/eurostat/ramon/other_documents/geonom/index.htm for a list of codes.
default value if missing/not set:
all countries
description:
This parameter allows to filter the trade to only some partner countries - which can be a list of countries (i.e. country codes) or one or more country groups.

periodtype

allowed values
  • M   - monthly data
  • Y   - yearly data
  • Q   - quarterly data
  • S   - semester data
  • YTD - year-to-date
    • default value if missing/not set:
    computes period type based on values, or “M”
    description:
    This parameter defines the level of time aggregates for the data set.

    reporter

    allowed values
    Comma or semicolon separated list of Geonom alpha-2 codes or GTT country group names.
    See http://ec.europa.eu/eurostat/ramon/other_documents/geonom/index.htm for a list of codes.
    default value if missing/not set:
    This parameter is required.
    description:
    Some of the reporting countries have several sets of the trade data. It is possible to select the specific trade data by appending the suffix to the country code.
    E.g. ‘FR_national specifies the trade data provided by the national statistics office, ‘FR_eurostat’ specifies the data provided by Eurostat.
    If the reporting country has several sets of the trade data, it will be specified several times in the list of countries provided by the ‘Available Countries’ end-point with the respective suffixes in the ‘reportercode’ property.

    requirealldatareported

    allowed values
    true, false
    default value if missing/not set:
    true
    description:
    If set to false - allow periods for which not all members in the accumulated reporter country groups have the data.

    source

    allowed values
    • DEFAULT
    • NATIONAL
    • EUROSTAT
    • COMTRADE
    Please note: COMTRADE as source is only accessible with an additional subscription and provides only yearly data for approx. 80 countries.
    default value if missing/not set:
    DEFAULT
    description:
    This parameter defines the source of the data. For some European countries there are two sources available (e.g. France, Germany, etc.). NATIONAL will provide the national statistics data while EUROSTAT will provide the one from Eurostat.
    The value DEFAULT has the same effect as NATIONAL.
    If the country group is specified as the reporter, and the data for the requested source is not available for some of the group countries, the other source will be used. This parameter cannot be used together with the filterbysource parameter.

    Please note: This parameter is used only if the reporter code is specified without suffix (i.e. without e.g. “FR_eurostat” or "FR_national".

    Please note: Source COMTRADE is not available with the regular subscription!
    If you do not have the extra COMTRADE subscription, the request will end with an error.

    Source COMTRADE provides only YEARLY data for approx. 80 countries and will not work if monthly data or data with extra information (e.g. “means of transport”, states, provinces etc.) is requested!

    to

    allowed values
    The end of the date period in the format YYYY-MM or YYYYMM.
    If yearly data is requested (see periodtype parameter) then the date can be in the format YYYY.
    default value if missing/not set:
    implicitly selects the current (latest) month
    description:
    This parameter defines the end date for which data should be considered to, resp. if used in conjunction with the latestmonths parameter defines the end date for the selected N latest months.

    token

    allowed values
    If the received Token is not part of the request HEADER (“Authorization: Bearer NNMMKKLL11WW...”) the token must be added to the POST or GET request as parameter.
    default value if missing/not set:
    -
    description:
    This parameter is necessary for the authentication and authorization to generate a GTT data set.

    tradedetails

    allowed values
    The allowed values are the the fields in the country information ‘supplementaryInfo` field (see Available Countries).
    For example: PORT, SUBDIVISION, TRANSPORT
    default value if missing/not set:
    no supplementary information is included in the report
    description:
    When specified, this parameter will trigger the generation of additional trade information such as port etc.
    Please note: Only a certain number of countries report this type of information. Please refer to the data availability list to get the different countries and their supplementary data elements.
    In addition to (or instead of) the tradedetails parameter it is possible to specify one or several of the following parameters: The values are the comma or semicolon separated list of numeric ids.
    The available numeric ids can be obtained from the Available Trade Details URL.
    If the list of the numeric ids is specified, the report will contain only the trade data with the respective trade details.

    unit

    allowed values
    • GR  - Grams
    • OZ  - Ounces
    • OZT - Ounces(troy)
    • LBT - Pounds(troy)
    • LB  - Pounds
    • KG  - Kilograms
    • CWT - Hundredweight
    • STN - Short tons
    • MT  - Metric tons
    • LTN - Long tons
    • KT  - Kilo tons
    • L   - Litre
    • M3  - Cubic meter
    • KM3 - Cubic kilometer
    • CM2 - Square centimeter
    • M2  - Square meter
    • CM  - Centimeter
    • M   - Meter
    • KM  - Kilometer
    • NO  - Number
    • PAR - Pair
    • DZN - Dozen
    • HUN - Hundred
    • THS - Thousand
    • User defined units
    default value if missing/not set:
    Original Units
    description:
    When specified then units will be converted to the specified unit if the reported unit can be converted. Otherwise the original unit will be reported.

    Please note: if a certain unit was requested (e.g. unit=KG) but the data in question was reported in a unit, which can't be converted to KG or was simply declared as “unspecified unit” or “unknown” or “X” etc. it is NOT possible to convert this data to the requested unit.
    In such a case the API will return several columns/entries with the different (reported and/or missing) units.

    unitpreferred

    allowed values
    • GR  - Grams
    • OZ  - Ounces
    • OZT - Ounces(troy)
    • LBT - Pounds(troy)
    • LB  - Pounds
    • KG  - Kilograms
    • CWT - Hundredweight
    • STN - Short tons
    • MT  - Metric tons
    • LTN - Long tons
    • KT  - Kilo tons
    • L   - Litre
    • M3  - Cubic meter
    • KM3 - Cubic kilometer
    • CM2 - Square centimeter
    • M2  - Square meter
    • CM  - Centimeter
    • M   - Meter
    • KM  - Kilometer
    • NO  - Number
    • PAR - Pair
    • DZN - Dozen
    • HUN - Hundred
    • THS - Thousand
    • User defined units
    default value if missing/not set:
    no preferred quantity units returned
    description:
    When specified then either primary or seconday units will be converted to the specified unit if the it can be converted. Otherwise the original primary unit will be reported.

    updatedafter

    allowed values
    Timestamp in one of the formats:
    • yyyy-MM-ddTHH:mm:ssZ
    • yyyy-MM-dd (will become yyyy-MM-ddT00:00:00 internally)
    • yyyy-MM (will become yyyy-MM-01T00:00:00 internally)
    • yyyy (will become yyyy-01-01T00:00:00 internally)
    default value if missing/not set:
    -
    description:
    If this parameter is specified, the report will contain only trade data which was added or updated after the specified date and time.
    It is recommended to explicitly define the timezone. Various timezone formats are supported. E.g.:
    • 2023-10-12T10:15:30Z
    • 2023-10-12T10:15:30GMT
    • 2023-10-12T10:15:30UTC
    • 2023-10-12T12:15:30CET
    • 2023-10-12T11:15:30+01:00
    • 2023-10-12T12:15:30GMT+02:00
    • 2023-10-12T12:15:30UTC+02:00
    • 2023-10-12T12:15:30Europe/Paris
    • 2023-10-12T12:15:30[Europe/Paris]
    If the timezone is not specified, Central European Time is used by default.