Package 'comtrade'

Check Data Availability

Description

Check which years and classifications have data available for a given reporter country.

Usage

ct_available(reporter, cache = TRUE)

Arguments

reporter	Character. Reporter country ISO3 code.
cache	Logical. Cache results. Default TRUE.

Value

A data.frame with columns: year, classification, type (C/S), frequency (A/M).

Examples

op <- options(comtrade.cache_dir = tempdir())
ct_available("GBR")
options(op)

---

Trade Balance by Partner

Description

Compute the trade balance (exports minus imports) for a reporter country against each trading partner.

Usage

ct_balance(
  reporter,
  partner = "0",
  year = NULL,
  commodity = "TOTAL",
  cache = TRUE
)

Arguments

reporter	Character. Reporter country ISO3 code.
partner	Character. Partner country code, or "0" for World. Default "0".
year	Integer. Year(s) to query.
commodity	Character. Commodity code. Default "TOTAL".
cache	Logical. Default TRUE.

Value

A data.frame with columns: partner, partner_desc, year, exports, imports, balance.

Examples

op <- options(comtrade.cache_dir = tempdir())
ct_balance("GBR", year = 2023)
options(op)

---

Clear the Comtrade Cache

Description

Remove all cached Comtrade API responses from the local cache directory.

Usage

ct_cache_clear()

Value

Invisibly returns TRUE if the cache was cleared, FALSE if no cache directory existed.

Examples

op <- options(comtrade.cache_dir = tempdir())
ct_cache_clear()
options(op)

---

Search Commodity Codes

Description

Search the HS (Harmonized System) commodity classification for codes matching a keyword or code pattern. Uses a built-in table of 96 two-digit HS chapters with descriptions.

Usage

ct_commodities(query = NULL, level = NULL)

Arguments

query	Character. Search term (matched against commodity descriptions) or a partial HS code (e.g., "27" for mineral fuels). Default NULL (return all).
level	Integer. HS digit level to return. Currently only level 2 is available from the built-in table. Default NULL (all levels).

Value

A data.frame with columns:

code

HS 2-digit chapter code

description

Chapter description

level

Digit level (always 2 for built-in table)

parent

Parent code (NA for 2-digit chapters)

Examples

# Search for petroleum-related codes
ct_commodities("petroleum")

# List all 2-digit HS chapters
ct_commodities()

# Find codes starting with "27" (mineral fuels)
ct_commodities("27")

---

Compare Countries

Description

Compare multiple countries' trade in a given commodity, showing exports, imports, balance, and revealed comparative advantage.

Usage

ct_compare(reporters, commodity = "TOTAL", year = NULL, cache = TRUE)

Arguments

reporters	Character vector. ISO3 codes for countries to compare.
commodity	Character. Commodity code. Default "TOTAL".
year	Integer. Year to query.
cache	Logical. Default TRUE.

Value

A data.frame with columns: reporter, reporter_desc, exports, imports, balance, rca.

Examples

op <- options(comtrade.cache_dir = tempdir())
ct_compare(c("GBR", "DEU", "FRA"), commodity = "87", year = 2023)
options(op)

---

Convert Between Trade Classifications

Description

Convert commodity codes between HS (Harmonized System), SITC, and BEC classifications. Uses a built-in concordance table covering the most common 2-digit HS chapters mapped to SITC sections and BEC categories.

Usage

ct_concordance(code, from = "HS", to = "SITC")

Arguments

code	Character. The commodity code(s) to convert.
from	Character. Source classification: "HS", "SITC", or "BEC".
to	Character. Target classification: "HS", "SITC", or "BEC".

Details

For detailed 4/6-digit concordances, see the concordance R package on CRAN.

Value

A data.frame with columns: from_code, from_desc, to_code, to_desc.

Examples

# Convert HS chapter 27 (mineral fuels) to SITC
ct_concordance("27", from = "HS", to = "SITC")

# Convert SITC section 0 (food) to HS
ct_concordance("0", from = "SITC", to = "HS")

---

Trade Growth Over Time

Description

Compute year-on-year and cumulative trade growth for a bilateral flow.

Usage

ct_growth(
  reporter,
  partner = "0",
  commodity = "TOTAL",
  flow = "X",
  years = NULL,
  cache = TRUE
)

Arguments

reporter	Character. Reporter country ISO3 code.
partner	Character. Partner country code. Default "0" (World).
commodity	Character. Commodity code. Default "TOTAL".
flow	Character. "X" or "M". Default "X".
years	Integer vector. Years to query (at least 2).
cache	Logical. Default TRUE.

Value

A data.frame with columns: year, value, growth_yoy, growth_cumulative, index_100.

Examples

op <- options(comtrade.cache_dir = tempdir())
ct_growth("GBR", flow = "X", years = 2018:2023)
options(op)

---

Trade Concentration Index (HHI)

Description

Compute the Herfindahl-Hirschman Index measuring the concentration of a country's trade across partners or products.

Usage

ct_hhi(
  reporter,
  flow = "X",
  year = NULL,
  by = "partner",
  level = 2L,
  cache = TRUE
)

Arguments

reporter	Character. Reporter country ISO3 code.
flow	Character. "X" or "M". Default "X".
year	Integer. Year to query.
by	Character. Concentrate by "partner" or "product". Default "partner".
level	Integer. HS digit level (only used when by = "product"). Default 2.
cache	Logical. Default TRUE.

Details

HHI ranges from 0 (perfectly diversified) to 10,000 (single partner/product). Interpretation: < 1,500 = low concentration, 1,500-2,500 = moderate, > 2,500 = high.

Value

A data.frame with columns: year, hhi, concentration, n_items, top_item, top_share_pct.

Examples

op <- options(comtrade.cache_dir = tempdir())

# Export partner concentration
ct_hhi("AUS", flow = "X", year = 2023, by = "partner")

# Export product concentration
ct_hhi("AUS", flow = "X", year = 2023, by = "product")

options(op)

---

Revealed Comparative Advantage (Balassa Index)

Description

Compute the Revealed Comparative Advantage for a country's exports. RCA > 1 indicates the country has a comparative advantage in that product.

Usage

ct_rca(reporter, year = NULL, level = 2L, cache = TRUE)

Arguments

reporter	Character. Reporter country ISO3 code.
year	Integer. Year to query.
level	Integer. HS digit level: 2, 4, or 6. Default 2.
cache	Logical. Default TRUE.

Details

The Balassa index is defined as: RCA = (country exports of product i / country total exports) / (world exports of product i / world total exports)

Value

A data.frame with columns: commodity_code, commodity_desc, reporter_value, world_value, reporter_share, world_share, rca, has_advantage.

Examples

op <- options(comtrade.cache_dir = tempdir())
rca <- ct_rca("AUS", year = 2023)
# Products where Australia has comparative advantage
rca[rca$has_advantage, ]
options(op)

---

List Reporter Countries

Description

Get the list of countries that report trade data to UN Comtrade, with their ISO3 codes and M49 numeric codes.

Usage

ct_reporters(cache = TRUE)

Arguments

cache

Logical. Cache the reference table locally. Default TRUE.

Value

A data.frame with columns:

code

M49 numeric country code (used in API queries)

iso3

ISO 3166-1 alpha-3 code (e.g., GBR, USA, AUS)

name

Country name

is_group

Logical. TRUE for country groups (e.g., EU, OECD)

Examples

op <- options(comtrade.cache_dir = tempdir())
reporters <- ct_reporters()
head(reporters)
options(op)

---

Get Services Trade Data

Description

Download international services trade data from the UN Comtrade database using the EBOPS (Extended Balance of Payments Services) classification.

Usage

ct_services(
  reporter,
  partner = "0",
  service = "TOTAL",
  flow = c("X", "M"),
  year = NULL,
  cache = TRUE
)

Arguments

reporter	Character. Reporter country ISO3 code.
partner	Character. Partner country code. Default "0" (World).
service	Character. EBOPS service code. Default "TOTAL".
flow	Character. Trade flow: "X" (exports), "M" (imports). Can be a vector. Default c("X", "M").
year	Integer. Year(s) to query (2000-present). Default: most recent available year.
cache	Logical. Cache results locally. Default TRUE.

Value

A data.frame with columns: reporter, reporter_desc, partner, partner_desc, flow, flow_desc, service_code, service_desc, year, trade_value_usd.

Examples

op <- options(comtrade.cache_dir = tempdir())

# UK services exports to the world
ct_services("GBR", year = 2022, flow = "X")

options(op)

---

Set the Comtrade API Key

Description

Store your UN Comtrade API key for the current session. The key is saved as an R option and optionally as an environment variable for persistence.

Usage

ct_set_key(key, install = FALSE)

Arguments

key	Character. Your Comtrade API subscription key.
install	Logical. If TRUE, also sets the COMTRADE_API_KEY environment variable via Sys.setenv(), which persists for the current R session. For permanent storage, add COMTRADE_API_KEY=your-key to your .Renviron file. Default FALSE.

Details

Get a free API key at https://comtradedeveloper.un.org/. The free tier allows 500 calls per day and up to 100,000 records per call.

Value

Invisibly returns the key.

Examples

ct_set_key("your-subscription-key-here")

---

World Trade Share

Description

Compute a country's share of world trade in a given commodity.

Usage

ct_share(reporter, commodity = "TOTAL", flow = "X", year = NULL, cache = TRUE)

Arguments

reporter	Character. Reporter country ISO3 code.
commodity	Character. Commodity code. Default "TOTAL".
flow	Character. "X" or "M". Default "X".
year	Integer. Year to query.
cache	Logical. Default TRUE.

Value

A data.frame with columns: commodity_code, reporter_value, world_value, share_pct.

Examples

op <- options(comtrade.cache_dir = tempdir())
ct_share("AUS", commodity = "2601", flow = "X", year = 2023)
options(op)

---

Top Trading Partners

Description

Rank a country's trading partners by total trade value.

Usage

ct_top_partners(reporter, flow = "X", year = NULL, n = 20L, cache = TRUE)

Arguments

reporter	Character. Reporter country ISO3 code.
flow	Character. "X" for exports, "M" for imports. Default "X".
year	Integer. Year to query.
n	Integer. Number of top partners to return. Default 20.
cache	Logical. Default TRUE.

Value

A data.frame with columns: partner, partner_desc, value, share_pct, rank.

Examples

op <- options(comtrade.cache_dir = tempdir())
ct_top_partners("GBR", flow = "X", year = 2023)
options(op)

---

Top Export or Import Products

Description

Rank a country's traded products by value, showing the top N with percentage shares.

Usage

ct_top_products(
  reporter,
  flow = "X",
  year = NULL,
  n = 20L,
  level = 2L,
  cache = TRUE
)

Arguments

reporter	Character. Reporter country ISO3 code.
flow	Character. "X" for exports, "M" for imports.
year	Integer. Year to query.
n	Integer. Number of top products to return. Default 20.
level	Integer. HS digit level: 2, 4, or 6. Default 2.
cache	Logical. Default TRUE.

Value

A data.frame with columns: commodity_code, commodity_desc, value, share_pct, rank.

Examples

op <- options(comtrade.cache_dir = tempdir())
ct_top_products("AUS", flow = "X", year = 2023)
options(op)

---

Get Bilateral Trade Data

Description

Download merchandise trade data from the UN Comtrade database. Returns bilateral trade flows between reporter and partner countries, optionally filtered by commodity code and trade flow direction.

Usage

ct_trade(
  reporter,
  partner = "0",
  commodity = "TOTAL",
  flow = c("X", "M"),
  year = NULL,
  frequency = "A",
  classification = "HS",
  cache = TRUE
)

Arguments

reporter	Character. Reporter country ISO3 code (e.g., "GBR", "USA", "AUS") or numeric M49 code. Use "all" for all reporters (limited to 1 per query on the free tier).
partner	Character. Partner country ISO3 code, or "0" / "W00" for World (all partners aggregated). Default "0" (World).
commodity	Character. HS commodity code(s). "TOTAL" for aggregate trade, "AG2" for all 2-digit chapters, or specific codes like "2709" (crude petroleum). Default "TOTAL".
flow	Character. Trade flow: "X" (exports), "M" (imports), "RX" (re-exports), "RM" (re-imports). Can be a vector for multiple flows. Default c("X", "M").
year	Integer. Year(s) to query (1962-present). Can be a vector. Maximum 12-year span per query on the free tier. Default: most recent available year.
frequency	Character. "A" for annual (default), "M" for monthly.
classification	Character. Commodity classification system. Default "HS" (latest Harmonized System revision). See ct_commodities() for available classifications.
cache	Logical. Cache results locally for 24 hours. Default TRUE.

Value

A data.frame with columns:

reporter

Reporter country code

reporter_desc

Reporter country name

partner

Partner country code

partner_desc

Partner country name

flow

Trade flow code (X, M, RX, RM)

flow_desc

Trade flow description

commodity_code

Commodity code

commodity_desc

Commodity description

year

Reference year

period

Reference period (year or year-month)

trade_value_usd

Trade value in US dollars

net_weight_kg

Net weight in kilograms

quantity

Quantity in supplementary units

quantity_unit

Supplementary quantity unit

Examples

op <- options(comtrade.cache_dir = tempdir())

# UK total exports to the world, 2023
ct_trade("GBR", year = 2023, flow = "X")

# US imports of crude petroleum from Saudi Arabia
ct_trade("USA", partner = "SAU", commodity = "2709", flow = "M",
         year = 2020:2023)

# Australia's top-level trade with China
ct_trade("AUS", partner = "CHN", year = 2023)

options(op)

---