Interface with and extract data from the United Nations Comtrade API https://comtradeplus.un.org/. Comtrade provides country level shipping data for a variety of commodities, these functions allow for easy API query and data returned as a tidy data frame. More info can be found here. Full API documentation can be found here.
Please report issues, comments, or feature requests. We are very much looking for feedback on the usability of the new functions.
Please note that this package is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.
For information on citation of this package, use
citation("comtradr")
You can install the package with:
install.packages("comtradr")
To install the dev version from github, use:
# install.packages("devtools")
::install_github("ropensci/comtradr@dev") devtools
Do not be discouraged by the complicated access to the token - you can do it! đĒ
As stated above, you need an API token, see the FAQ of Comtrade for details on how to obtain it:
âĄī¸ https://uncomtrade.org/docs/api-subscription-keys/
You need to follow the detailed explanations, which include
screenshots, in the Wiki of Comtrade to the letter. âī¸ I am not writing
them out here, because they might be updated regularly. However, once
you are signed up, select the comtrade - v1
product, which
is the free API.
If you are in an interactive session, you can call the following function to save your API token to the environment file for the current session.
library(comtradr)
set_primary_comtrade_key()
If you are not in an interactive session, you can register the token once in your session using the following base-r function.
Sys.setenv('COMTRADE_PRIMARY' = 'xxxxxxxxxxxxxxxxx')
If you would like to set the comtrade key permanently, we recommend
editing the project .Renviron
file, where you need to add a
line with COMTRADE_PRIMARY = xxxx-your-key-xxxx
.
âšī¸ Do not forget the line break after the last entry. This is the
easiest by taking advantage of the great usethis
package.
::edit_r_environ(scope = 'project') usethis
Now we can get to actually request some data. Let us query the total trade between China and Germany and Argentina, as reported by China.
# Country names passed to the API query function must be spelled in ISO3 format.
# For details see: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
# You can request a maximum interval of twelve years from the API
<- comtradr::ct_get_data(
example1 reporter = 'CHN',
partner = c('ARG', 'DEU'),
start_date = 2010,
end_date = 2012
)
# Inspect the return data
str(example1)
Return all exports related to Wine from Argentina to all other countries, for years 2007 through 2011.
library(comtradr)
# Fetch all shrimp related commodity codes from the Comtrade commodities DB.
# This vector of codes will get passed to the API query.
<- ct_commodity_lookup("wine", return_code = TRUE, return_char = TRUE)
wine_codes
# API query.
<- ct_get_data(
example2 reporter = "ARG",
flow_direction = "export",
partner = "all_countries",
start_date = 2007,
end_date = 2011,
commodity_code = wine_codes
)
# Inspect the output
str(example2)
To download bulk files, use the function ct_get_bulk
.
Usage is documented in the package vignettes, see here
for an example.
Attention, this downloads large files (often more than one Gigabyte in size) and requires a premium key.
<- comtradr::ct_get_bulk(
hs0_all reporter = c("DEU"), # only some examples here,
commodity_classification = 'H0',
frequency = 'A',
verbose = T,
start_date = 2020, # only one year here
end_date = 2020)
See here for an overview of available commodity classifications.
The Comtrade API has been undergoing extensive updates. At this point the legacy API has been taken offline (see here).
In order to accommodate the new syntax, as well as adding the new
functionality, the comtradr
package has been undergoing an
extensive re-write. Additionally, it is not possible anymore to query
the API without an API token. There still is a free version, but unlike
before you need to be a registered user to obtain the token. See the FAQ
for details on how to obtain the new access tokens.