WIXLIB

GTT RESTAPI UserManualGTT REST API HowToJuly 14, 2022

Table of Contents1Introduction . 12Accessing the GTT REST API . 13Retrieving an API Token . 14URIs and Endpoints . 24.1Subscription details . 24.2Available Countries . 24.3Available Trade details . 34.4Report fields . 34.5Data updates . 34.6Report Generation . 45Accessing Trade Data . 46Output Format . 47Parameters. 57.1accumulatecommoditygroups. 57.2accumulateotherpartners. 57.3accumulatepartnergroups. 57.4accumulatereportergroups . 57.5currency. 57.6customconversionrules. 67.7dataelements . 67.8decimalscale. 67.9excludeintratrade . 77.10 fallbacktomirrordata . 77.11 field . 77.12 filterbysource . 77.13 format . 77.14 from . 87.15 hscode . 87.16 hslevel . 87.17 impexp . 87.18 includeotherpartners. 97.19 lang. 97.20 latestmonths . 97.21 layout . 97.22 maxQ1 . 107.23 maxQ2 . 107.24 maxV . 107.25 metadata . 107.26 minQ1 . 107.27 minQ2 . 117.28 minV . 117.29 mirrored . 11

7.30 onlycompleteperiods . 117.31 partner . 117.32 periodtype. 117.33 reporter . 127.34 requirealldatareported . 127.35 source. 127.36 to . 127.37 token. 137.38 tradedetails . 137.38.1Create the report data only for the certain trade details . 137.39 unit. 137.40 updatedAfter . 14

GTT REST API User manual1 IntroductionThis guide will show you how to access Global Trade Tracker (‘GTT’) with the GTT REST API. Theguide assumes that you are a programmer or researcher who is familiar with the concepts andtechniques of retrieving data from Web Services.2 Accessing the GTT REST APIFollowing requirements have to be fulfilled to be able to access the GTT REST API: You need a valid GTT userid3 Retrieving an API TokenPlease note: The REST API itself can be accessed only with a valid Token.With a valid GTT userid you can retrieve an API Token to access the REST API which will be valid for14 days.This Token must then be sent in all subsequent calls to the API, either in the http header request (thepreferred way) or as URL or POST parameter.The Header must have the following format:Authorization : Bearer 61D1345AFF690F8F5D13DAB12F6EC9DEIf the Token is sent as URL GET parameter: /?para1 &token 61D1345AFF690F8F5D13DAB12F6EC9DE¶N Or as POST/Form parameter “token”The target URL to retrieve a token tokenBoth methods ‘GET’ and ‘POST’ are supported to retrieve a Token.Parameters which are mandatory to retrieve a token:userida valid GTT useridpassword the password for the supplied GTT useridExample GET t/gettoken?userid myGTTuserid&password myPasswordOr a Token can be retrieved through the basic user interface found at:https://www.globaltradetracker.com/api/Zen Innovations AG, Bernstrasse 99, CH-3122 Kehrsatzwww.globaltradetracker.com www.zen-innovations.comP a g e 1 of 14

GTT REST API User manual4 URIs and EndpointsThe following services are available4.1 Subscription detailsTo get the details of your current subscription (countries and commodity codes) for the actualcontract/userid, treport/subscriptionsSupported method: ‘GET’Parameter:periodTypefollowing periodType’s are currently supported: M (month) Y (year) Q (quarter) S (semester) YTD (year-to-date)If not selected, the default is periodType MResponse: JSON4.2 Available CountriesTo get a list of all available countries on GTT (including alphageonom2 code, source, first/last availabledate, date of last update, update frequency, extra information etc.) treport/countriesSupported method: ‘GET’Parameter: periodsif specified with the value “true”, the country information also contains the list of availableperiods with the data status for each period.The status values are:o FULL – complete trade data is availableo PART – partial data is availableo VALUES – only the values are available, no quantity informationo EXTRAEU – only the extra-EU information is available (used for the EU countries only). langdefines the language used for the translation of the country names.Allowed values: en de fr zh CN es hi jaZen Innovations AG, Bernstrasse 99, CH-3122 Kehrsatzwww.globaltradetracker.com www.zen-innovations.comP a g e 2 of 14

GTT REST API User manualDefault value if missing/not set: enResponse: JSON4.3 Available Trade detailsTo get a list of names and ids of the available trade details for the countries on GTT treport/tradedetailsSupported method: ‘GET’Parameter: tradedetailsdefined the type of the trade details.The values are:o SUBDIVISION – country subdivisions, states, provinces, etc.o PORT – country portso TRANSPORT – transportation modeo CUSTOM – the available information depends on the country.The parameter is required.Please note: Only a certain number of countries report this type of information. Please refer tothe data availability list to get the different countries and their supplementary data elements. countryCodeGeonom alpha-2 country code.Some of the reporting countries have several sets of the trade data. It is possible to select thespecific trade data by appending the suffix to the country code.E.g. ‘FR customs’ 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 thelist of countries provided by the ‘Available Countries’ end-point (see 4.2 above) with therespective suffixes in the ‘reportercode’ property.The parameter is required unless, the parameter tradedetails TRANSPORT is specified (theavaialable transportation modes are not country-specific). langdefines the language used for the translation of the trade detail names.Allowed values: en de fr zh CN es hi jaDefault value if missing/not set: enResponse: JSON4.4 Report fieldsTo get a list of all available report fields treport/fieldsSupported method: ‘GET’Parameter: langdefines the language used for the translation of the field names and desriptions.Allowed values: en de fr zh CN es hi jaDefault value if missing/not set: enResponse: JSON4.5 Data updatesTo retrieve information regarding data updates on GTT (whether this is newly added data or updateddata) following URL can be etreport/dataupdatesSupported method: ‘GET’Zen Innovations AG, Bernstrasse 99, CH-3122 Kehrsatzwww.globaltradetracker.com www.zen-innovations.comP a g e 3 of 14

GTT REST API User manualParameter: countryCodea list of comma-separated country codes, e.g. “US,CA,CH” periodTypefollowing periodType’s are currently supported:- M (month)- Y (year)- Q (quarter)- S (semester)- YTD (year-to-date)If not selected, the default is M updatedAfterthe date to check for updates/additions (i.e. updates/additions will be reported from this dateonwards)supported formats:- yyyy-MM-ddTHH:mm:ss- 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)Response: JSON4.6 Report GenerationTo create a GTT report, treportSupported methods: ‘GET’ and ‘POST’5 Accessing Trade DataUse the URI defined in chapter 4.6 to create and access datasets using GTT’s REST API.You can retrieve data by sending an HTTPS GET or POST request to the URI with the appropriate(query string) parameters.Chapter 7 lists all the available parameters you can use.Example:The following API call will retrieve the monthly import value from January 2016 to June 2016 forGermany and Switzerland for HS Codes 8401 and 2703 in JSON format (if the following API Token wasvalid – the one below is not /getreport?token NNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN&impexp I&periodtype M&from 2016-01&to 201606&reporter DE%2CCH&accumulatereportergroups true&partner &accumulatepartnergroups true&source DEFAULT&hscode 8401%2C2703&accumulatecommoditygroups true&hslevel 0¤cy &unit &decimalscale &customconversionrules true&layout brief&format json6 Output FormatThe API returns data in following formats:-Javascript Object Notation (JSON) formatComma-separated values format (CSV)Microsoft Excel Open XML format (XLSX)Zen Innovations AG, Bernstrasse 99, CH-3122 Kehrsatzwww.globaltradetracker.com www.zen-innovations.comP a g e 4 of 14

GTT REST API User manual7 ParametersBeside the authorization token which has to be provided either in the request HEADER or as parameter“token”, the following 4 parameters MUST be provided with valid values, otherwise a GTT report cannotbe created:reporter, hscode, impexp, sourceOne of the following two parameters is required (if both parameters are set, latestmonths hasprecedence):from, latestmonths7.1 accumulatecommoditygroupsallowed values:true falsedefault value if missing/not set:falsedescription: If a commodity group is used (chapter 7.15) and ifaccumulatecommoditygroups is set to true, then all commodity codes (HSCodes) defined for that group will be aggregated. If set to false, the dataset will list trade for each commodity code listed in that group.7.2 accumulateotherpartnersallowed values:true falsedefault value if missing/not set:falsedescription: If a set of countries is defined for partner countries (chapter 0)and accumulateotherpartners is set to true, then trade with all countriesother than those specified in partner countries will be aggregated as atotal. If set to false, then the trade will be listed for each other partnercountry.7.3 accumulatepartnergroupsallowed values:true falsedefault value if missing/not set:falsedescription: If country groups are listed for partner countries (chapter 0) andif accumulatepartnergroups is set to true, then trade will be aggregated foreach of these country groups. If set to false, trade will be listed for eachpartner country.7.4 accumulatereportergroupsallowed values:true falsedefault value if missing/not set:falsedescription: If country groups are listed for reporting countries (chapter 7.33)and if accumulatereportergroups is set to true, then trade will beaggregated for each of these country groups. If set to false, trade will belisted for each partner country.7.5 currencyallowed values:default value if missing/not set:one of the currency 3-letter ISO codes supportedfrom GTT (see below)original currency (as reported)description: The following currencies are supported in GTT and can be used:Zen Innovations AG, Bernstrasse 99, CH-3122 Kehrsatzwww.globaltradetracker.com www.zen-innovations.comP a g e 5 of 14

GTT REST API User ralian DollarBahraini DinarBotswana PulaBelize DollarCanadian DollarSwiss FrancEgyptian PoundEthiopian BirrEuroBritish PoundGhanaian New CediHong Kong DollarIndian RupeeIsland KronJordanian DinarJapanese YenKenian ShillingMoroccan DirhamMacau PatacaMalaysian RinggitNorvegian KronerNew Zealand DollarQatari RialSaudi RiyalSingapore DollarThai BahtTaiwan DollarUS DollarCFA Franc BCEAOSouth African Rand7.6 customconversionrulesallowed values:true falsedefault value if missing/not set:falsedescription: 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 orshared with that userid. If set to false, then only the standard conversionrules will be used to convert the reported quantities to the requestedquantity unit (chapter 7.23).7.7 dataelementsallowed values:default value if missing/not set:Comma or semicolon separated list of constants‘V’, ‘Q1’ or ‘Q2’V,Q1,Q2description: This parameter defines the data elements which should be includedin the report:Vmonetary valuesQ1primary quantityQ2secondary quantity7.8 decimalscaleallowed values:must be an integer, e.g. 1 or 2 or 3 etc.default value if missing/not set:0description: This parameter allows to specify the precision with which theresults are reported. The default of 0 will round decimals to an integervalue.Zen Innovations AG, Bernstrasse 99, CH-3122 Kehrsatzwww.globaltradetracker.com www.zen-innovations.comP a g e 6 of 14