Section 4 Datasets

4.1 Code of Conduct

Before you proceed to download the data, please read this carefully.

No matter your gender, gender identity and expression, age, sexual orientation, disability, physical appearance, body size, race, ethnicity, religion (or lack thereof), or technology choices you are able to use this data for any non-commercial purpose, including academic.

Commercial purposes are strictly out of the boundaries of what you can do with this data according to UN Comtrade dissemination clauses.

Our datasets are distributed under Creative Commons Attribution-NonCommercial 4.0 International License.

Before downloading you agree to the usage conditions explained both to UN Comtrade Online Usage Agreement and Creative Commons BY-NC 4.0 License.

Besides datasets, the code used to create the API, dashboard and R package are released under GNU General Public License v3.0.

4.2 API

The advantage of the API over https download is that you can filter what to obtain and also access some additional tables.

To obtain exactly the same data as with compressed files, please refer to 4.2.5.

If you use R you’ll need jsonlite and dplyr packages.

library(jsonlite)

These packages are also useful:

library(dplyr)
## 
## Attaching package: 'dplyr'
## The following objects are masked from 'package:stats':
## 
##     filter, lag
## The following objects are masked from 'package:base':
## 
##     intersect, setdiff, setequal, union
library(stringr)

4.2.1 Available tables

as_tibble(fromJSON("https://api.tradestatistics.io/tables"))
## # A tibble: 15 x 3
##    table      description                        source                   
##  * <chr>      <chr>                              <chr>                    
##  1 countries  Countries metadata                 UN Comtrade              
##  2 products   Product metadata                   UN Comtrade              
##  3 reporters  Reporting countries                UN Comtrade              
##  4 communiti… Product communities                Center for International…
##  5 product_s… Product short names                The Observatory of Econo…
##  6 country_r… Ranking of countries               UN Comtrade              
##  7 product_r… Ranking of products                Open Trade Statistics    
##  8 yrpc       Bilateral trade at product level … Open Trade Statistics    
##  9 yrp        Bilateral trade at aggregated lev… Open Trade Statistics    
## 10 yrc        Bilateral trade at aggregated lev… Open Trade Statistics    
## 11 yrc_expor… Bilateral trade at aggregated lev… Open Trade Statistics    
## 12 yrc_impor… Reporter trade at product level (… Open Trade Statistics    
## 13 yr         Reporter trade at aggregated leve… Open Trade Statistics    
## 14 yr_short   Reporter trade at aggregated leve… Open Trade Statistics    
## 15 yc         Product trade at aggregated level… Open Trade Statistics

4.2.2 Metadata

## Countries (no filter)
rda_countries <- "countries.rda"

if (!file.exists(rda_countries)) {
  countries <- as_tibble(fromJSON(
    "https://api.tradestatistics.io/countries"
  ))
  
  save(countries, file = rda_countries, compress = "xz")
  
  countries
} else {
  load(rda_countries)
  
  countries
}
## # A tibble: 249 x 6
##    country_iso country_name_en… country_fullnam… continent_id continent
##  * <chr>       <chr>            <chr>                   <int> <chr>    
##  1 afg         Afghanistan      Afghanistan                 1 Asia     
##  2 alb         Albania          Albania                     2 Europe   
##  3 dza         Algeria          Algeria                     3 Africa   
##  4 asm         American Samoa   American Samoa              4 Oceania  
##  5 and         Andorra          Andorra                     2 Europe   
##  6 ago         Angola           Angola                      3 Africa   
##  7 aia         Anguilla         Anguilla                    5 Americas 
##  8 atg         Antigua and Bar… Antigua and Bar…            5 Americas 
##  9 arg         Argentina        Argentina                   5 Americas 
## 10 arm         Armenia          Armenia                     1 Asia     
## # ... with 239 more rows, and 1 more variable: eu28_member <int>
## Products (no filter)
rda_products <- "products.rda"

if (!file.exists(rda_products)) {
  products <- as_tibble(fromJSON(
    "https://api.tradestatistics.io/products"
  ))
  
  save(products, file = rda_products, compress = "xz")
  
  products
} else {
  load(rda_products)
  
  products
}
## # A tibble: 6,373 x 4
##    product_code product_fullname_english            group_code group_name 
##  * <chr>        <chr>                               <chr>      <chr>      
##  1 0101         Horses, asses, mules and hinnies; … 01         Animals; l…
##  2 010110       Horses, asses, mules and hinnies; … 01         Animals; l…
##  3 010190       Horses, asses, mules and hinnies; … 01         Animals; l…
##  4 0102         Bovine animals; live                01         Animals; l…
##  5 010210       Bovine animals; live, pure-bred br… 01         Animals; l…
##  6 010290       Bovine animals; live, other than p… 01         Animals; l…
##  7 0103         Swine; live                         01         Animals; l…
##  8 010310       Swine; live, pure-bred breeding an… 01         Animals; l…
##  9 010391       Swine; live, (other than pure-bred… 01         Animals; l…
## 10 010392       Swine; live, (other than pure-bred… 01         Animals; l…
## # ... with 6,363 more rows

Please notice that these tables include some aliases.

countries includes some meta-codes, c-xx where xx must the first two letters of a continent and all, this is:

Alias Meaning
c-af Alias for all valid ISO codes in Africa
c-am Alias for all valid ISO codes in the Americas
c-as Alias for all valid ISO codes in Asia
c-eu Alias for all valid ISO codes in Europe
c-oc Alias for all valid ISO codes in Oceania
all Alias for all valid ISO codes in the World

products also includes some meta-codes, xx for the first two digits of a code and those digits are the product group and all, this is:

Alias Meaning
01 Alias for all codes in the group Animals; live
02 Alias for all codes in the group Meat and edible meat offal
03 Alias for all codes in the group Fish and crustaceans, molluscs and other aquatic invertebrates
04 Alias for all codes in the group Dairy produce; birds’ eggs; natural honey; edible products of animal origin, not elsewhere specified or included
06 Alias for all codes in the group Trees and other plants, live; bulbs, roots and the like; cut flowers and ornamental foliage
05 Alias for all codes in the group Animal originated products; not elsewhere specified or included
07 Alias for all codes in the group Vegetables and certain roots and tubers; edible
29 Alias for all codes in the group Organic chemicals
08 Alias for all codes in the group Fruit and nuts, edible; peel of citrus fruit or melons
09 Alias for all codes in the group Coffee, tea, mate and spices
10 Alias for all codes in the group Cereals
11 Alias for all codes in the group Products of the milling industry; malt, starches, inulin, wheat gluten
12 Alias for all codes in the group Oil seeds and oleaginous fruits; miscellaneous grains, seeds and fruit, industrial or medicinal plants; straw and fodder
26 Alias for all codes in the group Ores, slag and ash
13 Alias for all codes in the group Lac; gums, resins and other vegetable saps and extracts
14 Alias for all codes in the group Vegetable plaiting materials; vegetable products not elsewhere specified or included
15 Alias for all codes in the group Animal or vegetable fats and oils and their cleavage products; prepared animal fats; animal or vegetable waxes
22 Alias for all codes in the group Beverages, spirits and vinegar
16 Alias for all codes in the group Meat, fish or crustaceans, molluscs or other aquatic invertebrates; preparations thereof
17 Alias for all codes in the group Sugars and sugar confectionery
18 Alias for all codes in the group Cocoa and cocoa preparations
19 Alias for all codes in the group Preparations of cereals, flour, starch or milk; pastrycooks’ products
20 Alias for all codes in the group Preparations of vegetables, fruit, nuts or other parts of plants
21 Alias for all codes in the group Miscellaneous edible preparations
23 Alias for all codes in the group Food industries, residues and wastes thereof; prepared animal fodder
24 Alias for all codes in the group Tobacco and manufactured tobacco substitutes
25 Alias for all codes in the group Salt; sulphur; earths, stone; plastering materials, lime and cement
27 Alias for all codes in the group Mineral fuels, mineral oils and products of their distillation; bituminous substances; mineral waxes
28 Alias for all codes in the group Inorganic chemicals; organic and inorganic compounds of precious metals; of rare earth metals, of radio-active elements and of isotopes
30 Alias for all codes in the group Pharmaceutical products
35 Alias for all codes in the group Albuminoidal substances; modified starches; glues; enzymes
31 Alias for all codes in the group Fertilizers
32 Alias for all codes in the group Tanning or dyeing extracts; tannins and their derivatives; dyes, pigments and other colouring matter; paints, varnishes; putty, other mastics; inks
39 Alias for all codes in the group Plastics and articles thereof
33 Alias for all codes in the group Essential oils and resinoids; perfumery, cosmetic or toilet preparations
34 Alias for all codes in the group Soap, organic surface-active agents; washing, lubricating, polishing or scouring preparations; artificial or prepared waxes, candles and similar articles, modelling pastes, dental waxes and dental preparations with a basis of plaster
36 Alias for all codes in the group Explosives; pyrotechnic products; matches; pyrophoric alloys; certain combustible preparations
37 Alias for all codes in the group Photographic or cinematographic goods
38 Alias for all codes in the group Chemical products n.e.c.
40 Alias for all codes in the group Rubber and articles thereof
44 Alias for all codes in the group Wood and articles of wood; wood charcoal
41 Alias for all codes in the group Raw hides and skins (other than furskins) and leather
70 Alias for all codes in the group Glass and glassware
42 Alias for all codes in the group Articles of leather; saddlery and harness; travel goods, handbags and similar containers; articles of animal gut (other than silk-worm gut)
43 Alias for all codes in the group Furskins and artificial fur; manufactures thereof
45 Alias for all codes in the group Cork and articles of cork
46 Alias for all codes in the group Manufactures of straw, esparto or other plaiting materials; basketware and wickerwork
47 Alias for all codes in the group Pulp of wood or other fibrous cellulosic material; recovered (waste and scrap) paper or paperboard
52 Alias for all codes in the group Cotton
48 Alias for all codes in the group Paper and paperboard; articles of paper pulp, of paper or paperboard
49 Alias for all codes in the group Printed books, newspapers, pictures and other products of the printing industry; manuscripts, typescripts and plans
50 Alias for all codes in the group Silk
51 Alias for all codes in the group Wool, fine or coarse animal hair; horsehair yarn and woven fabric
53 Alias for all codes in the group Vegetable textile fibres; paper yarn and woven fabrics of paper yarn
54 Alias for all codes in the group Man-made filaments; strip and the like of man-made textile materials
55 Alias for all codes in the group Man-made staple fibres
62 Alias for all codes in the group Apparel and clothing accessories; not knitted or crocheted
56 Alias for all codes in the group Wadding, felt and nonwovens, special yarns; twine, cordage, ropes and cables and articles thereof
57 Alias for all codes in the group Carpets and other textile floor coverings
58 Alias for all codes in the group Fabrics; special woven fabrics, tufted textile fabrics, lace, tapestries, trimmings, embroidery
59 Alias for all codes in the group Textile fabrics; impregnated, coated, covered or laminated; textile articles of a kind suitable for industrial use
60 Alias for all codes in the group Fabrics; knitted or crocheted
61 Alias for all codes in the group Apparel and clothing accessories; knitted or crocheted
95 Alias for all codes in the group Toys, games and sports requisites; parts and accessories thereof
63 Alias for all codes in the group Textiles, made up articles; sets; worn clothing and worn textile articles; rags
64 Alias for all codes in the group Footwear; gaiters and the like; parts of such articles
65 Alias for all codes in the group Headgear and parts thereof
66 Alias for all codes in the group Umbrellas, sun umbrellas, walking-sticks, seat sticks, whips, riding crops; and parts thereof
67 Alias for all codes in the group Feathers and down, prepared; and articles made of feather or of down; artificial flowers; articles of human hair
68 Alias for all codes in the group Stone, plaster, cement, asbestos, mica or similar materials; articles thereof
69 Alias for all codes in the group Ceramic products
71 Alias for all codes in the group Natural, cultured pearls; precious, semi-precious stones; precious metals, metals clad with precious metal, and articles thereof; imitation jewellery; coin
72 Alias for all codes in the group Iron and steel
73 Alias for all codes in the group Iron or steel articles
74 Alias for all codes in the group Copper and articles thereof
75 Alias for all codes in the group Nickel and articles thereof
76 Alias for all codes in the group Aluminium and articles thereof
81 Alias for all codes in the group Metals; n.e.c., cermets and articles thereof
78 Alias for all codes in the group Lead and articles thereof
79 Alias for all codes in the group Zinc and articles thereof
80 Alias for all codes in the group Tin; articles thereof
82 Alias for all codes in the group Tools, implements, cutlery, spoons and forks, of base metal; parts thereof, of base metal
83 Alias for all codes in the group Metal; miscellaneous products of base metal
84 Alias for all codes in the group Nuclear reactors, boilers, machinery and mechanical appliances; parts thereof
85 Alias for all codes in the group Electrical machinery and equipment and parts thereof; sound recorders and reproducers; television image and sound recorders and reproducers, parts and accessories of such articles
88 Alias for all codes in the group Aircraft, spacecraft and parts thereof
91 Alias for all codes in the group Clocks and watches and parts thereof
86 Alias for all codes in the group Railway, tramway locomotives, rolling-stock and parts thereof; railway or tramway track fixtures and fittings and parts thereof; mechanical (including electro-mechanical) traffic signalling equipment of all kinds
87 Alias for all codes in the group Vehicles; other than railway or tramway rolling stock, and parts and accessories thereof
89 Alias for all codes in the group Ships, boats and floating structures
90 Alias for all codes in the group Optical, photographic, cinematographic, measuring, checking, medical or surgical instruments and apparatus; parts and accessories
92 Alias for all codes in the group Musical instruments; parts and accessories of such articles
93 Alias for all codes in the group Arms and ammunition; parts and accessories thereof
94 Alias for all codes in the group Furniture; bedding, mattresses, mattress supports, cushions and similar stuffed furnishings; lamps and lighting fittings, n.e.c.; illuminated signs, illuminated name-plates and the like; prefabricated buildings
96 Alias for all codes in the group Miscellaneous manufactured articles
97 Alias for all codes in the group Works of art; collectors’ pieces and antiques
99 Alias for all codes in the group Commodities not specified according to kind
all Alias for all codes

4.2.3 API parameters

The tables provided withing our API contain at least one of these fields:

  • Year (y)
  • Reporter ISO (r)
  • Partner ISO (p)
  • Product Code (c)

The most detailed table is yrpc that contains all bilateral flows at product level.

With respect to y you can pass any integer contained in \([1962,2017]\).

Both r and p accept any valid ISO code or alias contained in the countries table. For example, both chl (valid ISO code) and c-am (continent Americas, an alias) are valid API filtering parameters.

c takes any valid product code or alias from the products. For example, both 0101 (valid HS product code) and 01 (valid HS group code) are valid API filtering parameters.

In addition to y, r, p, c parameters, the length (l) parameter allows efficient queries provided our data contains both 4 and 6 digits long product codes. Because 4 digits code contain 6 digits codes, our approach is to allow the user to use l=4, l=6 or l=all to provide just the requested data.

By default the API takes c = "all" and l = 4 as defaults.

You can always skip c or l, but y, r and p are requiered to return data.

4.2.4 Available reporters

The only applicable filter is by year.

# Available reporters (filter by year)
as_tibble(fromJSON(
  "https://api.tradestatistics.io/reporters?y=2015"
))
## # A tibble: 224 x 1
##    reporter_iso
##  * <chr>       
##  1 afg         
##  2 ago         
##  3 aia         
##  4 alb         
##  5 and         
##  6 are         
##  7 arg         
##  8 arm         
##  9 asm         
## 10 atf         
## # ... with 214 more rows

4.2.5 YRPC (Year, Reporter, Partner and Product Code)

The applicable filters here are year, reporter, partner, product code and (optionally) product code length.

# Year - Reporter - Partner - Product Code (filter by year, reporter and partner)

## file to store the query results
rda_1962 <- "api_data_1962.rda"

## filter by product code length (parameter `l`)
if (!file.exists(rda_1962)) {
  yrpc_1 <- as_tibble(fromJSON(
    "https://api.tradestatistics.io/yrpc?y=1962&r=usa&p=all&l=4"
  ))
  
  save(yrpc_1, file = rda_1962, compress = "xz")
  
  yrpc_1
} else {
  load(rda_1962)
  
  yrpc_1
}
## # A tibble: 49,383 x 7
##     year reporter_iso partner_iso product_code product_code_le…
##  * <int> <chr>        <chr>       <chr>                   <int>
##  1  1962 usa          afg         0201                        4
##  2  1962 usa          afg         0210                        4
##  3  1962 usa          afg         0401                        4
##  4  1962 usa          afg         0402                        4
##  5  1962 usa          afg         0405                        4
##  6  1962 usa          afg         0406                        4
##  7  1962 usa          afg         0409                        4
##  8  1962 usa          afg         0710                        4
##  9  1962 usa          afg         0801                        4
## 10  1962 usa          afg         0802                        4
## # ... with 49,373 more rows, and 2 more variables: export_value_usd <int>,
## #   import_value_usd <int>
## filter by product group (parameter `c`)
yrpc_2 <- as_tibble(fromJSON(
  "https://api.tradestatistics.io/yrpc?y=2015&r=chl&p=arg&c=01"
))

yrpc_2
## # A tibble: 5 x 15
##    year reporter_iso partner_iso product_code product_code_le…
## * <int> <chr>        <chr>       <chr>                   <int>
## 1  2015 chl          arg         0101                        4
## 2  2015 chl          arg         010110                      6
## 3  2015 chl          arg         010190                      6
## 4  2015 chl          arg         0106                        4
## 5  2015 chl          arg         010619                      6
## # ... with 10 more variables: export_value_usd <int>,
## #   import_value_usd <int>, export_value_usd_change_1_year <int>,
## #   export_value_usd_change_5_years <int>,
## #   export_value_usd_percentage_change_1_year <dbl>,
## #   export_value_usd_percentage_change_5_years <dbl>,
## #   import_value_usd_change_1_year <int>,
## #   import_value_usd_change_5_years <int>,
## #   import_value_usd_percentage_change_1_year <dbl>,
## #   import_value_usd_percentage_change_5_years <dbl>

Some columns requiere an explanation:

  • product_code: HS07 product codes (e.g. according to the table within this package, 0101 stands for “Horses, etc.”)
  • product_code_length: How many digits does product_code contain, this can be useful to filter by depth when using HS codes (HS 6 digits is a more detailed version of HS 4 digits, and therefore you don’t have to sum both or you’ll be counting exports/imports twice)
  • group_code: International categorization of group products defined after product ID
  • group_name: English name corresponding to group_id
  • export_value_usd: Exports measured in nominal United States Dollars (USD)
  • import_value_usd: Imports measured in nominal United States Dollars (USD)
  • export_value_usd_percentage_change_1_year: Nominal increase/decrease in exports measured as percentage with respect to last year
  • export_value_usd_percentage_change_5_years: Nominal increase/decrease in exports measured as percentage with respect to five years ago
  • export_value_usd_change_1_year: Nominal increase/decrease in exports measured in USD with respect to last year
  • export_value_usd_change_5_years: Nominal increase/decrease in exports measured in USD with respect to five years ago

4.2.6 YRC (Year, Reporter and Product Code)

The only applicable filter is by year, reporter, product code and (optionally) product code length.

# Year - Reporter - Product Code (filter by year and reporter)

## filter by reporter ISO (parameter `r`)
yrc_1 <- as_tibble(fromJSON(
  "https://api.tradestatistics.io/yrc?y=2015&r=chl&l=4"
))

yrc_1
## # A tibble: 1,214 x 16
##     year reporter_iso product_code product_code_le… export_value_usd
##  * <int> <chr>        <chr>                   <int>            <dbl>
##  1  2015 chl          0101                        4          9958013
##  2  2015 chl          0102                        4         88938806
##  3  2015 chl          0103                        4           956016
##  4  2015 chl          0104                        4               NA
##  5  2015 chl          0105                        4               NA
##  6  2015 chl          0106                        4          5290017
##  7  2015 chl          0201                        4          7812764
##  8  2015 chl          0202                        4         25146882
##  9  2015 chl          0203                        4        402815596
## 10  2015 chl          0204                        4         32743522
## # ... with 1,204 more rows, and 11 more variables: import_value_usd <dbl>,
## #   export_rca_4_digits_product_code <dbl>,
## #   import_rca_4_digits_product_code <dbl>,
## #   export_value_usd_change_1_year <dbl>,
## #   export_value_usd_change_5_years <dbl>,
## #   export_value_usd_percentage_change_1_year <dbl>,
## #   export_value_usd_percentage_change_5_years <dbl>,
## #   import_value_usd_change_1_year <dbl>,
## #   import_value_usd_change_5_years <dbl>,
## #   import_value_usd_percentage_change_1_year <dbl>,
## #   import_value_usd_percentage_change_5_years <dbl>
## filter by reporter alias (also parameter `r`)
yrc_2 <- as_tibble(fromJSON(
  "https://api.tradestatistics.io/yrc?y=2015&r=c-am&l=4"
))

yrc_2
## # A tibble: 47,807 x 16
##     year reporter_iso product_code product_code_le… import_value_usd
##  * <int> <chr>        <chr>                   <int>            <dbl>
##  1  2015 aia          0101                        4            12000
##  2  2015 aia          0104                        4             1481
##  3  2015 aia          0105                        4            44859
##  4  2015 aia          0106                        4              111
##  5  2015 aia          0201                        4           216873
##  6  2015 aia          0202                        4           514211
##  7  2015 aia          0203                        4           166264
##  8  2015 aia          0204                        4            57070
##  9  2015 aia          0206                        4            33427
## 10  2015 aia          0207                        4          1117503
## # ... with 47,797 more rows, and 11 more variables:
## #   import_rca_4_digits_product_code <dbl>,
## #   import_value_usd_change_1_year <dbl>,
## #   import_value_usd_percentage_change_1_year <dbl>,
## #   import_value_usd_change_5_years <dbl>,
## #   import_value_usd_percentage_change_5_years <dbl>,
## #   export_value_usd <dbl>, export_rca_4_digits_product_code <dbl>,
## #   export_value_usd_change_1_year <dbl>,
## #   export_value_usd_change_5_years <dbl>,
## #   export_value_usd_percentage_change_1_year <dbl>,
## #   export_value_usd_percentage_change_5_years <dbl>

Here the export_rca* and import_rca* fields contain the Revealed Comparative Advantage (RCA) of an exported product with respect to all the products with the same number of digits. The definition of RCA is detailed on Open Trade Statistics Documentation.

4.2.7 YRP (Year, Reporter and Partner)

The only applicable filter is by year, reporter and partner.

# Year - Reporter - Partner (filter by year, reporter and partner)
yrp <- as_tibble(fromJSON(
  "https://api.tradestatistics.io/yrp?y=2015&r=chl&p=arg"
))

4.2.8 YC (Year and Product Code)

The only applicable filter is by year, product and (optionally) product code length.

# Year - Product Code (filter by year)
yc <- as_tibble(fromJSON(
  "https://api.tradestatistics.io/yc?y=2015&c=0101"
))

Let’s explore the first rows of yr:

yc
## # A tibble: 1 x 21
##    year product_code product_code_le… export_value_usd import_value_usd
## * <int> <chr>                   <int>            <dbl>            <dbl>
## 1  2015 0101                        4       3464828975       3464828975
## # … with 16 more variables: pci_4_digits_product_code <dbl>,
## #   pci_rank_4_digits_product_code <int>,
## #   pci_rank_4_digits_product_code_delta_1_year <int>,
## #   pci_rank_4_digits_product_code_delta_5_years <int>,
## #   top_exporter_iso <chr>, top_exporter_trade_value_usd <int>,
## #   top_importer_iso <chr>, top_importer_trade_value_usd <int>,
## #   export_value_usd_change_1_year <int>,
## #   export_value_usd_change_5_years <int>,
## #   export_value_usd_percentage_change_1_year <dbl>,
## #   export_value_usd_percentage_change_5_years <dbl>,
## #   import_value_usd_change_1_year <int>,
## #   import_value_usd_change_5_years <int>,
## #   import_value_usd_percentage_change_1_year <dbl>,
## #   import_value_usd_percentage_change_5_years <dbl>

Here some fields deserve an explanation:

  • pci_4_digits_product_code: Product Complexity Index (PCI) which is detailed on Open Trade Statistics Documentation. This index is built by using just four digits product codes.
  • pci_6_digits_product_code: Similar to the previous field but built by using just six digits product codes.
  • pci_rank_4_digits_product_code: The rank of a product given its PCI (e.g. the highest PCI obtains the #1)
  • pci_rank_4_digits_product_code_delta_1_year: How many places a country increased or decreased with respect to last year

4.2.8.1 YR (Year and Reporter)

The only applicable filter is by year and reporter.

## Year - Reporter (filter by year and reporter)
yr <- as_tibble(fromJSON(
  "https://api.tradestatistics.io/yr?y=2015&r=chl"
))

Let’s explore the first rows of yr:

yr
## # A tibble: 1 x 20
##    year reporter_iso export_value_usd import_value_usd eci_4_digits_pr…
## * <int> <chr>                   <dbl>            <dbl>            <dbl>
## 1  2015 chl               69696214027      73736894538           -0.221
## # … with 15 more variables: eci_rank_4_digits_commodity_code <int>,
## #   eci_rank_4_digits_commodity_code_delta_1_year <int>,
## #   eci_rank_4_digits_commodity_code_delta_5_years <int>,
## #   top_export_product_code <chr>, top_export_trade_value_usd <dbl>,
## #   top_import_product_code <chr>, top_import_trade_value_usd <dbl>,
## #   export_value_usd_change_1_year <dbl>,
## #   export_value_usd_change_5_years <dbl>,
## #   export_value_usd_percentage_change_1_year <dbl>,
## #   export_value_usd_percentage_change_5_years <dbl>,
## #   import_value_usd_change_1_year <dbl>,
## #   import_value_usd_change_5_years <dbl>,
## #   import_value_usd_percentage_change_1_year <dbl>,
## #   import_value_usd_percentage_change_5_years <dbl>

Some fields here require more detail:

  • eci_4_digits_product_code: Economic Complexity Index (ECI) which is detailed on Open Trade Statistics Documentation. This index is built by using just four digits product codes.
  • eci_rank_4_digits_product_code: The rank of a country given its ECI (e.g. the highest ECI obtains the #1)
  • eci_rank_4_digits_product_code_delta_1_year: How many places a country increased or decreased with respect to last year

4.2.9 Country rankings

The only applicable filter is by year.

# Country rankings (filter by year)
country_rankings <- as_tibble(fromJSON(
  "https://api.tradestatistics.io/country_rankings?y=2015"
))

4.2.10 Product rankings

The only applicable filter is by year.

# Product rankings (filter by year)
product_rankings <- as_tibble(fromJSON(
  "https://api.tradestatistics.io/product_rankings?y=2015"
))

4.3 R Package

To ease API using, we provide an R Package. This package is a part of ROpenSci and its documentation is available on a separate pkgdown site.

4.4 Dashboard (beta)

To ease API using, we provide a Shiny Dashboard that is still under improvements.

4.5 Compressed data

4.5.1 How to use

There is a special consideration you should have with our datasets, and is that you should always read the trade values as a numeric column and the product codes as a character column.

Different R packages, and statistical software in general, have includeded functions to autodetect column types. In our experience, that can read product codes as integers and that would ignore leading zeroes in product codes. The same applies to trade values that can be detected as integers after the program reads the first \(n\) rows, and that would lead to read large values incorrectly due to integer class maximum value of 2,147,483,647.

As an example, let’s read 1962 data and explore what the United Stated exported:

# packages

library(data.table)
library(dplyr)
library(stringr)
library(janitor)

# custom functions

messageline <- function() {
  message(rep("-", 60))
}

fread2 <- function(file, select = NULL, character = NULL, numeric = NULL) {
  messageline()
  message("function fread2")
  message("file: ", file)
  
  if(str_sub(file, start = -2) == "gz") {
    d <- fread(
      cmd = paste("zcat", file),
      select = select,
      colClasses = list(
        character = character,
        numeric = numeric
      )
    ) %>%
      as_tibble() %>%
      clean_names()
  } else {
    d <- fread(
      input = file,
      select = select,
      colClasses = list(
        character = character,
        numeric = numeric
      )
    ) %>%
      as_tibble() %>%
      clean_names()
  }
  
  return(d)
}

# download data

url_1962 <- "https://data.tradestatistics.io/06-tables/hs-rev2007/1-yrpc/yrpc-1962.csv.gz"
gz_1962 <- "yrpc-1962.csv.gz"

if (!file.exists(gz_1962)) {
  try(download.file(url_1962, gz_1962))
}

# read data

# same filename as in the YRPC example from the API section (it's the same data)
rda_1962 <- "api_data_1962.rda"

if (!file.exists(rda_1962)) {
  yrpc_1 <- fread2(
        gz_1962,
        character = "product_code",
        numeric = c(
          "export_value_usd",
          "import_value_usd",
          "export_value_usd_change_1_year",
          "export_value_usd_change_5_years",
          "export_value_usd_percentage_change_1_year",
          "export_value_usd_percentage_change_5_years",
          "import_value_usd_change_1_year",
          "import_value_usd_change_5_years",
          "import_value_usd_percentage_change_1_year",
          "import_value_usd_percentage_change_5_years"
        )
      ) %>% 
    filter(reporter_iso == "usa")
} else {
  load(rda_1962)
}

yrpc_1
## # A tibble: 49,383 x 7
##     year reporter_iso partner_iso product_code product_code_le…
##  * <int> <chr>        <chr>       <chr>                   <int>
##  1  1962 usa          afg         0201                        4
##  2  1962 usa          afg         0210                        4
##  3  1962 usa          afg         0401                        4
##  4  1962 usa          afg         0402                        4
##  5  1962 usa          afg         0405                        4
##  6  1962 usa          afg         0406                        4
##  7  1962 usa          afg         0409                        4
##  8  1962 usa          afg         0710                        4
##  9  1962 usa          afg         0801                        4
## 10  1962 usa          afg         0802                        4
## # … with 49,373 more rows, and 2 more variables: export_value_usd <int>,
## #   import_value_usd <int>

4.5.2 Available datasets

Please check the md5sums to verify data integrity after downloading.

4.5.2.1 Metadata

4.5.2.2 Yearly datasets

Year Last updated File size (MB) MD5 sum
1962 2019-07-12 9.24 41cbc45755fc5d226cdc025fd3f7fb6d
1963 2019-07-12 24.00 99aeace3432a5291300b193ff4ce473b
1964 2019-07-12 26.99 b5f836e1064c51d2ee0468aff6f09da8
1965 2019-07-12 29.86 da78feb341c50a2ae8029deedb3b6bea
1966 2019-07-12 32.00 32e33ca9079840863cfdee6018274033
1967 2019-07-12 44.95 a6e3dcffb2802f7f74fd9ec574720bc5
1968 2019-07-12 48.20 ebc4279d732b74c75488b288320c9269
1969 2019-07-12 50.85 c547403d5cf6b7f4d073651acfde1b2e
1970 2019-07-12 54.69 12622f7a70bf3e3d071619028eb56e74
1971 2019-07-12 57.45 3bea125eb5d5c2e7749131f47c129532
1972 2019-07-12 59.79 cf805cbca11936dc2cf4d91bf70bd018
1973 2019-07-12 62.92 ef18f1c0a7cdcc1939529415dfb07121
1974 2019-07-12 67.06 18334c39fe32df531c9eee53d78dcc59
1975 2019-07-12 69.56 a912eb5a82d38a770eb96e983f338b7c
1976 2019-07-12 68.77 979b8b73ba095d6934be45fb99353984
1977 2019-07-12 74.59 23aab0ffc2a285a1a6277fac17abcc60
1978 2019-07-12 81.26 0dfe35cc39c851308e156321e4869931
1979 2019-07-12 90.08 c60c8da0caa8eff457c1e25ac8be5bab
1980 2019-07-12 94.45 9ea640f62c3fefda961c2205c1cd2a8b
1981 2019-07-12 97.82 3a2796b07c0068f81e4cf5dcf69af73a
1982 2019-07-12 99.06 50397416aa54c269731361a168bce5fe
1983 2019-07-12 103.98 77cf6546f735f3252a519fd6151d798c
1984 2019-07-12 105.40 96f73fc3b8a9e86129fc09d8a0bd599c
1985 2019-07-12 108.69 2707dcf8f11026799dc41d6e29dc10de
1986 2019-07-12 112.20 6511ef673f03cb74565f4b2f465ace92
1987 2019-07-12 114.74 0c987f5cc04ed352b221de65a7b266e4
1988 2019-07-12 117.02 9c37a13dd9420fa3a33c89300154c17d
1989 2019-07-12 122.21 bd880d583a3134ce16996094d7d57dae
1990 2019-07-12 127.62 9fa73f8d95ff2afc39573b1d1da2298a
1991 2019-07-12 129.30 3d05d74c13a690906dc464ea8b9d3c2a
1992 2019-07-12 144.23 6069e0e21670e7907a96f08accf1336c
1993 2019-07-12 185.60 45132da198aa4dec77399971f3c6d50c
1994 2019-07-12 212.43 3da4f07744ec3c7e6e0ba9e4cc91c945
1995 2019-07-12 233.97 05babd17437353533cd63e991ee8da90
1996 2019-07-12 227.53 80fd59268917411f7ef6195ede5b70a5
1997 2019-07-12 274.33 c6cd85c9db7ee25352c367267997fb1d
1998 2019-07-12 297.57 7c744d9bddae2651513673a6e6722be9
1999 2019-07-12 319.00 dddff89a22af936fa0907d4666c7e083
2000 2019-07-12 362.02 f2ce7ef93487bc733502e4998cb642d2
2001 2019-07-12 385.40 9bd5f67f6407602245dd29441110a28d
2002 2019-07-12 379.10 d760a2c9e50e55ea7fef8d426bf80123
2003 2019-07-12 396.63 12ecbc2c17a584dc07bb2480a4981f6e
2004 2019-07-12 426.79 86d0b58fad2b8fab3406868ac2d201be
2005 2019-07-12 462.61 520c4d1b4484da5c3b222fdd5ecbeab3
2006 2019-07-12 485.55 4f9656edfcefc3226c7f1ce8470f883a
2007 2019-07-12 460.91 dc15b09517c523f849c0e91b58b4f869
2008 2019-07-12 491.27 3ed9270f32e447e3525a0cb1433e5856
2009 2019-07-12 516.27 99933c25e22cf64d8b162ed4f5db0592
2010 2019-07-12 541.07 4eea694c3d6142b7fd7139a8b6767f01
2011 2019-07-12 564.27 917accc22d3e382def56f29e1a6a1176
2012 2019-07-12 574.05 313289e8e0ff2c612686fde2de9779ec
2013 2019-07-12 598.92 23185d32ab0f170ad5e2e303ed1d04ec
2014 2019-07-12 609.68 8c5a1851c04025d6b664116e1b05acad
2015 2019-07-12 623.48 5f148d234ceefd43da62a41a6a329d74
2016 2019-07-12 632.51 3a4d439e5fd4f6ca1d777b6dfcd1310a
2017 2019-07-12 636.73 60e4c8d31bd5462fcac12c98db299c1b

4.5.3 Note for Windows users

If you use Windows the scripts will only use a single core because we used a parallelization that depends on fork system call that is only supported on Unix systems. You can always run the scripts on Windows and the only difference will be that it will use less RAM and processor, and it will be slower to compute.

Also, before running the scripts on Windows verify that you installed GNU Utilities beforehand. One easy option is to install Chocolatey first and then install the GNU Utilities by running choco install unxutils on Cmd or Power Shell as administrator.

4.5.4 Note for spreadsheets users

If you plan to use the datasets with a software such as Microsoft Excel, Libre Office Calc or similar, please use 7-zip to decompress the datasets. Also, be sure that your software reads the product_code column as character or it will trim codes starting with zero.