GTT - Global Trade Tracker REST API




► GTT REST API user manual

REQUIREMENTS to use the GTT API

  • a valid GTT userid
  • required parameters to create a GTT report are: [reporter, hscode, impexp]
  • one of these 3 parameters must be set as well: [from, latestmonths, latestavailablemonths]
  • a valid token has to be supplied

API usage and code examples

  • a simple [java] Java class which demonstrates basic GTT API usage
     
  • simple [python] python scripts which demonstrate basic GTT API usage: gtt-api.py gtt-api-1.py
    Please note: requests module must be installed
    $ pip install requests
     
  • access the GTT API with Microsoft Power BI
    [see quick Microsoft Power BI help for more information].

    ▷ Please note: request a GTT TOKEN which does not expire from your Sales Rep to use along with Power BI.
    ▷ see as well: connect to a webpage (external link)
     
  • access the GTT API with Tableau Server through the GTT WDC (Web Data Connector)
    [see quick WDC help for more information].

    ▷ Please note: This is a 2.x implementation of the WDC, which is compatible only with Tableau 10.0 and later.
    ▷ see as well: using a Web Data Connector (external link)
     
  • access the GTT API with cURL:
    1. get a token which has to be added to all subsequent calls with the &token=NNNNNNNN parameter:
      curl https://www.globaltradetracker.com/api/rest/gettoken -d "userid=MYUSERID&password=MYPASSWORD"
       
    2. check data update for US after 2025-01
      please note: only GET is allowed here
      curl -G https://www.globaltradetracker.com/api/rest/dataupdates -d "updatedAfter=2025-01&countryCode=US&token=NNNNNNNNNNNNNNNNNNNNN"
       
    3. create a simple EXPORT report on HS code 72, default source, for USA from 2019-01 to 2025-02 but only with data updated after 2025-01:
      curl https://www.globaltradetracker.com/api/rest/getreport -d "updatedAfter=2025-01&source=DEFAULT&impexp=E&hscode=72&from=2019-01&to=2025-02&reporter=US&token=NNNNNNNNNNNNNNNNNNNNN"
       
      please note: you will need a subscription to US and HS code 72 to run this example successfully - or replace the HS and country code with codes and countries you are subscribed to
       

GTT API parameter list

&accumulatecommoditygroups=
&accumulateotherpartners=
&accumulatepartnergroups=
&accumulatereportergroups=
&aggregatemonths=
&allownotreportedperiodsinaggregatedreportinggroups=
&chunk=
&countryCode=
&currency=
&customconversionrules=
&dataelements=
&decimalscale=
&estimaterecords=
&excludeintratrade=
&exculdeintratrade=
&fallbacktomirrordata=
&fetchsameperiodnyears=
&field=
&filterbysource=
&format=
&from=
&hscode=
&hslevel=
&impexp=
&includeotherpartners=
&includetimestamps=
&lang=
&latestavailablemonths=
&latestmonths=
&layout=
&maxQ1=
&maxQ2=
&maxQPreferred=
&maxV=
&metadata=
&minQ1=
&minQ2=
&minQPreferred=
&minV=
&mirrored=
&mirrormissingperiods=
&onlycompleteperiods=
&onlydefaultreporters=
&partner=
&periods=
&periodtype=
&recordsperchunk=
&reporter=
&reportid=
&requirealldatareported=
&source=
&to=
&token=
&tradedetails=
&unit=
&unit1=
&unit2=
&unitpreferred=
&updatedAfter=
&updatedBefore=
&useanalytics=
&version=
Get a token which is valid 14 days

userid
password

[target url=/api/rest/gettoken | supported methods: GET and POST]
check how long the token is still valid:
token

list subscriptions for selected token and period

token
for period

[target url=/api/rest/subscriptions | method: GET | returns: JSON]
data updates

token
updated after [format: 'yyyy-MM-ddTHH:mm:ssZ' or 'yyyy-MM-dd' or 'yyyy-MM' or 'yyyy', e.g. '2018-05-16T10:15:30UTC+02:00' or '2018-05-16')]
updated before [format: 'yyyy-MM-ddTHH:mm:ssZ' or 'yyyy-MM-dd' or 'yyyy-MM' or 'yyyy', e.g. '2018-05-16T10:15:30UTC+02:00' or '2018-05-16')]
period
country code(s) [comma-separated list of country codes, e.g. "CH,US"]
include timestamps

[target url=/api/rest/dataupdates | method: GET | returns: JSON]
list GTT countries

token
language

[target url=/api/rest/countries | method: GET]
list country groups

token
filter
group name
language

[target url=/api/rest/countrygroups | method: GET]
trade details

token
tradedetails
country code [country code, e.g. "CN", "CA"]
language

[target url=/api/rest/tradedetails | method: GET | returns: JSON]
list fields

token
language

[target url=/api/rest/fields | method: GET]

generate a GTT report URL for the

[target url=/api/rest/getreport | supported methods: POST and GET]


- - >>

  method GET POST
  token *
  trade flow * para name=impexp
  latest N available months ** para name=latestavailablemonths
[number from 1 to max 36; latestavailablemonths has precedence over latestmonths and from]
  latest N calendar months ** para name=latestmonths
[number from 1 to max 36; latestmonths has precedence over from]
  from ** para name=from
[YYYY-MM or YYYY please note: the parameters latestavailablemonths and latestmonths have precedence over this parameter]
  to para name=to
[YYYY-MM or YYYY; if empty the current (latest) months is used. May be combined with latestmonths]
  same period N previous years para name=fetchsameperiodnyears
[positive number; if specified, the report will include the data for the same period in N previous years]
  reporting countries or groups * para name=reporter
[coma or semicolon separated list: country codes or group names]
  hs codes * para name=hscode
[coma or semicolon separated list: HS codes, group names or section codes (e.g. 'S01')]
  (*)   = mandatory fields
  (**) = one of the two fields must be set		  
  source para name=source
multiple entries are allowed, e.g. NATIONAL,EUROSTAT
filter by source para name=filterbysource
 
mirror report para name=mirrored
partner country codes para name=partner
[coma or semicolon separated list: country codes or group names -- empty=ALL countries]
updated after para name=updatedAfter
[Include only data, which was updated after this time. YYYY-MM or YYYY or yyyy-MM-ddTHH:mm:ssZ]
period type para name=periodtype
months to aggregate para name=aggregatemonths
[number of months to aggregate (ignored if the 'period type' is specified)]
allow only complete periods para name=onlycompleteperiods
[include only the periods, for which all reporters have the complete data (typically used for Eurostat data)]
accumulate reporter country groups para name=accumulatereportergroups
[accumulate the reporter country groups, otherwise individual countries from the groups will be used]
require all data in accumulated reporter country groups to be reported para name=requirealldatareported
[if false - allow periods, for which not all members in the accumulated reporter country groups have the data]
use the mirror data if the country does not provide its own data para name=fallbacktomirrordata
[if true - allow to use the mirror data if the country does not provide its own trade data]
use the mirror data if the country does not provide the data for the requested period para name=mirrormissingperiods
[if true - use the mirror data if the country does not provide the trade data for the requested period]
accumulate partner country groups para name=accumulatepartnergroups
[accumulate the partner country groups, otherwise individual countries from the groups will be used]
accumulate commodity groups para name=accumulatecommoditygroups
[accumulate the commodity groups, otherwise individual HS codes from the groups will be used]
explode hs to level para name=hslevel
currency para name=currency
[original currency is used if not specified]
quantity unit para name=unit
[original quantity unit is used if not specified]
preferred quantity unit para name=unitpreferred
[convert either primary or secondary quantity unit]
precision para name=decimalscale
[number of digits after decimal point]
use custom conversion rules para name=customconversionrules
[use the custom conversion rules for quantity units defined on the 'Options' page in GTT]
exclude intra trade para name=excludeintratrade
[trade between the members of the country group is excluded]
include all other partner countries para name=includeotherpartners
accumulate other countries para name=accumulateotherpartners
[accumulate other countries into the single entry 'Other Countries']
data elements para name=dataelements
[coma or semicolon separated list: V (value), Q1 (quantity1), Q2 (quantity2)]
value threshold min: max: parameter names=minV - maxV
[include only data, which is between min and max]
quantity1 threshold min: max: parameter names=minQ1 - maxQ1
[include only data, which is between min and max]
quantity2 threshold min: max: parameter names=minQ2 - maxQ2
[include only data, which is between min and max]
preferred quantity threshold min: max: parameter names=minQPreferred - maxQPreferred
[include only data, which is between min and max]
trade details para name=tradedetails
mutliple values are allowed
trade details filter
SUBDIVISION para name=SUBDIVISION
[coma or semicolon separated list of numeric ids]
PORT para name=PORT
[coma or semicolon separated list of numeric ids]
TRANSPORT para name=TRANSPORT
[coma or semicolon separated list of numeric ids]
FOREIGN_PORT para name=FOREIGN_PORT
[coma or semicolon separated list of numeric ids]
PARTNER_US_STATE para name=PARTNER_US_STATE
[coma or semicolon separated list of numeric ids]
CUSTOMS_REGIME para name=CUSTOMS_REGIME
[coma or semicolon separated list of numeric ids]
SUPPRESSION para name=SUPPRESSION
[coma or semicolon separated list of numeric ids]
language para name=lang
fields para name=field
[coma or semicolon separated list of report field ids]
layout
format add metadata: (JSON and XLSX format only!)

generate a GTT report

method GET POST [target url=/api/rest/getreport | supported methods:POST and GET]
token
impexp [values: I, E, IE (exports and imports), TB (exports - imports), TT (exports + imports), RI (re-imports), RE (re-exports), RIE (re-exports and re-imports), RTB (re-exports - re-imports), RTT (re-exports + re-imports), NI (net imports), NE (net exports), NIE (net exports and net imports), NTB (net exports - net imports), NTT (net exports + net imports)]
mirrored [Values: true, false]. Default value if missing: false
periodtype [Values: M, Y, Q, S, YTD]
from [YYYY-MM or YYYY (one of from or latestmonths or latestavailablemonths must be set!)]
latestmonths [N from 1 to max 36 months; if both from and latestmonths are set, latestmonths has precedence]
latestavailablemonths [N from 1 to max 36 months; latestavailablemonths has precedence over latestmonths and from]
to [YYYY-MM or YYYY, can be combined with latestmonths]
fetchsameperiodnyears [positive number]
updatedAfter [Include only data, which was updated after this time. YYYY-MM or YYYY or yyyy-MM-ddTHH:mm:ssZ]
aggregatemonths [number of months to aggregate (ignored if the 'period type' is specified)]
onlycompleteperiods [include only the periods, for which all reporters have the complete data (typically used for Eurostat data)]
reporter [coma or semicolon separated list: country codes or group names]
accumulatereportergroups [Values: true, false]. Default value if missing: true
requirealldatareported [if false - allow periods, for which not all members in the accumulated reporter country groups have the data]
fallbacktomirrordata [if true - allow to use the mirror data if the country does not provide its own trade data]
mirrormissingperiods [if true - allow to use the mirror data if the country does not provide the trade data for the requested period]
partner [coma or semicolon separated list: country codes or group names]. Default value if missing: all countries
accumulatepartnergroups [Values: true, false]. Default value if missing: false
source [Values: DEFAULT, EUROSTAT, COMTRADE]
filterbysource [Values: DEFAULT, NATIONAL, EUROSTAT, COMTRADE]
hscode [coma or semicolon separated list: HS codes, group names or section codes (e.g. 'S01')]
accumulatecommoditygroups [Values: true, false]. Default value if missing: false
hslevel [Values: any number]. Values <0 - tariff level, '0' - do not explode, >0 - HS level. Default value if missing: (do not explode)
currency Default value if missing: original currency
unit Default value if missing: original units
unitpreferred
decimalscale Default value if missing: 0
customconversionrules [Values: true, false]. Default value if missing: false
excludeintratrade [Values: true, false]. Default value if missing: false
includeotherpartners [Values: true, false]. Default value if missing: false
accumulateotherpartners [Values: true, false]. Default value if missing: false
dataelements [Values: V, Q1, Q2]. Default value if missing: V (value), Q1 (quantity1) and Q2 (quantity2)
minV [Values: any number]. Default value if missing: no minimum threshold for value.
maxV [Values: any number]. Default value if missing: no maximum threshold for value.
minQ1 [Values: any number]. Default value if missing: no minimum threshold for quantity1.
maxQ1 [Values: any number]. Default value if missing: no maximum threshold for quantity1.
minQ2 [Values: any number]. Default value if missing: no minimum threshold for quantity2.
maxQ2 [Values: any number]. Default value if missing: no maximum threshold for quantity2.
minQPreferred [Values: any number]. Default value if missing: no minimum threshold for preferred quantity.
maxQPreferred [Values: any number]. Default value if missing: no maximum threshold for preferred quantity.
value threshold min: max: [include only data, which is between min and max]
quantity1 threshold min: max: [include only data, which is between min and max]
quantity2 threshold min: max: [include only data, which is between min and max]
preferred quantity threshold min: max: [include only data, which is between min and max]
tradedetails [Values: SUBDIVISION, PORT, TRANSPORT, FOREIGN_PORT, PARTNER_US_STATE, CUSTOMS_REGIME, SUPPRESSION]. Default value if missing: no supplementary info
lang [Values: en, de, fr, ja, zh_CN]. Default value if missing: en
field [coma or semicolon separated list: field ids].
layout [Values: default, brief, gttdynamicexcel]. Default value if missing: default
format [Values: JSON, CSV, XLSX]. Default value if missing: JSON
metadata [Values: true, false]. Default value if missing: false. Supported for JSON and XLSX format only!

© Zen Innovations AG 2007-2025 | v1.46.11