Make queries to the UN Comtrade API, data is returned as a tidy data frame. 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/
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.
- trade_direction
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". Default value is "all".
- freq
Time frequency of the returned results, as a character string. Must be either "annual" or "monthly". Default value is "annual".
- start_date
Start date of a time period, or "all". Default value is "all". See "details" for more info on valid input formats when not using "all" as input.
- end_date
End date of a time period, or "all". Default value is "all". See "details" for more info on valid input formats when not using "all" as input.
- commod_codes
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".
- max_rec
Max number of records returned from each API call, as an integer. Default value is 100000.
- type
Type of trade, as a character string. Must be either "goods" or "services". Default value is "goods".
- url
Base of the Comtrade url string, as a character string. Default value is "https://comtrade.un.org/api/get?" and should mot be changed unless Comtrade changes their endpoint url.
Details
Basic rate limit restrictions listed below. For details on how to
register a valid token, see ct_register_token. For API docs
on rate limits, 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 "start_date" and "end_date"), 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 "start_date" and "end_date" must not span more than five months or five years. There is one exception to this rule, if arg "freq" is "monthly", then a single year can be passed to "start_date" and "end_date" and the API will return all of the monthly data for that year.
For param "commod_codes", if not using input "All", then the maximum number of input values is 20 (although "All" is always a valid input).
This function returns objects with metadata related to the API call that
can be accessed via attributes. The metadata accessible is:
url: url of the API call.
time_stamp: date-time of the API call.
req_duration: total duration of the API call, in seconds.
For args start_date and end_date, if inputting a date (as
opposed to the catch-all input "all"), valid input format is dependent on
the input passed to arg freq. If freq is "annual",
start_date and end_date must be either a string w/ format
"yyyy" or "yyyy-mm-dd", or a year as an integer (so "2016", "2016-01-01",
and 2016 would all be valid). If freq is "monhtly",
start_date and end_date must be a string with format
"yyyy-mm" or "yyyy-mm-dd" (so "2016-02" and "2016-02-01" would both be
valid).
Examples
if (FALSE) {
## Example API call number 1:
# All exports from China to South Korea, United States and Mexico over all
# years.
ex_1 <- ct_search(reporters = "China",
partners = c("Rep. of Korea", "USA", "Mexico"),
trade_direction = "exports")
nrow(ex_1)
## Example API call number 2:
# All shipments related to shrimp between Canada and all other countries,
# between 2011 and 2015.
# Perform "shrimp" query
shrimp_codes <- ct_commodity_lookup("shrimp",
return_code = TRUE,
return_char = TRUE)
# Make API call
ex_2 <- ct_search(reporters = "Canada",
partners = "All",
trade_direction = "all",
start_date = 2011,
end_date = 2015,
commod_codes = shrimp_codes)
nrow(ex_2)
# Access metadata
attributes(ex_2)$url
attributes(ex_2)$time_stamp
attributes(ex_2)$req_duration
}