Title: | Interface with the United Nations Comtrade API |
---|---|
Description: | 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. |
Authors: | Paul Bochtler [aut, cre, cph] |
Maintainer: | Paul Bochtler <[email protected]> |
License: | GPL-3 |
Version: | 1.0.1 |
Built: | 2024-08-29 23:10:30 UTC |
Source: | https://github.com/ropensci/comtradr |
A full dataset of all reporter and partner codes available in the UN Comtrade database.
country_codes
country_codes
country_codes
A dataframe with 312 rows and eight columns:
Unique country code.
Name of the country (in English).
The country's ISO 3 code.
The country's entry into the international system or 1900 (whichever is largest).
The country's exit from the international system, if applicable.
Indicates whether the entity is a group of countries. For example, ASEAN or the European Union.
Indicates whether the country is a reporter in the UN Comtrade database.
Indicates whether the country can be reported on by others in the UN Comtrade database. Not all partners are reporters. For example, the World cannot report its trade values.
https://comtradeapi.un.org/files/v1/app/reference/Reporters.json and https://comtradeapi.un.org/files/v1/app/reference/partnerAreas.json
This function is deprecated. There is currently
no alternative for this function.
ct_commodity_db_type(...)
ct_commodity_db_type(...)
... |
Used to catch all possible arguments that users have supplied to this function. |
depreciation error
# no examples because only legacy function
# no examples because only legacy function
The Comtrade API requires that searches for specific commodities be done using commodity codes. This is a helper function for querying the Comtrade commodity database. It takes as input a vector of commodities or commodity codes. Output is a list or vector of commodity descriptions or codes associated with the input search_terms. For use with the UN Comtrade API, full API docs can be found at https://unstats.un.org/wiki/display/comtrade/
ct_commodity_lookup( search_terms, return_code = FALSE, commodity_classification = "HS", type = "goods", return_char = FALSE, verbose = TRUE, ignore.case = TRUE, update = FALSE, ... )
ct_commodity_lookup( search_terms, return_code = FALSE, commodity_classification = "HS", type = "goods", return_char = FALSE, verbose = TRUE, ignore.case = TRUE, update = FALSE, ... )
search_terms |
Commodity names or commodity codes, as a char or numeric vector. |
return_code |
Logical, if set to FALSE, the function will return a set of commodity descriptions along with commodity codes (as a single string for each match found), if set to TRUE it will return only the commodity codes. Default value is FALSE. |
commodity_classification |
The trade classification scheme.
Possible values for goods: |
type |
The type of returned trade data. Possible values: 'goods' for trade in goods, 'services' for trade in services. Default: 'goods'. |
return_char |
Logical, if set to FALSE, the function will return the matches as a named list, if set to TRUE it will return them as a character vector. Default value is FALSE. |
verbose |
Logical, if set to TRUE, a warning message will print to console if any of the elements of input "search_terms" returned no matches (message will indicate which elements returned no data). Default is TRUE. |
ignore.case |
logical, to be passed along to arg ignore.case within
|
update |
If TRUE, downloads possibly updated reference tables from the UN. Default: FALSE. |
... |
additional args to be passed along to |
This function uses regular expressions (regex) to find matches within the commodity DB. This means it will treat as a match any commodity description that contains the input search term. For more on using regex within R, see https://stat.ethz.ch/R-manual/R-devel/library/base/html/regex.html
A list or character vector of commodity descriptions and/or commodity codes that are matches with the elements of "search_terms".
comtradr::ct_commodity_lookup("wine")
comtradr::ct_commodity_lookup("wine")
This function is deprecated. You can use country_codes
to return a dataset with all possible country codes, but in general the
specification of iso 3 codes makes a look-up unnecessary.
ct_country_lookup(...)
ct_country_lookup(...)
... |
Used to catch all possible arguments that users have supplied to this function. |
depreciation error
# no examples because only legacy function
# no examples because only legacy function
This function queries the UN Comtrade API to retrieve
international trade data.
It allows for detailed specification of the query,
including the type of data (goods or services),
frequency (annual or monthly), commodity classification,
flow direction, and more.
By providing everything
for certain parameters,
you can query all possible values.
The function is opinionated in that it already verifies certain parameters
for you and is more than a pure wrapper around the API.
ct_get_bulk( type = "goods", frequency = "A", commodity_classification = "HS", reporter = "all_countries", start_date = NULL, end_date = NULL, tidy_cols = TRUE, verbose = FALSE, primary_token = get_primary_comtrade_key(), update = FALSE, requests_per_second = 10/60, cache = FALSE, download_bulk_files = TRUE )
ct_get_bulk( type = "goods", frequency = "A", commodity_classification = "HS", reporter = "all_countries", start_date = NULL, end_date = NULL, tidy_cols = TRUE, verbose = FALSE, primary_token = get_primary_comtrade_key(), update = FALSE, requests_per_second = 10/60, cache = FALSE, download_bulk_files = TRUE )
type |
The type of returned trade data. Possible values: 'goods' for trade in goods, 'services' for trade in services. Default: 'goods'. |
frequency |
The frequency of returned trade data. Possible values: 'A' for annual data, 'M' for monthly data. Default: 'A'. |
commodity_classification |
The trade classification scheme.
Possible values for goods:
|
reporter |
Reporter ISO3 code(s), |
start_date |
The start date of the query.
Format: |
end_date |
The end date of the query.
Format: |
tidy_cols |
If TRUE, returns tidy column names. If FALSE, returns raw column names. Default: TRUE. |
verbose |
If TRUE, sends status updates to the console. If FALSE, runs functions quietly. Default: FALSE. |
primary_token |
Your primary UN Comtrade API token.
Default: stored token from |
update |
If TRUE, downloads possibly updated reference tables from the UN. Default: FALSE. |
requests_per_second |
Rate of requests per second executed,
usually specified as a fraction, e.g. 10/60 for 10 requests per minute,
see |
cache |
A logical value to determine, whether requests should be cached
or not. If set to True, |
download_bulk_files |
If TRUE downloads all files that are returned from the Comtrade API as a list for the specified parameters. This can result in large writing and reading operations from your file system. |
The UN Comtrade database provides a repository of official international trade statistics and relevant analytical tables. It contains annual trade statistics starting from 1988 and monthly trade statistics since 2000 for goods data
Parameters that accept everything
will query all possible values.
For example, setting commodity_code = 'everything'
will retrieve data for all commodity codes.
This can be useful for broad queries but may result in large datasets.
A data.frame with trade data or,
if process = FALSE
, a httr2 response object.
This function queries the UN Comtrade API to retrieve
international trade data.
It allows for detailed specification of the query,
including the type of data (goods or services),
frequency (annual or monthly), commodity classification,
flow direction, and more.
By providing everything
for certain parameters,
you can query all possible values.
The function is opinionated in that it already verifies certain parameters
for you and is more than a pure wrapper around the API.
ct_get_data( type = "goods", frequency = "A", commodity_classification = "HS", commodity_code = "TOTAL", flow_direction = c("Import", "Export", "Re-export", "Re-import"), reporter = "all_countries", partner = "World", start_date = NULL, end_date = NULL, process = TRUE, tidy_cols = TRUE, verbose = FALSE, primary_token = get_primary_comtrade_key(), mode_of_transport = "TOTAL modes of transport", partner_2 = "World", customs_code = "C00", update = FALSE, requests_per_second = 10/60, extra_params = NULL, cache = FALSE )
ct_get_data( type = "goods", frequency = "A", commodity_classification = "HS", commodity_code = "TOTAL", flow_direction = c("Import", "Export", "Re-export", "Re-import"), reporter = "all_countries", partner = "World", start_date = NULL, end_date = NULL, process = TRUE, tidy_cols = TRUE, verbose = FALSE, primary_token = get_primary_comtrade_key(), mode_of_transport = "TOTAL modes of transport", partner_2 = "World", customs_code = "C00", update = FALSE, requests_per_second = 10/60, extra_params = NULL, cache = FALSE )
type |
The type of returned trade data. Possible values: 'goods' for trade in goods, 'services' for trade in services. Default: 'goods'. |
frequency |
The frequency of returned trade data. Possible values: 'A' for annual data, 'M' for monthly data. Default: 'A'. |
commodity_classification |
The trade classification scheme.
Possible values for goods: |
commodity_code |
The commodity code(s) or |
flow_direction |
The direction of trade flows or |
reporter |
Reporter ISO3 code(s), |
partner |
Partner ISO3 code(s), |
start_date |
The start date of the query.
Format: |
end_date |
The end date of the query.
Format: |
process |
If TRUE, returns a data.frame with results. If FALSE, returns the raw httr2 request. Default: TRUE. |
tidy_cols |
If TRUE, returns tidy column names. If FALSE, returns raw column names. Default: TRUE. |
verbose |
If TRUE, sends status updates to the console. If FALSE, runs functions quietly. Default: FALSE. |
primary_token |
Your primary UN Comtrade API token.
Default: stored token from |
mode_of_transport |
Text code of mode of transport or |
partner_2 |
Partner 2 ISO3 code(s), |
customs_code |
Customs Code ID or |
update |
If TRUE, downloads possibly updated reference tables from the UN. Default: FALSE. |
requests_per_second |
Rate of requests per second executed,
usually specified as a fraction, e.g. 10/60 for 10 requests per minute,
see |
extra_params |
Additional parameters to the API, passed as query parameters without checking. Please provide a named list to this parameter. Default: NULL. |
cache |
A logical value to determine, whether requests should be cached
or not. If set to True, |
The UN Comtrade database provides a repository of official international trade statistics and relevant analytical tables. It contains annual trade statistics starting from 1988 and monthly trade statistics since 2000 for goods data
Parameters that accept everything
will query all possible values.
For example, setting commodity_code = 'everything'
will retrieve data for all commodity codes.
This can be useful for broad queries but may result in large datasets.
A data.frame with trade data or,
if process = F
, a httr2 response object.
# Query goods data for China's trade with Argentina and Germany in 2019 ct_get_data( type = "goods", commodity_classification = "HS", commodity_code = "TOTAL", reporter = "CHN", partner = c("ARG", "DEU"), start_date = "2019", end_date = "2019", flow_direction = "Import", partner_2 = "World", verbose = TRUE ) # Query all commodity codes for China's imports from Germany in 2019 ct_get_data( commodity_code = "everything", reporter = "CHN", partner = "DEU", start_date = "2019", end_date = "2019", flow_direction = "Import" ) # Query all commodity codes for China's imports from Germany # from January to June of 2019 ct_get_data( commodity_code = "everything", reporter = "CHN", partner = "DEU", start_date = "2019", end_date = "2019", flow_direction = "import" )
# Query goods data for China's trade with Argentina and Germany in 2019 ct_get_data( type = "goods", commodity_classification = "HS", commodity_code = "TOTAL", reporter = "CHN", partner = c("ARG", "DEU"), start_date = "2019", end_date = "2019", flow_direction = "Import", partner_2 = "World", verbose = TRUE ) # Query all commodity codes for China's imports from Germany in 2019 ct_get_data( commodity_code = "everything", reporter = "CHN", partner = "DEU", start_date = "2019", end_date = "2019", flow_direction = "Import" ) # Query all commodity codes for China's imports from Germany # from January to June of 2019 ct_get_data( commodity_code = "everything", reporter = "CHN", partner = "DEU", start_date = "2019", end_date = "2019", flow_direction = "import" )
The first time, the function will read from disk, the second time from the
environment. In the case of a necessary update the new data will be saved
to the environment for the current session.
You can use this table to look at the reference tables and if necessary
extract respective classification codes by hand. In general we would
recommend the function ct_commodity_lookup
for this purpose.
It uses the present function in the backend.
ct_get_ref_table(dataset_id, update = FALSE, verbose = FALSE)
ct_get_ref_table(dataset_id, update = FALSE, verbose = FALSE)
dataset_id |
The dataset ID, which is either partner, reporter or a valid classification scheme. |
update |
If TRUE, downloads possibly updated reference tables from the UN. Default: FALSE. |
verbose |
If TRUE, sends status updates to the console. If FALSE, runs functions quietly. Default: FALSE. |
The function allows you to query most possible input parameters that are listed by the Comtrade API. The following dataset_ids are permitted:
Datasets that contain codes for the commodity_code
argument. The name is
the same as you would provide under commodity_classification
.
'HS' This is probably the most common classification for goods.
'B4'
'B5'
'EB02'
'EB10'
'EB10S'
'EB'
'S1'
'S2'
'S3'
'S4'
'SS'
'reporter'
'partner'
'mode_of_transport'
'customs_code'
'flow_direction'
a tidy dataset with a reference table
## get HS commodity table ct_get_ref_table("HS") ## get reporter table ct_get_ref_table("reporter")
## get HS commodity table ct_get_ref_table("HS") ## get reporter table ct_get_ref_table("reporter")
This function is deprecated. There is no more reset
time, as the upper limit of 250 calls per day is enforced daily.
ct_get_remaining_hourly_queries(...)
ct_get_remaining_hourly_queries(...)
... |
Used to catch all possible arguments that users have supplied to this function. |
depreciation error
# no examples because only legacy function
# no examples because only legacy function
This function is deprecated. There is no more reset
time, as the upper limit of 250 calls per day is enforced daily.
ct_get_reset_time(...)
ct_get_reset_time(...)
... |
Used to catch all possible arguments that users have supplied to this function. |
depreciation error
# no examples because only legacy function
# no examples because only legacy function
Comtradr versions previous to version 1.0.1 have used a cache location that was not CRAN compliant. You can migrate any remaining files to the new cache location using this function. It will delete the old cache.
ct_migrate_cache()
ct_migrate_cache()
Nothing
ct_migrate_cache()
ct_migrate_cache()
A data.frame with a matched list of tidy and untidy column names for the results.
ct_pretty_cols
ct_pretty_cols
country_codes
A dataframe with 47 rows and twi columns:
tidy columns
original column names
This function is deprecated.
Please use set_primary_comtrade_key()
instead.
ct_register_token(...)
ct_register_token(...)
... |
Used to catch all possible arguments that users have supplied to this function. |
depreciation error
# no examples because only legacy function
# no examples because only legacy function
This function is deprecated Please use ct_get_data()
instead.
ct_search(...)
ct_search(...)
... |
Used to catch all possible arguments that users have supplied to this function. |
depreciation error
# no examples because only legacy function
# no examples because only legacy function
This function is deprecated. Please use update
parameter in the main ct_get_data
function instead.
ct_update_databases(...)
ct_update_databases(...)
... |
Used to catch all possible arguments that users have supplied to this function. |
depreciation error
# no examples because only legacy function
# no examples because only legacy function
This function is deprecated. Please use the process
argument in the main function instead.
ct_use_pretty_cols(...)
ct_use_pretty_cols(...)
... |
Used to catch all possible arguments that users have supplied to this function. |
depreciation error
# no examples because only legacy function
# no examples because only legacy function
If you would like your Comtrade API key to persist in between sessions,
use usethis::edit_r_environ()
to add the env variable COMTRADE_PRIMARY
to your environment file.
get_primary_comtrade_key()
get_primary_comtrade_key()
Gets your primary comtrade key from the environment var COMTRADE_PRIMARY
## get API key get_primary_comtrade_key()
## get API key get_primary_comtrade_key()
If you would like your Comtrade API key to persist in between sessions,
use usethis::edit_r_environ()
to add the env variable COMTRADE_PRIMARY
to your environment file.
set_primary_comtrade_key(key = NULL)
set_primary_comtrade_key(key = NULL)
key |
Provide your primary comtrade key |
Saves your comtrade primary key in the environment.
## set API key set_primary_comtrade_key("xxxxxc678ca4dbxxxxxxxx8285r3")
## set API key set_primary_comtrade_key("xxxxxc678ca4dbxxxxxxxx8285r3")