[API] comtradr

API & Databases R Courses

Access detailed global trade data through the Comtrad API.

Thierry Warin https://warin.ca/aboutme.html (HEC Montréal and CIRANO (Canada))https://www.hec.ca/en/profs/thierry.warin.html
06-01-2020

Database description

UN Comtrade Database gives free access to detailed global trade data. UN Comtrade is a repository of official international trade statistics and relevant analytical tables. The UN Comtrade Database features inter-country trade data dating back to the early 1990’s.

UN Comtrade : https://comtrade.un.org/

Functions

This package gives access to all indicators provided by the UN Comtrade database. The functions listed below allow you to search and download specific data from the UN Comtrade database.

Each of these functions are detailed in this course and some examples are provided.

The function ct_search() takes as an input any string of character and will provide the list of all trades for the choosen parameters.

Lets say we want to get data on all imports into the United States from Germany, France, Japan, and Mexico, for all years.

#Loading the Comtrad package
library(comtradr)

# Search data on all imports into the United States from Germany, France, Japan, and Mexico, for all years:
q <- ct_search(reporters = "USA", 
               partners = c("Germany", "France", "Japan", "Mexico"), 
               trade_direction = "imports")

# Display the result
str(q)

Here are a few more examples to show the different parameter options:

For example, if we want to get data on all imports into the United States from Germany, France, Japan, and Mexico, between 2010 and 2014:

# Search all the imports to USA from Germany, France, Japan, and Mexico, between 2010 and 2014:
q <- ct_search(reporters = "USA", 
               partners = c("Germany", "France", "Japan", "Mexico"), 
               trade_direction = "imports", 
               start_date = 2010, 
               end_date = 2014)

By default, the return data is in yearly amounts. We can pass “monthly” to arg freq to return data in monthly amounts, however the API limits each “monthly” query to a single year.

# Get all monthly data for a single year (API max of 12 months per call).
q <- ct_search(reporters = "USA", 
               partners = c("Germany", "France", "Japan", "Mexico"), 
               trade_direction = "imports", 
               start_date = 2012, 
               end_date = 2012, 
               freq = "monthly")

# Get monthly data for a specific span of months (API max of five months per call).
q <- ct_search(reporters = "USA", 
               partners = c("Germany", "France", "Japan", "Mexico"), 
               trade_direction = "imports", 
               start_date = "2012-03", 
               end_date = "2012-07", 
               freq = "monthly")

ct_country_lookup()

Countries passed to parameters reporters and partners must be spelled as they appear in the Comtrade country reference table. Function ct_country_lookup allows us to query the country reference table.

# Search the names that have to be use for Korea and Bolivia:
ct_country_lookup("korea", "reporter")
#> [1] "Dem. People's Rep. of Korea" "Rep. of Korea"
ct_country_lookup("bolivia", "partner")
#> [1] "Bolivia (Plurinational State of)"

# Then using them for a ct_search
q <- ct_search(reporters = "Rep. of Korea", 
               partners = "Bolivia (Plurinational State of)", 
               trade_direction = "all")

The function ct_country_lookup is able to take multiple search terms as input.

# Search multiple terms as input
ct_country_lookup(c("Belgium", "vietnam", "brazil"), "reporter")

ct_commodity_lookup()

Search trade related to specific commodities (for example: tomatoes). We can query the Comtrade commodity reference table to see all of the different commodity descriptions available for tomatoes.

# Gives all the codes related to "tomato"
ct_commodity_lookup("tomato")

If we want to search for shipment data on all of the commodity descriptions listed, then we can simply adjust the parameters for ct_commodity_lookup so that it will return only the codes, which can then be passed along to ct_search.

# Search for a specific commodity (tomatoes)
tomato_codes <- ct_commodity_lookup("tomato", 
                                    return_code = TRUE, 
                                    return_char = TRUE)

q <- ct_search(reporters = "USA", 
               partners = c("Germany", "France", "Mexico"), 
               trade_direction = "all", 
               commod_codes = tomato_codes)

# Display the results
str(q)

On the other hand, if we wanted to exclude juices and sauces from our search, we can pass a vector of the relevant codes to the API call.

# Search for specific commodities (each code is a comodity)
q <- ct_search(reporters = "USA", 
               partners = c("Germany", "France", "Mexico"), 
               trade_direction = "all", 
               commod_codes = c("0702", "070200", "2002", "200210", "200290"))

# Display the results
str(q)

The function ct_commodity_lookup is able to take multiple search terms as input.

# Search multiple terms as input
ct_commodity_lookup(c("tomato", "trout"), return_char = TRUE)

ct_commodity_lookup can return a vector (as seen above) or a named list, using parameter return_char

# Search multiple terms as input
ct_commodity_lookup(c("tomato", "trout"), return_char = FALSE)

For ct_commodity_lookup, if any of the input search terms return zero results and parameter verbose is set to TRUE, a warning will be printed to console (set verbose to FALSE to turn off this feature).

# Search multiple terms as input
ct_commodity_lookup(c("tomato", "sldfkjkfdsklsd"), verbose = TRUE)

tl;dr

#Loading the Comtrad package
library(comtradr)

# Search data on all imports into the United States from Germany, France, Japan, and Mexico, for all years:
q <- ct_search(reporters = "USA", 
               partners = c("Germany", "France", "Japan", "Mexico"), 
               trade_direction = "imports")

# Display the result
str(q)

# Search all the imports to USA from Germany, France, Japan, and Mexico, between 2010 and 2014:
q <- ct_search(reporters = "USA", 
               partners = c("Germany", "France", "Japan", "Mexico"), 
               trade_direction = "imports", 
               start_date = 2010, 
               end_date = 2014)

# Get all monthly data for a single year (API max of 12 months per call).
q <- ct_search(reporters = "USA", 
               partners = c("Germany", "France", "Japan", "Mexico"), 
               trade_direction = "imports", 
               start_date = 2012, 
               end_date = 2012, 
               freq = "monthly")

# Get monthly data for a specific span of months (API max of five months per call).
q <- ct_search(reporters = "USA", 
               partners = c("Germany", "France", "Japan", "Mexico"), 
               trade_direction = "imports", 
               start_date = "2012-03", 
               end_date = "2012-07", 
               freq = "monthly")

# Search the names that have to be use for Korea and Bolivia:
ct_country_lookup("korea", "reporter")

ct_country_lookup("bolivia", "partner")

# Then using them for a ct_search
q <- ct_search(reporters = "Rep. of Korea", 
               partners = "Bolivia (Plurinational State of)", 
               trade_direction = "all")

# Search multiple terms as input
ct_country_lookup(c("Belgium", "vietnam", "brazil"), "reporter")

# Gives all the codes related to "tomato"
ct_commodity_lookup("tomato")

# Search for a specific commodity (tomatoes)
tomato_codes <- ct_commodity_lookup("tomato", 
                                    return_code = TRUE, 
                                    return_char = TRUE)

q <- ct_search(reporters = "USA", 
               partners = c("Germany", "France", "Mexico"), 
               trade_direction = "all", 
               commod_codes = tomato_codes)

# Display the results
str(q)

# Search for specific commodities (each code is a comodity)
q <- ct_search(reporters = "USA", 
               partners = c("Germany", "France", "Mexico"), 
               trade_direction = "all", 
               commod_codes = c("0702", "070200", "2002", "200210", "200290"))

# Display the results
str(q)

# Search multiple terms as input
ct_commodity_lookup(c("tomato", "trout"), return_char = TRUE)

# Search multiple terms as input
ct_commodity_lookup(c("tomato", "trout"), return_char = FALSE)

# Search multiple terms as input
ct_commodity_lookup(c("tomato", "sldfkjkfdsklsd"), verbose = TRUE)

Code learned this week

Command Detail
ct_search() Search for UN Comtrade trades
ct_country_lookup() Find data related for each country
ct_comodity_lookup() Find data related for each comodity

References

This course uses the UN Comtrad package documentation


Citation

For attribution, please cite this work as

Warin (2020, June 1). Thierry Warin, PhD: [API] comtradr. Retrieved from https://warin.ca/posts/api-comtradr/

BibTeX citation

@misc{warin2020[api],
  author = {Warin, Thierry},
  title = {Thierry Warin, PhD: [API] comtradr},
  url = {https://warin.ca/posts/api-comtradr/},
  year = {2020}
}