Last chance! 50% off unlimited learning
Sale ends in
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/
ct_search(reporters, partners, trade_direction = c("all", "imports",
"exports", "re_imports", "re_exports"), freq = c("annual", "monthly"),
start_date = "all", end_date = "all", commod_codes = "TOTAL",
max_rec = NULL, type = c("goods", "services"),
url = "https://comtrade.un.org/api/get?")Country(s) of interest, as a character vector. Can either be a vector of country names, or "All" to represent all countries.
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.
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".
Time frequency of the returned results, as a character string. Must be either "annual" or "monthly". Default value is "annual".
Start date of a time period, or "all". Default value is "all". If inputing a date, must be string w/ structure "yyyy-mm-dd".
End date of a time period, or "all". Default value is "all". If inputing a date, must be string w/ structure "yyyy-mm-dd".
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 number of records returned from each API call, as an
integer. If max_rec is set to NULL, then value is determined by whether or
not an API token has been registered. API cap without a token is 50000,
cap with a valid token is 250000. Default value is NULL. For details on
how to register a valid token, see ct_register_token.
Type of trade, as a character string. Must be either "goods" or "services". Default value is "goods".
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.
Data frame of Comtrade shipping data.
Basic rate limit restrictions. 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 at most span five months or five years).
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.
# NOT RUN {
## 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-01-01",
end_date = "2015-01-01",
commod_codes = shrimp_codes)
nrow(ex_2)
# Access metadata
attributes(ex_2)$url
attributes(ex_2)$time_stamp
attributes(ex_2)$req_duration
# }
Run the code above in your browser using DataLab