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_attributes_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 Econom…
#> 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 StatisticsThe 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_attributes_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_attributes_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 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: 58 x 5
#> product_code product_fullname_engli… group_code group_name type_product
#> <chr> <chr> <chr> <chr> <chr>
#> 1 0103 Swine; live 01 Animals; l… wine
#> 2 010310 Swine; live, pure-bred… 01 Animals; l… wine
#> 3 010391 Swine; live, (other th… 01 Animals; l… wine
#> 4 010392 Swine; live, (other th… 01 Animals; l… wine
#> 5 0203 Meat of swine; fresh, … 02 Meat and e… wine
#> 6 020311 Meat; of swine, carcas… 02 Meat and e… wine
#> 7 020312 Meat; of swine, hams, … 02 Meat and e… wine
#> 8 020319 Meat; of swine, n.e.c.… 02 Meat and e… wine
#> 9 020321 Meat; of swine, carcas… 02 Meat and e… wine
#> 10 020322 Meat; of swine, hams, … 02 Meat and e… wine
#> # … with 48 more rowsThis 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 1965:
ots_create_tidy_data(years = 1965, reporters = "chl", partners = "arg")
#> # A tibble: 317 x 16
#> year reporter_iso partner_iso reporter_fullna… partner_fullnam…
#> <int> <chr> <chr> <chr> <chr>
#> 1 1965 chl arg Chile Argentina
#> 2 1965 chl arg Chile Argentina
#> 3 1965 chl arg Chile Argentina
#> 4 1965 chl arg Chile Argentina
#> 5 1965 chl arg Chile Argentina
#> 6 1965 chl arg Chile Argentina
#> 7 1965 chl arg Chile Argentina
#> 8 1965 chl arg Chile Argentina
#> 9 1965 chl arg Chile Argentina
#> 10 1965 chl arg Chile Argentina
#> # … with 307 more rows, and 11 more variables: product_code <chr>,
#> # product_code_length <int>, product_fullname_english <chr>,
#> # group_code <chr>, group_name <chr>, export_value_usd <int>,
#> # import_value_usd <int>, export_value_usd_change_1_year <int>,
#> # export_value_usd_percentage_change_1_year <dbl>,
#> # import_value_usd_change_1_year <int>,
#> # import_value_usd_percentage_change_1_year <dbl>
# the same can be obtained specifying yrpc which is the default table
# ots_create_tidy_data(years = 1965, 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,1965), reporters = c("chl", "Peru", "bol"), partners = c("arg", "Brazil"))
#> # A tibble: 2,538 x 16
#> 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 2,528 more rows, and 11 more variables: product_code <chr>,
#> # product_code_length <int>, product_fullname_english <chr>,
#> # group_code <chr>, group_name <chr>, export_value_usd <int>,
#> # import_value_usd <int>, export_value_usd_change_1_year <int>,
#> # export_value_usd_percentage_change_1_year <dbl>,
#> # import_value_usd_change_1_year <int>,
#> # import_value_usd_percentage_change_1_year <dbl>If we want filtering by product, there are different options:
# Pass a specific HS code
ots_create_tidy_data(years = c(1962,1965), reporters = c("chl", "Peru", "bol"), partners = c("arg", "bra"), products = "0101")
#> # A tibble: 11 x 17
#> year reporter_iso partner_iso reporter_fullna… partner_fullnam…
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl arg Chile Argentina
#> 2 1965 chl arg Chile Argentina
#> 3 1962 bol arg Bolivia Argentina
#> 4 1965 bol arg Bolivia Argentina
#> 5 1962 per arg Peru Argentina
#> 6 1965 per arg Peru Argentina
#> 7 1962 chl bra Chile Brazil
#> 8 1965 chl bra Chile Brazil
#> 9 1965 bol bra Bolivia Brazil
#> 10 1962 per bra Peru Brazil
#> 11 1965 per bra Peru Brazil
#> # … with 12 more variables: product_code <chr>, product_code_length <int>,
#> # product_fullname_english <chr>, group_code <chr>, group_name <chr>,
#> # export_value_usd <int>, import_value_usd <int>,
#> # export_value_usd_change_1_year <int>,
#> # export_value_usd_percentage_change_1_year <dbl>,
#> # import_value_usd_change_1_year <int>,
#> # import_value_usd_percentage_change_1_year <dbl>, observation <chr>
# Pass a string that will return all matching descriptions and multiple HS codes
ots_create_tidy_data(years = c(1962,1965), reporters = c("chl", "Peru", "bol"), partners = c("arg", "bra"), products = c("0101", "apple"))
#> # A tibble: 27 x 17
#> year reporter_iso partner_iso reporter_fullna… partner_fullnam…
#> <int> <chr> <chr> <chr> <chr>
#> 1 1962 chl arg Chile Argentina
#> 2 1965 chl arg Chile Argentina
#> 3 1962 bol arg Bolivia Argentina
#> 4 1965 bol arg Bolivia Argentina
#> 5 1962 per arg Peru Argentina
#> 6 1965 per arg Peru Argentina
#> 7 1962 chl bra Chile Brazil
#> 8 1965 chl bra Chile Brazil
#> 9 1965 bol bra Bolivia Brazil
#> 10 1962 per bra Peru Brazil
#> # … with 17 more rows, and 12 more variables: product_code <chr>,
#> # product_code_length <int>, product_fullname_english <chr>,
#> # group_code <chr>, group_name <chr>, export_value_usd <int>,
#> # import_value_usd <int>, export_value_usd_change_1_year <int>,
#> # export_value_usd_percentage_change_1_year <dbl>,
#> # import_value_usd_change_1_year <int>,
#> # import_value_usd_percentage_change_1_year <dbl>, observation <chr>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.”)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 IDgroup_name: English name corresponding to group_idexport_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 1965:
ots_create_tidy_data(years = 1965, reporters = "chl", partners = "arg", table = "yrp")
#> # A tibble: 1 x 11
#> year reporter_iso partner_iso reporter_fullna… partner_fullnam…
#> <int> <chr> <chr> <chr> <chr>
#> 1 1965 chl arg Chile Argentina
#> # … with 6 more variables: export_value_usd <int>, import_value_usd <int>,
#> # export_value_usd_change_1_year <int>,
#> # export_value_usd_percentage_change_1_year <dbl>,
#> # import_value_usd_change_1_year <int>,
#> # import_value_usd_percentage_change_1_year <dbl>Another option is to pass more than one year, reporter and/or partner:
ots_create_tidy_data(years = 1962:1965, reporters = c("chl", "per"), partners = "arg", table = "yrp")
#> # A tibble: 8 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
#> 3 1964 chl arg Chile Argentina
#> 4 1965 chl arg Chile Argentina
#> 5 1962 per arg Peru Argentina
#> 6 1963 per arg Peru Argentina
#> 7 1964 per arg Peru Argentina
#> 8 1965 per arg Peru Argentina
#> # … with 6 more variables: export_value_usd <int>, import_value_usd <int>,
#> # export_value_usd_change_1_year <int>,
#> # export_value_usd_percentage_change_1_year <dbl>,
#> # import_value_usd_change_1_year <int>,
#> # import_value_usd_percentage_change_1_year <dbl>This table accepts different years, reporters and partners just like yrpc.
If we want Chilean trade at product level in 1965:
ots_create_tidy_data(years = 1965, reporters = "chl", table = "yrc")
#> # A tibble: 907 x 16
#> year reporter_iso reporter_fullna… product_code product_code_le…
#> <int> <chr> <chr> <chr> <int>
#> 1 1965 chl Chile 0101 4
#> 2 1965 chl Chile 0102 4
#> 3 1965 chl Chile 0103 4
#> 4 1965 chl Chile 0104 4
#> 5 1965 chl Chile 0105 4
#> 6 1965 chl Chile 0106 4
#> 7 1965 chl Chile 0201 4
#> 8 1965 chl Chile 0203 4
#> 9 1965 chl Chile 0204 4
#> 10 1965 chl Chile 0206 4
#> # … with 897 more rows, and 11 more variables:
#> # product_fullname_english <chr>, group_code <chr>, group_name <chr>,
#> # export_value_usd <int>, import_value_usd <int>,
#> # export_rca_4_digits_product_code <dbl>,
#> # import_rca_4_digits_product_code <dbl>,
#> # export_value_usd_change_1_year <int>,
#> # export_value_usd_percentage_change_1_year <dbl>,
#> # import_value_usd_change_1_year <int>,
#> # import_value_usd_percentage_change_1_year <dbl>If we want Chilean trade at product level in 1965 with respect to product “0101” (Horses, asses, mules and hinnies; live):
ots_create_tidy_data(years = 1965, reporters = "chl", products = "0101", table = "yrc")
#> # A tibble: 1 x 16
#> year reporter_iso reporter_fullna… product_code product_code_le…
#> <int> <chr> <chr> <chr> <int>
#> 1 1965 chl Chile 0101 4
#> # … with 11 more variables: product_fullname_english <chr>,
#> # group_code <chr>, group_name <chr>, export_value_usd <int>,
#> # import_value_usd <int>, export_rca_4_digits_product_code <dbl>,
#> # import_rca_4_digits_product_code <dbl>,
#> # export_value_usd_change_1_year <int>,
#> # export_value_usd_percentage_change_1_year <dbl>,
#> # import_value_usd_change_1_year <int>,
#> # import_value_usd_percentage_change_1_year <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 1965:
ots_create_tidy_data(years = 1965, reporters = "chl", table = "yr")
#> # A tibble: 1 x 16
#> year reporter_iso reporter_fullna… export_value_usd import_value_usd
#> <int> <chr> <chr> <int> <int>
#> 1 1965 chl Chile 1012377535 800177433
#> # … with 11 more variables: eci_4_digits_product_code <dbl>,
#> # eci_rank_4_digits_commodity_code <int>,
#> # eci_rank_4_digits_commodity_code_delta_1_year <int>,
#> # top_export_product_code <chr>, top_export_trade_value_usd <int>,
#> # top_import_product_code <chr>, top_import_trade_value_usd <int>,
#> # export_value_usd_change_1_year <int>,
#> # export_value_usd_percentage_change_1_year <dbl>,
#> # import_value_usd_change_1_year <int>,
#> # import_value_usd_percentage_change_1_year <dbl>Another option is to pass more than one year and/or reporter:
ots_create_tidy_data(years = 1962:1965, reporters = c("chl", "arg", "per"), table = "yr")
#> # A tibble: 12 x 16
#> year reporter_iso reporter_fullna… export_value_usd import_value_usd
#> <int> <chr> <chr> <int> <int>
#> 1 1962 chl Chile 686689403 695820595
#> 2 1963 chl Chile 684739946 771091879
#> 3 1964 chl Chile 838060302 724513056
#> 4 1965 chl Chile 1012377535 800177433
#> 5 1962 arg Argentina 1494178586 1786150048
#> 6 1963 arg Argentina 1687668737 1279500605
#> 7 1964 arg Argentina 1756784616 1481487424
#> 8 1965 arg Argentina 1893170943 1697743561
#> 9 1962 per Peru 676343986 601437849
#> 10 1963 per Peru 785444440 651334910
#> 11 1964 per Peru 907176474 682595972
#> 12 1965 per Peru 885166337 831010422
#> # … with 11 more variables: eci_4_digits_product_code <dbl>,
#> # eci_rank_4_digits_commodity_code <int>, top_export_product_code <chr>,
#> # top_export_trade_value_usd <int>, top_import_product_code <chr>,
#> # top_import_trade_value_usd <int>,
#> # eci_rank_4_digits_commodity_code_delta_1_year <int>,
#> # export_value_usd_change_1_year <int>,
#> # export_value_usd_percentage_change_1_year <dbl>,
#> # import_value_usd_change_1_year <int>,
#> # import_value_usd_percentage_change_1_year <dbl>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 1965:
ots_create_tidy_data(years = 1965, table = "yc")
#> # A tibble: 991 x 19
#> year product_code product_code_le… product_fullnam… group_code
#> <int> <chr> <int> <chr> <chr>
#> 1 1965 0101 4 Horses, asses, … 01
#> 2 1965 0102 4 Bovine animals;… 01
#> 3 1965 0103 4 Swine; live 01
#> 4 1965 0104 4 Sheep and goats… 01
#> 5 1965 0105 4 Poultry; live, … 01
#> 6 1965 0106 4 Animals, n.e.c.… 01
#> 7 1965 0201 4 Meat of bovine … 02
#> 8 1965 0203 4 Meat of swine; … 02
#> 9 1965 0204 4 Meat of sheep o… 02
#> 10 1965 0205 4 Meat of horses,… 02
#> # … with 981 more rows, and 14 more variables: group_name <chr>,
#> # export_value_usd <dbl>, import_value_usd <dbl>,
#> # pci_4_digits_product_code <dbl>, pci_rank_4_digits_product_code <int>,
#> # pci_rank_4_digits_product_code_delta_1_year <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_percentage_change_1_year <dbl>,
#> # import_value_usd_change_1_year <int>,
#> # import_value_usd_percentage_change_1_year <dbl>If we want traded values of product “0101” (Horses, asses, mules and hinnies; live) in 1965:
ots_create_tidy_data(years = 1965, products = "0101", table = "yc")
#> # A tibble: 1 x 19
#> year product_code product_code_le… product_fullnam… group_code
#> <int> <chr> <int> <chr> <chr>
#> 1 1965 0101 4 Horses, asses, … 01
#> # … with 14 more variables: group_name <chr>, export_value_usd <int>,
#> # import_value_usd <int>, pci_4_digits_product_code <dbl>,
#> # pci_rank_4_digits_product_code <int>,
#> # pci_rank_4_digits_product_code_delta_1_year <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_percentage_change_1_year <dbl>,
#> # import_value_usd_change_1_year <int>,
#> # import_value_usd_percentage_change_1_year <dbl>This table accepts different product codes just like yrpc.
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