comtradr (version 0.0.2)

ct_search: Get UN Comtrade data via API

Description

Make queries to the UN Comtrade API, data is returned as a tidy dataframe. Comtrade is a DB hosted by the United Nations that houses country-level shipping data. Full API docs can be found here: https://comtrade.un.org/data/doc/api/

Usage

ct_search(reporters, partners, countrytable,
  url = "https://comtrade.un.org/api/get?", maxrec = 50000,
  type = c("goods", "services"), freq = c("annual", "monthly"),
  startdate = "all", enddate = "all", tradedirection = c("all", "imports",
  "exports", "re-imports", "re-exports"), commodcodes = "TOTAL",
  fmt = c("json", "csv"), colname = c("human", "machine"), token = NULL,
  codetype = c("HS", "H0", "H1", "H2", "H3", "H4", "ST", "S1", "S2", "S3",
  "S4", "BEC", "EB02"))

Arguments

reporters

Country(s) of interest, as a character vector. Can either be a vector of country names, or "All" to represent all countries.

partners

Country(s) that have interacted with the reporter country(s), as a character vector. Can either be a vector of country names, or "All" to represent all countries.

countrytable

Dataframe of country names and associated country codes that work within the Comtrade API calls. Includes both reporters & partners.

url

Base of the Comtrade url string, as a character string.

maxrec

Max number of records returned from each API call, as an integer. API cap without a token is 50000, cap with a valid token is 250000. Default value is 50000.

type

Type of trade, as a character string. Must be either "goods" or "services".

freq

Time frequency of the returned results, as a character string. Must be either "annual" or "monthly".

startdate

Start date of a time period, or "all". Default value is "all". If inputing a date, must be string w/ structure "yyyy-mm-dd".

enddate

End date of a time period, or "all". Default value is "all". If inputing a date, must be string w/ structure "yyyy-mm-dd".

tradedirection

Indication of which trade directions on which to focus, as a character vector. Must either be "all", or a vector containing any combination of the following: "imports", "exports", "re-imports", "re-exports".

commodcodes

Character vector of commodity codes, or "TOTAL". Valid commodity codes as input will restrict the query to only look for trade related to those commodities, "TOTAL" as input will return all trade between the indicated reporter country(s) and partner country(s). Default value is "TOTAL".

fmt

Indication as to the format of the returned data, as a character string. Must be either "json" or "csv". Regardless of the fmt used, the return data will be in the form of a tidy dataframe. "json" is the suggested value for this parameter, as the API tends to provide more detailed feedback on why a query failed when using json.

colname

Should the output dataframe have human-friendly or machine-friendly column names. Human-friendly means easy for a human to read and understand, and may contain special characters and spaces. Machine-friendly means easy for a machine to parse, and may not contain special characters or spaces. Must be either "human" or "machine". Default value is "human".

token

Authorization token, as a character string. Default value is NULL.

codetype

Trade data classification scheme to use, as a character string. See "Details" for a list of a valid inputs.

Value

List of length three, elements are:

• msg: Brief message on success/failure of the API call.

• details: More detailed message on success/failure of the API call.

• data: Dataframe object of return data.

Details

Basic rate limit restrictions. For full details see https://comtrade.un.org/data/doc/api/#Limits

• Without authentication token: 1 request per second, 100 requests per hour (each per IP address).

• With valid authentication token: 1 request per second, 10,000 requests per hour (each per IP address or authenticated user).

In addition to these rate limits, the API imposes some limits on parameter combinations, they are listed below:

• Between params "reporters", "partners", and the query date range (as dictated by the two params "startdate" and "enddate"), only one of these three may use the catch-all input "All".

• For the same group of three ("reporters", "partners", date range), if the input is not "All", then the maximum number of input values for each is five (for date range, if not using "all", then the "startdate" and "enddate" must at most span five months or five years).

• For param "commodcodes", if not using input "All", then the maximum number of input values is 20 (although "All" is always a valid input).

The default for param codetype is HS. Below is a list of all valid inputs with a very brief description for each. For more information on each of these types, see https://comtrade.un.org/data/doc/api/#DataAvailabilityRequests

• HS: Harmonized System (HS), as reported

• HS1992: HS 1992

• HS1996: HS 1996

• HS2002: HS 2002

• HS2007: HS 2007

• HS2012: HS 2012

• SITC: Standard International Trade Classification (SITC), as reported

• SITCrev1: SITC Revision 1

• SITCrev2: SITC Revision 2

• SITCrev3: SITC Revision 3

• SITCrev4: SITC Revision 4

• BEC: Broad Economic Categories

• EB02: Extended Balance of Payments Services Classification

Examples

# NOT RUN {
# Create the country lookup table
countrydf <- ct_countries_table()

## Example API call number 1:
# All exports from China to South Korea, United States and Mexico over all
# years.
comtrade <- ct_search(reporters = "China",
                      partners = c("Rep. of Korea", "USA", "Mexico"),
                      countrytable = countrydf,
                      tradedirection = "exports")
comtrade$msg
[1] "Data returned"
comtrade$details
[1] "Connection successful"
nrow(comtrade$data)
[1] 75

## Example API call number 2:
# All shipments related to halibut between Canada and all other countries,
# between 2011 and 2015.
# Create the commodities lookup table
commoditydf <- ct_commodities_table("HS")

# Perform "shrimp" query
shrimp_codes <- commodity_lookup("shrimp",
                                 commoditydf,
                                 return_code = TRUE,
                                 return_char = TRUE,
                                 verbose = TRUE)

# Make API call
shrimp_codes <- commodity_lookup("shrimp",
                                 commoditydf,
                                 return_code = TRUE,
                                 return_char = TRUE,
                                 verbose = TRUE)
comtrade <- ct_search(reporters = "Canada",
                      partners = "All",
                      countrytable = countrydf,
                      tradedirection = "all",
                      startdate = "2011-01-01",
                      enddate = "2015-01-01",
                      commodcodes = shrimp_codes)
comtrade$msg
[1] "Data returned"
comtrade$details
[1] "Connection successful"
nrow(comtrade$data)
[1] 1321
# }