Provided that this package obtains data from an API, it is useful to know which tables can be accessed:
library(tradestatistics)
#>
#> Welcome to tradestatistics package. If you are going to use this
#> package, it means that you are ok with the usage conditions explained
#> on https://docs.tradestatistics.io/datasets.html#code-of-conduct
#>
#> Commercial purposes are strictly out of the boundaries of what you
#> can do with this data according to UN Comtrade dissemination clauses.
#>
#> Our contents are distributed under Creative Commons
#> Attribution-NonCommercial 4.0 International License.
#>
ots_tables
#> # A tibble: 16 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 Econom~
#> 6 country_r~ Ranking of countries Open Trade Statistics
#> 7 product_r~ Ranking of products Open Trade Statistics
#> 8 yrpc Bilateral trade at product level ~ Open Trade Statistics
#> 9 yrp Reporter trade at aggregated leve~ Open Trade Statistics
#> 10 yrp_short Reporter trade at aggregated leve~ Open Trade Statistics
#> 11 yrc Reporter trade at aggregated leve~ Open Trade Statistics
#> 12 yrc_expor~ Reporter trade at aggregated leve~ Open Trade Statistics
#> 13 yrc_impor~ Reporter trade at aggregated leve~ Open Trade Statistics
#> 14 yr Reporter trade at aggregated leve~ Open Trade Statistics
#> 15 yr_short Reporter trade at aggregated leve~ Open Trade Statistics
#> 16 yc Product trade at aggregated level~ Open Trade Statistics
The Package Functions section explains that you don’t need to memorize all ISO codes. The functions within this package are designed to match strings (i.e. “United States” or “America”) to valid ISO codes (i.e. “USA”).
Just as a reference, the table with all valid ISO codes can be accessed by running this:
ots_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>
The Package Functions section explains that you don’t need to memorize all HS codes. The functions within this package are designed to match strings (i.e. “apple”) to valid HS codes (i.e. “0808”).
ots_products
#> # A tibble: 1,320 x 4
#> product_code product_fullname_english group_code group_name
#> <chr> <chr> <chr> <chr>
#> 1 0101 Horses, asses, mules and hinnies~ 01 Animals; live
#> 2 0102 Bovine animals; live 01 Animals; live
#> 3 0103 Swine; live 01 Animals; live
#> 4 0104 Sheep and goats; live 01 Animals; live
#> 5 0105 Poultry; live, fowls of the spec~ 01 Animals; live
#> 6 0106 Animals, n.e.c. in chapter 01; l~ 01 Animals; live
#> 7 0201 Meat of bovine animals; fresh or~ 02 Meat and edib~
#> 8 0202 Meat of bovine animals; frozen 02 Meat and edib~
#> 9 0203 Meat of swine; fresh, chilled or~ 02 Meat and edib~
#> 10 0204 Meat of sheep or goats; fresh, c~ 02 Meat and edib~
#> # ... with 1,310 more rows
ots_product_shortnames
#> # A tibble: 1,222 x 2
#> product_code product_shortname_english
#> <chr> <chr>
#> 1 0101 Horses
#> 2 0102 Bovine
#> 3 0103 Pigs
#> 4 0104 Sheep and Goats
#> 5 0105 Poultry
#> 6 0106 Other Animals
#> 7 0201 Bovine Meat
#> 8 0202 Frozen Bovine Meat
#> 9 0203 Pig Meat
#> 10 0204 Sheep and Goat Meat
#> # ... with 1,212 more rows
ots_communities
#> # A tibble: 1,222 x 4
#> product_code community_code community_name community_color
#> <chr> <chr> <chr> <chr>
#> 1 0101 01 Animal Products #74c0e2
#> 2 0102 01 Animal Products #74c0e2
#> 3 0103 01 Animal Products #74c0e2
#> 4 0104 01 Animal Products #74c0e2
#> 5 0105 01 Animal Products #74c0e2
#> 6 0106 01 Animal Products #74c0e2
#> 7 0201 01 Animal Products #74c0e2
#> 8 0202 01 Animal Products #74c0e2
#> 9 0203 01 Animal Products #74c0e2
#> 10 0204 01 Animal Products #74c0e2
#> # ... with 1,212 more rows
This table is provided to be used with ots_inflation_adjustment()
.
ots_inflation
#> from to conversion_factor
#> 1 1962 1963 1.0308
#> 2 1963 1964 1.0338
#> 3 1964 1965 1.0412
#> 4 1965 1966 1.0532
#> 5 1966 1967 1.0354
#> 6 1967 1968 1.0398
#> 7 1968 1969 1.0364
#> 8 1969 1970 1.0502
#> 9 1970 1971 1.0546
#> 10 1971 1972 1.0588
#> 11 1972 1973 1.0917
#> 12 1973 1974 1.1540
#> 13 1974 1975 1.1247
#> 14 1975 1976 1.0969
#> 15 1976 1977 1.1035
#> 16 1977 1978 1.0862
#> 17 1978 1979 1.1010
#> 18 1979 1980 1.1374
#> 19 1980 1981 1.1284
#> 20 1981 1982 1.1038
#> 21 1982 1983 1.0937
#> 22 1983 1984 1.0904
#> 23 1984 1985 1.0868
#> 24 1985 1986 1.0650
#> 25 1986 1987 1.0698
#> 26 1987 1988 1.0997
#> 27 1988 1989 1.1464
#> 28 1989 1990 1.2329
#> 29 1990 1991 1.1104
#> 30 1991 1992 1.1096
#> 31 1992 1993 1.2079
#> 32 1993 1994 1.2389
#> 33 1994 1995 1.0915
#> 34 1995 1996 1.0651
#> 35 1996 1997 1.0472
#> 36 1997 1998 1.0439
#> 37 1998 1999 1.0342
#> 38 1999 2000 1.0368
#> 39 2000 2001 1.0379
#> 40 2001 2002 1.0295
#> 41 2002 2003 1.0310
#> 42 2003 2004 1.0317
#> 43 2004 2005 1.0363
#> 44 2005 2006 1.0378
#> 45 2006 2007 1.0407
#> 46 2007 2008 1.0695
#> 47 2008 2009 1.0233
#> 48 2009 2010 1.0299
#> 49 2010 2011 1.0450
#> 50 2011 2012 1.0348
#> 51 2012 2013 1.0274
#> 52 2013 2014 1.0228
#> 53 2014 2015 1.0151
#> 54 2015 2016 1.0157
#> 55 2016 2017 1.0241
#> 56 2017 2018 1.0258
The end user can use this function to find an ISO code by providing a country name. This works by implementing partial search.
Basic examples:
# Single match with no replacement
ots_country_code("Chile")
#> # A tibble: 1 x 6
#> country_iso country_name_en~ country_fullnam~ continent_id continent
#> <chr> <chr> <chr> <int> <chr>
#> 1 chl Chile Chile 5 Americas
#> # ... with 1 more variable: eu28_member <int>
# Single match with replacement
ots_country_code("America")
#> # A tibble: 1 x 6
#> country_iso country_name_en~ country_fullnam~ continent_id continent
#> <chr> <chr> <chr> <int> <chr>
#> 1 usa USA USA, Puerto Ric~ 5 Americas
#> # ... with 1 more variable: eu28_member <int>
# Double match with no replacement
ots_country_code("Germany")
#> # A tibble: 2 x 6
#> country_iso country_name_en~ country_fullnam~ continent_id continent
#> <chr> <chr> <chr> <int> <chr>
#> 1 ddr Fmr Dem. Rep. o~ Fmr Dem. Rep. o~ 2 Europe
#> 2 deu Germany Germany (former~ 2 Europe
#> # ... with 1 more variable: eu28_member <int>
The function ots_country_code()
is used by ots_create_tidy_data()
in a way that you can pass parameters like ots_create_tidy_data(... reporters = "Chile" ...)
and it will automatically replace your input for a valid ISO in case there is a match. This will be covered in detail in the Trade Data section.
The end user can use this function to find a product code by providing a product name. This works by implementing partial string matching:
ots_product_code("wine")
#> # A tibble: 12 x 5
#> product_code product_fullname_en~ group_code group_name type_product
#> <chr> <chr> <chr> <chr> <chr>
#> 1 0103 Swine; live 01 Animals; live wine
#> 2 0203 Meat of swine; fres~ 02 Meat and edib~ wine
#> 3 0206 Edible offal of bov~ 02 Meat and edib~ wine
#> 4 2204 Wine of fresh grape~ 22 Beverages, sp~ wine
#> 5 2205 Vermouth and other ~ 22 Beverages, sp~ wine
#> 6 2307 Wine lees; argol 23 Food industri~ wine
#> 7 5607 Twine, cordage, rop~ 56 Wadding, felt~ wine
#> 8 5608 Twine, cordage or r~ 56 Wadding, felt~ wine
#> 9 5609 Articles of yarn, s~ 56 Wadding, felt~ wine
#> 10 6310 Rags; used or new, ~ 63 Textiles, mad~ wine
#> 11 8435 Presses, crushers a~ 84 Nuclear react~ wine
#> 12 56 Alias for all codes~ <NA> <NA> wine
This function downloads data for a single year and needs (at least) some filter parameters according to the query type.
If we want Chile-Argentina bilateral trade at product level in 1962:
ots_create_tidy_data(years = 1962, reporters = "chl", partners = "arg")
#> # A tibble: 194 x 11
#> year reporter_iso partner_iso reporter_fullna~ partner_fullnam~
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl arg Chile Argentina
#> 2 1962 chl arg Chile Argentina
#> 3 1962 chl arg Chile Argentina
#> 4 1962 chl arg Chile Argentina
#> 5 1962 chl arg Chile Argentina
#> 6 1962 chl arg Chile Argentina
#> 7 1962 chl arg Chile Argentina
#> 8 1962 chl arg Chile Argentina
#> 9 1962 chl arg Chile Argentina
#> 10 1962 chl arg Chile Argentina
#> # ... with 184 more rows, and 6 more variables: product_code <chr>,
#> # product_fullname_english <chr>, group_code <chr>, group_name <chr>,
#> # import_value_usd <int>, export_value_usd <int>
# the same can be obtained specifying yrpc which is the default table
# ots_create_tidy_data(years = 1962, reporters = "chl", partners = "arg", table = "yrpc")
We can pass more than one year and or reporter/partner:
# Note that here I'm passing Peru and not per which is the ISO code for Peru
# The same applies to Brazil
ots_create_tidy_data(years = c(1962,1963), reporters = c("chl", "Peru", "bol"), partners = c("arg", "Brazil"))
#> # A tibble: 423 x 11
#> year reporter_iso partner_iso reporter_fullna~ partner_fullnam~
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl arg Chile Argentina
#> 2 1962 chl arg Chile Argentina
#> 3 1962 chl arg Chile Argentina
#> 4 1962 chl arg Chile Argentina
#> 5 1962 chl arg Chile Argentina
#> 6 1962 chl arg Chile Argentina
#> 7 1962 chl arg Chile Argentina
#> 8 1962 chl arg Chile Argentina
#> 9 1962 chl arg Chile Argentina
#> 10 1962 chl arg Chile Argentina
#> # ... with 413 more rows, and 6 more variables: product_code <chr>,
#> # product_fullname_english <chr>, group_code <chr>, group_name <chr>,
#> # import_value_usd <int>, export_value_usd <int>
If we want filtering by product, there are different options:
# Pass a specific HS code
ots_create_tidy_data(years = c(1962,1963), reporters = c("chl", "Peru", "bol"), partners = c("arg", "bra"), products = "0101")
#> # A tibble: 2 x 11
#> year reporter_iso partner_iso reporter_fullna~ partner_fullnam~
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl arg Chile Argentina
#> 2 1963 chl arg Chile Argentina
#> # ... with 6 more variables: product_code <chr>,
#> # product_fullname_english <chr>, group_code <chr>, group_name <chr>,
#> # export_value_usd <int>, import_value_usd <int>
# Pass a string that will return all matching descriptions and multiple HS codes
ots_create_tidy_data(years = c(1962,1963), reporters = c("chl", "Peru", "bol"), partners = c("arg", "bra"), products = c("0101", "apple"))
#> # A tibble: 2 x 11
#> year reporter_iso partner_iso reporter_fullna~ partner_fullnam~
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl arg Chile Argentina
#> 2 1963 chl arg Chile Argentina
#> # ... with 6 more variables: product_code <chr>,
#> # product_fullname_english <chr>, group_code <chr>, group_name <chr>,
#> # export_value_usd <int>, import_value_usd <int>
yrpc
table returns some fields that deserve an explanation:
product_code
: HS07 product codes (e.g. according to the table within this package, 0101 stands for “Horses, etc.”)group_code
: International categorization of group products defined after product IDgroup_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 yearexport_value_usd_percentage_change_5_years
: Nominal increase/decrease in exports measured as percentage with respect to five years agoexport_value_usd_change_1_year
: Nominal increase/decrease in exports measured in USD with respect to last yearexport_value_usd_change_5_years
: Nominal increase/decrease in exports measured in USD with respect to five years agoIf we want Chile-Argentina bilateral trade at aggregated level in 1962:
ots_create_tidy_data(years = 1962, reporters = "chl", partners = "arg", table = "yrp")
#> # A tibble: 1 x 7
#> year reporter_iso partner_iso reporter_fullna~ partner_fullnam~
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl arg Chile Argentina
#> # ... with 2 more variables: export_value_usd <int>,
#> # import_value_usd <int>
Another option is to pass more than one year, reporter and/or partner:
ots_create_tidy_data(years = 1962:1963, reporters = c("chl", "per"), partners = "arg", table = "yrp")
#> # A tibble: 2 x 7
#> year reporter_iso partner_iso reporter_fullna~ partner_fullnam~
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl arg Chile Argentina
#> 2 1963 chl arg Chile Argentina
#> # ... with 2 more variables: export_value_usd <int>,
#> # import_value_usd <int>
This table accepts different years, reporters and partners just like yrpc
.
If we want Chilean trade at product level in 1962:
ots_create_tidy_data(years = 1962, reporters = "chl", table = "yrc")
#> # A tibble: 512 x 11
#> year reporter_iso reporter_fullna~ product_code product_fullnam~
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl Chile 9999 Commodities not~
#> 2 1962 chl Chile 9701 Paintings, draw~
#> 3 1962 chl Chile 9616 Scent sprays an~
#> 4 1962 chl Chile 9608 Pens; ball-poin~
#> 5 1962 chl Chile 9601 Ivory, bone, to~
#> 6 1962 chl Chile 9508 Roundabouts, sw~
#> 7 1962 chl Chile 9507 Fishing rods, f~
#> 8 1962 chl Chile 9503 Tricycles, scoo~
#> 9 1962 chl Chile 9401 Seats (not thos~
#> 10 1962 chl Chile 9306 Bombs, grenades~
#> # ... with 502 more rows, and 6 more variables: group_code <chr>,
#> # group_name <chr>, export_value_usd <int>, import_value_usd <int>,
#> # export_rca <dbl>, import_rca <dbl>
If we want Chilean trade at product level in 1962 with respect to product “0101” (Horses, asses, mules and hinnies; live):
ots_create_tidy_data(years = 1962, reporters = "chl", products = "0101", table = "yrc")
#> # A tibble: 1 x 11
#> year reporter_iso reporter_fullna~ product_code product_fullnam~
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl Chile 0101 Horses, asses, ~
#> # ... with 6 more variables: group_code <chr>, group_name <chr>,
#> # export_value_usd <int>, import_value_usd <int>, export_rca <dbl>,
#> # import_rca <dbl>
This table accepts different years, reporters and product codes just like yrpc
.
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.
If we want Chilean trade at aggregated level in 1962:
ots_create_tidy_data(years = 1962, reporters = "chl", table = "yr")
#> # A tibble: 1 x 15
#> year reporter_iso reporter_fullna~ export_value_usd import_value_usd
#> <int> <chr> <chr> <int> <int>
#> 1 1962 chl Chile 633574770 695158161
#> # ... with 10 more variables: eci_fitness_method <dbl>,
#> # eci_rank_fitness_method <int>, eci_reflections_method <dbl>,
#> # eci_rank_reflections_method <int>, eci_eigenvalues_method <dbl>,
#> # eci_rank_eigenvalues_method <int>, top_export_product_code <chr>,
#> # top_export_trade_value_usd <int>, top_import_product_code <chr>,
#> # top_import_trade_value_usd <int>
Another option is to pass more than one year and/or reporter:
ots_create_tidy_data(years = 1962:1963, reporters = c("chl", "arg", "per"), table = "yr")
#> # A tibble: 2 x 15
#> year reporter_iso reporter_fullna~ export_value_usd import_value_usd
#> <int> <chr> <chr> <int> <int>
#> 1 1962 chl Chile 633574770 695158161
#> 2 1963 chl Chile 654719784 746808156
#> # ... with 10 more variables: eci_fitness_method <dbl>,
#> # eci_rank_fitness_method <int>, eci_reflections_method <dbl>,
#> # eci_rank_reflections_method <int>, eci_eigenvalues_method <dbl>,
#> # eci_rank_eigenvalues_method <int>, top_export_product_code <chr>,
#> # top_export_trade_value_usd <int>, top_import_product_code <chr>,
#> # top_import_trade_value_usd <int>
This table accepts different years and reporters just like yrpc
.
Here some fields deserve an explanation:
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 yearIf we want all products traded in 1962:
ots_create_tidy_data(years = 1962, table = "yc")
#> # A tibble: 539 x 17
#> year product_code product_fullnam~ group_code group_name
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 9999 Commodities not~ 99 Commoditi~
#> 2 1962 9701 Paintings, draw~ 97 Works of ~
#> 3 1962 9616 Scent sprays an~ 96 Miscellan~
#> 4 1962 9608 Pens; ball-poin~ 96 Miscellan~
#> 5 1962 9601 Ivory, bone, to~ 96 Miscellan~
#> 6 1962 9508 Roundabouts, sw~ 95 Toys, gam~
#> 7 1962 9507 Fishing rods, f~ 95 Toys, gam~
#> 8 1962 9503 Tricycles, scoo~ 95 Toys, gam~
#> 9 1962 9401 Seats (not thos~ 94 Furniture~
#> 10 1962 9306 Bombs, grenades~ 93 Arms and ~
#> # ... with 529 more rows, and 12 more variables: export_value_usd <dbl>,
#> # import_value_usd <dbl>, pci_fitness_method <dbl>,
#> # pci_rank_fitness_method <int>, pci_reflections_method <dbl>,
#> # pci_rank_reflections_method <int>, pci_eigenvalues_method <dbl>,
#> # pci_rank_eigenvalues_method <int>, top_exporter_iso <chr>,
#> # top_exporter_trade_value_usd <int>, top_importer_iso <chr>,
#> # top_importer_trade_value_usd <int>
If we want traded values of product “0101” (Horses, asses, mules and hinnies; live) in 1962:
ots_create_tidy_data(years = 1962, products = "0101", table = "yc")
#> # A tibble: 1 x 17
#> year product_code product_fullnam~ group_code group_name
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 0101 Horses, asses, ~ 01 Animals; ~
#> # ... with 12 more variables: export_value_usd <int>,
#> # import_value_usd <int>, pci_fitness_method <dbl>,
#> # pci_rank_fitness_method <int>, pci_reflections_method <dbl>,
#> # pci_rank_reflections_method <int>, pci_eigenvalues_method <dbl>,
#> # pci_rank_eigenvalues_method <int>, top_exporter_iso <chr>,
#> # top_exporter_trade_value_usd <int>, top_importer_iso <chr>,
#> # top_importer_trade_value_usd <int>
This table accepts different product codes just like yrpc
.
Here some fields deserve an explanation:
pci_*_method
: Product Complexity Index (PCI) which is detailed on Open Trade Statistics Documentation.pci_rank_4_*_method
: The rank of a product given its PCI (e.g. the highest PCI obtains the #1)Taking Year - Reporter table as an example, we can use ots_inflation_adjustment()
to convert dollars from 1962 to dollars of 1970:
library(magrittr)
ots_create_tidy_data(years = 1962, reporters = "chl", table = "yr") %>%
ots_inflation_adjustment(reference_year = 1970)
#> # A tibble: 1 x 17
#> year reporter_iso reporter_fullna~ export_value_usd import_value_usd
#> <int> <chr> <chr> <dbl> <dbl>
#> 1 1962 chl Chile 867583361. 951912359.
#> # ... with 12 more variables: eci_fitness_method <dbl>,
#> # eci_rank_fitness_method <int>, eci_reflections_method <dbl>,
#> # eci_rank_reflections_method <int>, eci_eigenvalues_method <dbl>,
#> # eci_rank_eigenvalues_method <int>, top_export_product_code <chr>,
#> # top_export_trade_value_usd <int>, top_import_product_code <chr>,
#> # top_import_trade_value_usd <int>, conversion_year <dbl>,
#> # conversion_factor <dbl>