Help for package tradestatistics

Type:

Package

Title:

Open Trade Statistics API Wrapper and Utility Program

Version:

7.0.0

Description:

Access 'Open Trade Statistics' API from R to download international trade data.

License:

Apache License (≥ 2)

URL:

https://docs.ropensci.org/tradestatistics/

BugReports:

https://github.com/ropensci/tradestatistics/issues/

Depends:

R (≥ 2.10)

Imports:

crul, data.table, digest, jsonlite, memoise

Suggests:

covr, knitr, rmarkdown, testthat (≥ 2.1.0), tibble, vcr

VignetteBuilder:

knitr

Encoding:

UTF-8

LazyData:

TRUE

Config/roxygen2/version:

8.0.0

NeedsCompilation:

Packaged:

2026-07-07 19:18:54 UTC; pacha

Author:

Mauricio Vargas

[aut, cre, cph], Joshua Kunst [ctb] (contributed to different parts of the pre-release code), Alexey Kravchenko [ctb] (reviewed 2021 version of the API), Emma Mendelsohn [ctb] (updated the functions to take available years from the API instead of hardcoded values), Daniela de los Santos [ctb] (proposed improvements to default parameters), Emily Riederer [rev] (reviewed the package for rOpenSci, see https://github.com/ropensci/onboarding/issues/274), Mark Padgham [rev] (reviewed the package for rOpenSci, see https://github.com/ropensci/onboarding/issues/274), Amanda Dobbyn [rev] (reviewed a previous package that evolved into the current package for rOpenSci, see https://github.com/ropensci/onboarding/issues/217), Jorge Cimentada [rev] (reviewed a previous package that evolved into the current package for rOpenSci, see https://github.com/ropensci/onboarding/issues/217), UN Comtrade [dtc], The World Bank [dtc]

Maintainer:

Mauricio Vargas <m.vargas.sepulveda@gmail.com>

Repository:

CRAN

Date/Publication:

2026-07-07 21:00:02 UTC

tradestatistics: Open Trade Statistics API Wrapper and Utility Program

Description

Access 'Open Trade Statistics' API from R to download international trade data.

Author(s)

Maintainer: Mauricio Vargas m.vargas.sepulveda@gmail.com (ORCID) [copyright holder]

Authors:

Mauricio Vargas m.vargas.sepulveda@gmail.com (ORCID) [copyright holder]

Other contributors:

Joshua Kunst (contributed to different parts of the pre-release code) [contributor]
Alexey Kravchenko (reviewed 2021 version of the API) [contributor]
Emma Mendelsohn (updated the functions to take available years from the API instead of hardcoded values) [contributor]
Daniela de los Santos (proposed improvements to default parameters) [contributor]
Emily Riederer (reviewed the package for rOpenSci, see https://github.com/ropensci/onboarding/issues/274) [reviewer]
Mark Padgham (reviewed the package for rOpenSci, see https://github.com/ropensci/onboarding/issues/274) [reviewer]
Amanda Dobbyn (reviewed a previous package that evolved into the current package for rOpenSci, see https://github.com/ropensci/onboarding/issues/217) [reviewer]
Jorge Cimentada (reviewed a previous package that evolved into the current package for rOpenSci, see https://github.com/ropensci/onboarding/issues/217) [reviewer]
UN Comtrade [data contributor]
The World Bank [data contributor]

Caching wrapper to reduce API calls (internal)

Description

Eases saving the data downloaded from api.tradestatistics.io and prevents ots_read_from_api() from downloading the same twice.

Usage

ots_cache(use_cache, file, ...)

Arguments

use_cache

Logical to save and load from cache. If TRUE, the results will be cached in memory if file is NULL or on disk if 'file' is not NULL.

file

Character with the full file path to save the data.

...

Additional parameters inherited from ots_create_tidy_data().

OTS Countries

Description

Official country names, ISO-3 codes, continent and EU membership.

Usage

ots_countries

Format

A data frame with 308 observations on the following 5 variables

country: Official name (e.g. United Kingdom)
iso3: ISO-3 code (e.g. "GBR")
dynamic_code: Deambiguated ISO-3 code (e.g. "DEU.X" for East Germany)
continent: Corresponding continent (e.g., Europe)
colour: Assigned colour by continen (e.g., '#d1a1bc')

Source

Derived from USITC

String matching of official country names and ISO-3 codes according to the United Nations nomenclature

Description

Takes a text string and searches within the package data for a country code in the context of valid API country codes.

Usage

ots_country_code(countryname = NULL)

Arguments

countryname

A text string such as "Chile", "CHILE" or "CHL".

Value

A single character if there is a exact match (e.g. ots_country_code("Chile")) or a tibble in case of multiple matches (e.g. ots_country_code("Germany"))

Examples

ots_country_code("Chile ")
ots_country_code("america")
ots_country_code("UNITED  STATES")
ots_country_code(" united_")

Downloads and processes the data from the API to return a human-readable tibble

Description

Accesses api.tradestatistics.io and performs different API calls to transform and return tidy data.

Usage

ots_create_tidy_data(
  years = 2020,
  importers = "all",
  exporters = "all",
  sectors = "all",
  industries = "all",
  table = "itpde_imp",
  max_attempts = 5,
  use_cache = FALSE,
  file = NULL
)

Arguments

years

Year contained within the years specified in api.tradestatistics.io/year_range (e.g., 2002 or seq(2002, 2010, 2)). Default set to 2019.

importers

Importers (e.g. "chl", "Chile" or c("chl", "Peru")). Default set to "all".

exporters

Exporters (e.g. "chl", "Chile" or c("chl", "Peru")). Default set to "all".

sectors

Sectors (e.g. "Agriculture", 1 or search matches for "agri") to filter sectors. Default set to "all".

industries

Industries (e.g. "Cereal products", 5 or search matches for "cereal") to filter industries. Default set to "all".

table

Character string to select the table to obtain the data. Default set to itpde_imp (aggregate trade by importer-year). Run ots_tables in case of doubt.

max_attempts

How many times to try to download data in case the API or the internet connection fails when obtaining data. Default set to 5.

use_cache

Logical to save and load from cache. If TRUE, the results will be cached in memory if file is NULL or on disk if 'file' is not NULL. Default set to FALSE.

file

Optional character with the full file path to save the data. Default set to NULL.

Value

A tibble that describes bilateral trade metrics (imports, exports, trade balance and relevant metrics such as exports growth w/r to last year) between a reporter and partner country.

Examples

## Not run: 
# The next examples can take more than 5 seconds to compute,
# so these are just shown without evaluation according to CRAN rules

# Run `ots_countries` to display the full table of countries
# Run `ots_sectors` to display the full table of sectors

# Agricultural trade (sector)
ots_create_tidy_data(years = 2020, sectors = "Agriculture",
 table = "itpde_sec")

# Cereal products trade (industry-importer)
ots_create_tidy_data(years = 2020, importers = "chl",
 industries = "Cereal products", table = "itpde_imp_ind")

# Aggregate trade (bilateral)
ots_create_tidy_data(years = 2020, importers = "chl",
 exporters = c("arg", "bra"), table = "itpde_imp_exp")

## End(Not run)

Downloads and processes the data from the API to return a human-readable tibble (memoised, internal)

Description

A composition of ots_create_tidy_data_unmemoised() and memoise() for caching the output

Usage

ots_create_tidy_data_memoised(
  years = 2018,
  importers = "usa",
  exporters = "all",
  sectors = "all",
  industries = "all",
  table = "itpde_imp",
  max_attempts = 5
)

Downloads and processes the data from the API to return a human-readable tibble (unmemoised, internal)

Description

A separation of ots_create_tidy_data() for making caching optional.

Usage

ots_create_tidy_data_unmemoised(
  years = 2018,
  importers = "usa",
  exporters = "all",
  sectors = "all",
  industries = "all",
  table = "itpde_imp",
  max_attempts = 5
)

OTS Industries

Description

Industry IDs.

Usage

ots_industries

Format

A data frame with 170 observations on the following 2 variables

industry_descr: Industry name (e.g. 'Wheat')
industry_id: Industry code (e.g. '1')

Source

Derived from USITC

String matching of industry names and IDs

Description

Takes a text string and searches within the package data for all matching industry IDs in the context of valid API industry codes.

Usage

ots_industry_code(industry = NULL)

Arguments

industry

A text string such as "Wheat", "CEREAL" or "oilseed".

Value

A data frame with all possible matches (no uppercase distinction) showing the industry name and industry ID.

Examples

ots_industry_code("Wheat")
ots_industry_code("cereal")

Reads data from the API (internal function)

Description

Accesses api.tradestatistics.io and performs different API calls to return data.frames by reading JSON data. The parameters here are passed from ots_create_tidy_data.

Usage

ots_read_from_api(
  year = NULL,
  importer = NULL,
  exporter = NULL,
  sector = "all",
  industry = "all",
  table = "itpde_imp",
  max_attempts = 5
)

String matching of broad sector names and IDs

Description

Takes a text string and searches within the package data for all matching sector IDs in the context of valid API sector codes.

Usage

ots_sector_code(sector = NULL)

Arguments

sector

A text string such as "Agriculture", "MINING" or "serv".

Value

A data frame with all possible matches (no uppercase distinction) showing the sector name and sector ID.

Examples

ots_sector_code("Agriculture")
ots_sector_code("mining")

OTS Sectors

Description

Broad sector IDs.

Usage

ots_sectors

Format

A data frame with 4 observations on the following 2 variables

broad_sector: Sector name (e.g. 'Agriculture')
broad_sector_id: Sector code (e.g. '1')
colour: Sector colour (e.g., '#74c0e2')

Source

Derived from USITC

OTS Tables

Description

Existing API tables with both description and source.

Usage

ots_tables

Format

A data frame with 30 rows and 3 variables

table: Table name
description: Description of table contents
source: Source for the data

Source

Derived from USITC

Package {tradestatistics}

tradestatistics: Open Trade Statistics API Wrapper and Utility Program

Description

Author(s)

See Also

Caching wrapper to reduce API calls (internal)

Description

Usage

Arguments

OTS Countries

Description

Usage

Format

Source

String matching of official country names and ISO-3 codes according to the United Nations nomenclature

Description

Usage

Arguments

Value

Examples

Downloads and processes the data from the API to return a human-readable tibble

Description

Usage

Arguments

Value

Examples

Downloads and processes the data from the API to return a human-readable tibble (memoised, internal)

Description

Usage

Downloads and processes the data from the API to return a human-readable tibble (unmemoised, internal)

Description

Usage

OTS Industries

Description

Usage

Format

Source

String matching of industry names and IDs

Description

Usage

Arguments

Value

Examples

Reads data from the API (internal function)

Description

Usage

String matching of broad sector names and IDs

Description

Usage

Arguments

Value

Examples

OTS Sectors

Description

Usage

Format

Source

OTS Tables

Description

Usage

Format

Source