This vignette explains the functions within this package. The idea is to show how this package simplifies obtaining data from (api.tradestatistics.io)[https://api.tradestatistics.io].
To improve the presentation of the tables I shall use
tibble besides tradestatistics.
Provided that this package obtains data from an API, it is useful to know which tables can be accessed:
as_tibble(ots_tables)
#> # A tibble: 11 × 3
#> table description source
#> <chr> <chr> <chr>
#> 1 commodities Commodities metadata (HS codes, 6 digits long) Based…
#> 2 commodities_short Commodities metadata (HS codes, 4 digits long) Based…
#> 3 countries Countries metadata Based…
#> 4 gdp_deflator GDP deflator (2020 = 100) Based…
#> 5 sections Sections metadata (HS codes) Based…
#> 6 year_range Minimum and maximum years with available data Based…
#> 7 yc Commodity trade at aggregated level (Year and Commo… Based…
#> 8 yr Reporter trade at aggregated level (Year and Report… Based…
#> 9 yrc Reporter trade at commodity level (Year, Reporter a… Based…
#> 10 yrp Reporter-Partner trade at aggregated level (Year, R… Based…
#> 11 yrpc Reporter-Partner trade at commodity level (Year, Re… Based…You might notice the tables have a pattern. The letters indicate the presence of columns that account for the level of detail in the data:
y: year column.r: reporter columnp: partner columnc: commodity columnThe most aggregated table is yr which basically says how
many dollars each country exports and imports for a given year.
The less aggregated table is yrpc which says how many
dollars of each of the 1,242 commodities from the Harmonized System each
country exports to other countries and imports from other countries.
For the complete detail you can check tradestatistics.io.
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:
as_tibble(ots_countries)
#> # A tibble: 263 × 5
#> country_iso country_name continent_id continent_name continent_color
#> <chr> <chr> <int> <chr> <chr>
#> 1 DZA Algeria 1 Africa #74c0e2
#> 2 AGO Angola 1 Africa #74c0e2
#> 3 BEN Benin 1 Africa #74c0e2
#> 4 BWA Botswana 1 Africa #74c0e2
#> 5 IOT Br. Indian Ocean Ter… 1 Africa #74c0e2
#> 6 BFA Burkina Faso 1 Africa #74c0e2
#> 7 BDI Burundi 1 Africa #74c0e2
#> 8 CPV Cabo Verde 1 Africa #74c0e2
#> 9 CMR Cameroon 1 Africa #74c0e2
#> 10 CAF Central African Rep. 1 Africa #74c0e2
#> # ℹ 253 more rowsThe 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”).
as_tibble(ots_commodities)
#> # A tibble: 6,898 × 8
#> commodity_code commodity_code_short commodity_name chapter_code chapter_name
#> <chr> <chr> <chr> <chr> <chr>
#> 1 010121 0101 Horses; live, … 01 Animals; li…
#> 2 010129 0101 Horses; live, … 01 Animals; li…
#> 3 010130 0101 Asses; live 01 Animals; li…
#> 4 010190 0101 Mules and hinn… 01 Animals; li…
#> 5 010221 0102 Cattle; live, … 01 Animals; li…
#> 6 010229 0102 Cattle; live, … 01 Animals; li…
#> 7 010231 0102 Buffalo; live,… 01 Animals; li…
#> 8 010239 0102 Buffalo; live,… 01 Animals; li…
#> 9 010290 0102 Bovine animals… 01 Animals; li…
#> 10 010310 0103 Swine; live, p… 01 Animals; li…
#> # ℹ 6,888 more rows
#> # ℹ 3 more variables: section_code <chr>, section_name <chr>,
#> # section_color <chr>This table is provided to be used with
ots_gdp_deflator_adjustment().
as_tibble(ots_gdp_deflator)
#> # A tibble: 7,070 × 4
#> year_from year_to country_iso gdp_deflator
#> <int> <int> <chr> <dbl>
#> 1 1988 1989 ABW 1.04
#> 2 1989 1990 ABW 1.06
#> 3 1990 1991 ABW 1.06
#> 4 1991 1992 ABW 1.04
#> 5 1992 1993 ABW 1.05
#> 6 1993 1994 ABW 1.06
#> 7 1994 1995 ABW 1.03
#> 8 1995 1996 ABW 1.03
#> 9 1996 1997 ABW 1.04
#> 10 1997 1998 ABW 1.07
#> # ℹ 7,060 more rowsThe 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
as_tibble(ots_country_code("Chile"))
#> # A tibble: 1 × 5
#> country_iso country_name continent_id continent_name continent_color
#> <chr> <chr> <int> <chr> <chr>
#> 1 CHL Chile 2 Americas #406662
# Single match with replacement
as_tibble(ots_country_code("America"))
#> # A tibble: 0 × 5
#> # ℹ 5 variables: country_iso <chr>, country_name <chr>, continent_id <int>,
#> # continent_name <chr>, continent_color <chr>
# Double match with no replacement
as_tibble(ots_country_code("Germany"))
#> # A tibble: 2 × 5
#> country_iso country_name continent_id continent_name continent_color
#> <chr> <chr> <int> <chr> <chr>
#> 1 DDR Dem. Rep. of Germany … 4 Europe #8abdb6
#> 2 DEU Germany 4 Europe #8abdb6The 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 find a code or a set of codes by looking for
keywords for commodities or groups. The function
ots_commodity_code() allows to search from the official
commodities and groups in the Harmonized system:
as_tibble(ots_commodity_code(commodity = " Horse ", section = " ANIMAL "))
#> # A tibble: 13 × 6
#> commodity_code commodity_name chapter_code chapter_name section_code
#> <chr> <chr> <chr> <chr> <chr>
#> 1 010121 Horses; live, pure-bre… 01 Animals; li… 01
#> 2 010129 Horses; live, other th… 01 Animals; li… 01
#> 3 020500 Meat; of horses, asses… 02 Meat and ed… 01
#> 4 020680 Offal, edible; of shee… 02 Meat and ed… 01
#> 5 020690 Offal, edible; of shee… 02 Meat and ed… 01
#> 6 030245 Fish; fresh or chilled… 03 Fish and cr… 01
#> 7 030355 Fish; frozen, jack and… 03 Fish and cr… 01
#> 8 030554 Dried herrings, anchov… 03 Fish and cr… 01
#> 9 050290 Animal products; badge… 05 Animal orig… 01
#> 10 010110 Horses, asses, mules a… 01 Animals; li… 01
#> 11 050300 Animal products; horse… 05 Animal orig… 01
#> 12 010111 Horses; live, pure-bre… 01 Animals; li… 01
#> 13 010119 Horses; live, other th… 01 Animals; li… 01
#> # ℹ 1 more variable: section_name <chr>This function downloads data for a single year and needs (at least) some filter parameters according to the query type.
Here we cover aggregated tables to describe the usage.
If we want Chile-Argentina bilateral trade at community level in 2019:
yrpc <- ots_create_tidy_data(
years = 2019,
reporters = "chl",
partners = "arg",
table = "yrpc"
)
as_tibble(yrpc)We can pass two years or more, several reporters/partners, and filter by commodities with exact codes or code matching based on keywords:
# Note that here I'm passing Peru and not per which is the ISO code for Peru
# The same applies to Brazil
yrpc2 <- ots_create_tidy_data(
years = 2018:2019,
reporters = c("chl", "Peru", "bol"),
partners = c("arg", "Brazil"),
commodities = c("01", "food"),
table = "yrpc"
)The yrpc table returns some fields that deserve an
explanation which can be seen at tradestatistics.io. This example
is interesting because “01” return a set of commodities (all commodities
starting with 01, which is the commodity group “Animals; live”), but
“food” return all commodities with a matching description (“1601”,
“1806”, “1904”, etc.). In addition, not all the requested commodities
are exported from each reporter to each partner, therefore a warning is
returned.
If we want Chile-Argentina bilateral trade at aggregated level in 2018 and 2019:
yrp <- ots_create_tidy_data(
years = 2018:2019,
reporters = c("chl", "per"),
partners = "arg",
table = "yrp"
)This table accepts different years, reporters and partners just like
yrpc.
If we want Chilean trade at commodity level in 2019 with respect to commodity “010121” which means “Horses; live, pure-bred breeding animals”:
yrc <- ots_create_tidy_data(
years = 2019,
reporters = "chl",
commodities = "010121",
table = "yrc"
)This table accepts different years, reporters and commodity codes
just like yrpc.
All the variables from this table are documented at tradestatistics.io.
If we want the aggregated trade of Chile, Argentina and Peru in 2018 and 2019:
This table accepts different years and reporters just like
yrpc.
All the variables from this table are documented at tradestatistics.io.
If we want all commodities traded in 2019:
If we want the traded values of the commodity “010121” which means “Horses; live, pure-bred breeding animals” in 2019:
This table accepts different years just like yrpc.