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-03-07 9.19 84477a24805a38c6cbc5628bb9989c5d
1963 2019-03-07 23.87 a4b82361ea01cad29e96eec88ba4b06e
1964 2019-03-07 26.84 0f7637240ac6927d1815af00c0542ec1
1965 2019-03-07 29.69 8683f312ff80d02a4b61c08f140c00ac
1966 2019-03-07 31.81 231a5ca9b61ce718172e33f71d96b672
1967 2019-03-07 44.65 9d2e25839d96565143c52510413c9cb3
1968 2019-03-07 47.85 501a53a5b0947855f260f829e8406170
1969 2019-03-07 50.47 999374dd5bca901bbfa483254d30e970
1970 2019-03-07 54.27 c8c1d57d2233a535f1bf7e308aa6e1fb
1971 2019-03-07 57.00 d558e969451505e9c05d9456cf6188bd
1972 2019-03-07 59.30 e9362865dea2c7719b89864bac922743
1973 2019-03-07 62.38 9636432c2cfe68a1674080e27e178117
1974 2019-03-07 66.50 ed1f10fd090ee9611f2738ee943092f1
1975 2019-03-07 68.99 a8cef1ae737e018d0aea5ed363fb0131
1976 2019-03-07 68.18 418c26342125d85cba55b090b7a5d40a
1977 2019-03-07 73.94 4152185126c252d30d393c1cd78bc74e
1978 2019-03-07 80.57 0d9b36937d3493791fe39fd2b6c4b4b6
1979 2019-03-07 89.33 cf1234f1993638a731feb497904fa71f
1980 2019-03-07 93.72 9c39a54594545b1da475cd8d054ffd75
1981 2019-03-07 97.12 38ff527ef186c80218d60c566b7a3169
1982 2019-03-07 98.41 6acba824c5cdfc49c8c1e63848df7da0
1983 2019-03-07 103.35 8b399cfcd890112eb1df732aa24c99c8
1984 2019-03-07 104.76 e9b0eb5037c76f210297aa6c41132725
1985 2019-03-07 108.06 ab9489f6f76600941246e6d4021b75f6
1986 2019-03-07 111.57 06d2ef903c3faeb36553191950be15a8
1987 2019-03-07 114.11 c8c8c3e4645f12a74c5a6a6d45b07106
1988 2019-03-07 116.44 67a8f8d2ad4ed2b2144d24055e2be157
1989 2019-03-07 121.48 13f59d05ba8c16337e5f617f6ab7a06f
1990 2019-03-07 126.79 45e096876dea810c8dfa09015bbd4ed9
1991 2019-03-07 128.31 176dcb2d7e665ef312068a44be3ee62a
1992 2019-03-07 142.85 b00f8e689c4bcc5685efd550ebefc162
1993 2019-03-07 183.53 224f0d66615357b4ac90514df7f71c2e
1994 2019-03-07 209.98 2d2f8d50cde7b62cc1ff5c4932c331b3
1995 2019-03-07 231.29 d4ac9be2216a3e21a65b6809fa4a3de0
1996 2019-03-07 225.08 1f7b623f602f48fee4fee4ef2f029631
1997 2019-03-07 271.01 bf63b8a4a5fdcd285987961a5d6d2aea
1998 2019-03-07 293.61 430291880b2e0c9146f3934365a5ee76
1999 2019-03-07 314.98 e256b077c726e7c1e19e32660978d207
2000 2019-03-07 357.59 0cb0779665c74c50de50a2b2452575bd
2001 2019-03-07 380.78 e289068eb4dc19233a6b022382ef319c
2002 2019-03-07 374.03 d3268ee697c8419ddb22c15a3068eb41
2003 2019-03-07 390.76 846898383579a0dc429c3f426219c8bc
2004 2019-03-07 419.84 f51afa26fbbf5a573e2024e5606fabfe
2005 2019-03-07 454.80 184ec668a0ae951adcf9676972417987
2006 2019-03-07 477.17 8e4b04997b5cb9f0d7b68c5bc4954cd7
2007 2019-03-07 452.87 59d941b8b62234305219daf3724f95c8
2008 2019-03-07 482.61 300019d3b9c00af175fc8cf8fbd1c8fe
2009 2019-03-07 507.08 74ab397eccd8b142b85e2452644358f8
2010 2019-03-07 531.34 3640d6974f469d76ac1fbcc84eafd8bc
2011 2019-03-07 553.89 0ed3c2a4c1fb19e6862814a7df7b0718
2012 2019-03-07 563.45 934517182c4be17e6e5ecafe9096b7c6
2013 2019-03-07 586.78 c8113d86337ac3ed2a49bd02fb0a6cec
2014 2019-03-07 596.02 21b9b86a9f47211f88b9ce94590035b6
2015 2019-03-07 606.73 e5da3f931174ba515488d940fd6cdc37
2016 2019-03-07 613.93 15cae25df67ebcc4860fb688d21b537a
2017 2019-03-07 610.42 d6c8becaa0c034c46906fefb2164d6ca

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.