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 2024-10
      please note: only GET is allowed here
      curl -G https://www.globaltradetracker.com/api/rest/getreport/dataupdates -d "updatedAfter=2024-10&countryCode=US&token=NNNNNNNNNNNNNNNNNNNNN"
       
    3. create a simple EXPORT report on HS code 72, default source, for USA from 2019-01 to 2024-11 but only with data updated after 2024-10:
      curl https://www.globaltradetracker.com/api/rest/getreport -d "updatedAfter=2024-10&source=DEFAULT&impexp=E&hscode=72&from=2019-01&to=2024-11&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/getreport/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/getreport/dataupdates | method: GET | returns: JSON]
list GTT countries

token
language

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

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

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

token
language

[target url=/api/rest/getreport/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. DEFAULT,EUROSTAT

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!
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-2024 | v1.45.19