comtrade: Access and Analyse UN Comtrade International Trade Data

Description

Download and analyse international merchandise and services trade data from the United Nations Comtrade database https://comtradeplus.un.org/. Retrieve bilateral trade flows, compute trade analytics (revealed comparative advantage, trade concentration, trade balance), and convert between commodity classifications (HS, SITC, BEC). Covers 200+ reporter countries, 60+ years of goods trade data (1962-present), and services trade via EBOPS. Works without registration for basic queries. A free API key from https://comtradedeveloper.un.org/ unlocks full access.

Author(s)

Maintainer: Charles Coverdale charlesfcoverdale@gmail.com

See Also

Useful links:

• https://github.com/charlescoverdale/comtrade

• Report bugs at https://github.com/charlescoverdale/comtrade/issues

Check Data Availability

Description

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

Usage

ct_available(reporter, cache = TRUE)

Arguments

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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)