Interface with the United Nations Comtrade API

Interface with and extract data from the United Nations Comtrade API < https://comtrade.un.org/data/>. 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.


Travis-CI Build Status AppVeyor Build Status codecov CRAN_Status_Badge

R package for interacting with the UN Comtrade Database public API. UN Comtrade provides historical data on the weights and value of specific goods shipped between countries, more info can be found here. Full API documentation can be found here.

This package was inspired by the R tutorial posted by Comtrade, and is built using httr and jsonlite.

I've also built a Shiny app for visualizing comtrade shipping data, that's powered by this package. The app can be viewed here.

Please report issues, comments, or feature requests.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

For information on citation of this package, use citation("comtradr")

Installation

Install from CRAN:

install.packages("comtradr")

Or install from this repo:

devtools::install_github("ChrisMuir/comtradr")

Example Usage

Example 1: Return all exports from China to South Korea, United States and Mexico, for all years

library(comtradr)
 
# Country names passed to the API query function must be spelled as they appear 
# in the Comtrade DB. Use "ct_country_lookup" to query the country DB and 
#return the exact spelling of specific countries.
ct_country_lookup("korea")
#> [1] "Dem. People's Rep. of Korea" "Rep. of Korea"
 
# Since we want South Korea, we'll use "Rep. of Korea" within the API query.
example1 <- ct_search(reporters = "China", 
                      partners = c("Rep. of Korea", "USA", "Mexico"), 
                      trade_direction = "exports")
 
# Inspect the return data
str(example1)
#> 'data.frame':    75 obs. of  35 variables:
#>  $ classification        : chr  "H4" "H4" "H4" "H4" ...
#>  $ year                  : int  2012 2012 2012 2013 2013 2013 2014 2014 2014 2015 ...
#>  $ period                : int  2012 2012 2012 2013 2013 2013 2014 2014 2014 2015 ...
#>  $ period_desc           : chr  "2012" "2012" "2012" "2013" ...
#>  $ aggregate_level       : int  0 0 0 0 0 0 0 0 0 0 ...
#>  $ is_leaf_code          : int  0 0 0 0 0 0 0 0 0 0 ...
#>  $ trade_flow_code       : int  2 2 2 2 2 2 2 2 2 2 ...
#>  $ trade_flow            : chr  "Export" "Export" "Export" "Export" ...
#>  $ reporter_code         : int  156 156 156 156 156 156 156 156 156 156 ...
#>  $ reporter              : chr  "China" "China" "China" "China" ...
#>  $ reporter_iso          : chr  "CHN" "CHN" "CHN" "CHN" ...
#>  $ partner_code          : int  410 484 842 410 484 842 410 484 842 410 ...
#>  $ partner               : chr  "Rep. of Korea" "Mexico" "USA" "Rep. of Korea" ...
#>  $ partner_iso           : chr  "KOR" "MEX" "USA" "KOR" ...
#>  $ second_partner_code   : logi  NA NA NA NA NA NA ...
#>  $ second_partner        : chr  NA NA NA NA ...
#>  $ second_partner_iso    : chr  NA NA NA NA ...
#>  $ customs_proc_code     : chr  NA NA NA NA ...
#>  $ customs               : chr  NA NA NA NA ...
#>  $ mode_of_transport_code: chr  NA NA NA NA ...
#>  $ mode_of_transport     : chr  NA NA NA NA ...
#>  $ commodity_code        : chr  "TOTAL" "TOTAL" "TOTAL" "TOTAL" ...
#>  $ commodity             : chr  "All Commodities" "All Commodities" "All Commodities" "All Commodities" ...
#>  $ qty_unit_code         : int  1 1 1 1 1 1 1 1 1 1 ...
#>  $ qty_unit              : chr  "No Quantity" "No Quantity" "No Quantity" "No Quantity" ...
#>  $ alt_qty_unit_code     : logi  NA NA NA NA NA NA ...
#>  $ alt_qty_unit          : chr  NA NA NA NA ...
#>  $ qty                   : logi  NA NA NA NA NA NA ...
#>  $ alt_qty               : logi  NA NA NA NA NA NA ...
#>  $ netweight_kg          : logi  NA NA NA NA NA NA ...
#>  $ gross_weight_kg       : logi  NA NA NA NA NA NA ...
#>  $ trade_value_usd       : num  8.77e+10 2.75e+10 3.52e+11 9.12e+10 2.90e+10 ...
#>  $ cif_trade_value_usd   : logi  NA NA NA NA NA NA ...
#>  $ fob_trade_value_usd   : logi  NA NA NA NA NA NA ...
#>  $ flag                  : int  0 0 0 0 0 0 0 0 0 0 ...
#>  - attr(*, "url")= chr "https://comtrade.un.org/api/get?max=50000&type=C&freq=A&px=HS&ps=all&r=156&p=410,842,484&rg=2&cc=TOTAL&fmt=json&head=H"
#>  - attr(*, "time_stamp")= POSIXct, format: "2017-10-23 18:50:31"
#>  - attr(*, "req_duration")= num 0.856

Example 2: Return all exports related to shrimp from Thailand to all other countries, for years 2007 thru 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.
shrimp_codes <- ct_commodity_lookup("shrimp", return_code = TRUE, return_char = TRUE)
 
# API query.
example2 <- ct_search(reporters = "Thailand", 
                      partners = "All", 
                      trade_direction = "exports", 
                      start_date = "2007-01-01", 
                      end_date = "2011-01-01", 
                      commod_codes = shrimp_codes)
 
# Inspect the output
str(example2)
#> 'data.frame':    1203 obs. of  35 variables:
#>  $ classification        : chr  "H3" "H3" "H3" "H3" ...
#>  $ year                  : int  2007 2007 2007 2007 2007 2007 2007 2007 2007 2007 ...
#>  $ period                : int  2007 2007 2007 2007 2007 2007 2007 2007 2007 2007 ...
#>  $ period_desc           : chr  "2007" "2007" "2007" "2007" ...
#>  $ aggregate_level       : int  6 6 6 6 6 6 6 6 6 6 ...
#>  $ is_leaf_code          : int  1 1 1 1 1 1 1 1 1 1 ...
#>  $ trade_flow_code       : int  2 2 2 2 2 2 2 2 2 2 ...
#>  $ trade_flow            : chr  "Export" "Export" "Export" "Export" ...
#>  $ reporter_code         : int  764 764 764 764 764 764 764 764 764 764 ...
#>  $ reporter              : chr  "Thailand" "Thailand" "Thailand" "Thailand" ...
#>  $ reporter_iso          : chr  "THA" "THA" "THA" "THA" ...
#>  $ partner_code          : int  0 36 40 48 56 104 116 124 152 156 ...
#>  $ partner               : chr  "World" "Australia" "Austria" "Bahrain" ...
#>  $ partner_iso           : chr  "WLD" "AUS" "AUT" "BHR" ...
#>  $ second_partner_code   : logi  NA NA NA NA NA NA ...
#>  $ second_partner        : chr  NA NA NA NA ...
#>  $ second_partner_iso    : chr  NA NA NA NA ...
#>  $ customs_proc_code     : chr  NA NA NA NA ...
#>  $ customs               : chr  NA NA NA NA ...
#>  $ mode_of_transport_code: chr  NA NA NA NA ...
#>  $ mode_of_transport     : chr  NA NA NA NA ...
#>  $ commodity_code        : chr  "030613" "030613" "030613" "030613" ...
#>  $ commodity             : chr  "Shrimps & prawns, whether/not in shell, frozen" "Shrimps & prawns, whether/not in shell, frozen" "Shrimps & prawns, whether/not in shell, frozen" "Shrimps & prawns, whether/not in shell, frozen" ...
#>  $ qty_unit_code         : int  8 8 8 8 8 8 8 8 8 8 ...
#>  $ qty_unit              : chr  "Weight in kilograms" "Weight in kilograms" "Weight in kilograms" "Weight in kilograms" ...
#>  $ alt_qty_unit_code     : logi  NA NA NA NA NA NA ...
#>  $ alt_qty_unit          : chr  NA NA NA NA ...
#>  $ qty                   : int  169654441 5545602 1265 29780 2721318 750 8510 13088545 4930 3410678 ...
#>  $ alt_qty               : logi  NA NA NA NA NA NA ...
#>  $ netweight_kg          : int  169654441 5545602 1265 29780 2721318 750 8510 13088545 4930 3410678 ...
#>  $ gross_weight_kg       : logi  NA NA NA NA NA NA ...
#>  $ trade_value_usd       : int  1084677273 36120291 11888 124668 16061545 4521 74842 77292118 64218 18400152 ...
#>  $ cif_trade_value_usd   : logi  NA NA NA NA NA NA ...
#>  $ fob_trade_value_usd   : logi  NA NA NA NA NA NA ...
#>  $ flag                  : int  0 0 0 0 0 0 0 0 0 0 ...
#>  - attr(*, "url")= chr "https://comtrade.un.org/api/get?max=50000&type=C&freq=A&px=HS&ps=2007,2008,2009,2010,2011&r=764&p=all&rg=2&cc=0"| __truncated__
#>  - attr(*, "time_stamp")= POSIXct, format: "2017-10-23 18:50:34"
#>  - attr(*, "req_duration")= num 3.3

ropensci_footer

News

comtradr 0.1.0

PKG API CHANGES

  • Eliminated functions ct_commodities_table and ct_countries_table.
  • Added new functions ct_update_databases, ct_use_pretty_cols, ct_commodity_db_type, ct_register_token, ct_get_reset_time, ct_get_remaining_hourly_queries.
  • Renamed functions: commodity_lookup is now ct_commodity_lookup, country_lookup is now ct_country_lookup.
  • The commodity and country reference tables are now saved as cached package data, and accessed by comtradr functions when necessary. This replaces the need for functions ct_commodities_table and ct_countries_table.
  • Reorder function arguments within function ct_search.
  • Changed some function argument names to ensure snake_case is being used throughout the package.
  • ct_search now returns a data frame, as opposed to a list.

MINOR CHANGES

  • Added a vignette directory, with an "Intro to comtradr" vignette.
  • API requests are now throttled based on the rate limits imposed by the UN Comtrade.
  • Added function for setting a valid API key/token (ct_register_token).
  • Appending API metadata to each returned data frame as attributes (url of the API call, date-time of the query, duration of the query in seconds).
  • Added package level man page.
  • Now using native R errors/warnings, as opposed to nesting API status codes in a returned list.
  • Imports changes: remove dplyr, add magrittr and purrr.
  • Expand and improve test coverage via testthat.

BUG FIXES

  • The issues related to type-safety in function commodity_lookup have been fixed by importing purrr and using purrr::map in place of sapply. This fixes issue #2 and issue #3.

comtradr 0.0.2 (2017-07-03)

NEW FEATURES

  • commodity_lookup(): Expanded function to accept multiple commodities or commodity codes (as either character vector or numeric vector). Also added argument "return_char" that allows the user to specify list output or char vector output, and argument "return_code" that specifies output of commodity descriptions or commodity codes.

MINOR IMPROVEMENTS

comtradr 0.0.1 (2017-04-06)

NEW FEATURES

  • released to CRAN

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("comtradr")

0.2.1 by Chris Muir, 2 months ago


https://github.com/ropensci/comtradr


Report a bug at https://github.com/ropensci/comtradr/issues


Browse source code at https://github.com/cran/comtradr


Authors: Chris Muir [aut, cre], Alicia Schep [rev] (<https://orcid.org/0000-0002-3915-0618>, Alicia reviewed the package for rOpenSci, see https://github.com/ropensci/onboarding/issues/141), Rafael Hellwig [rev] (<https://orcid.org/0000-0002-3092-3493>, Rafael reviewed the package for rOpenSci, see https://github.com/ropensci/onboarding/issues/141)


Documentation:   PDF Manual  


GPL-3 license


Imports httr, jsonlite, magrittr, methods, purrr

Suggests testthat, knitr, rmarkdown, ggplot2, dplyr


Imported by ITNr.


See at CRAN