Get Bilateral Trade Data — ct

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

# \donttest{
op <- options(comtrade.cache_dir = tempdir())

# The Comtrade API is rate-limited and can return a non-JSON response
# under load. tryCatch so the examples degrade gracefully if that
# happens during the CRAN check.

# UK total exports to the world, 2023
uk <- tryCatch(ct_trade("GBR", year = 2023, flow = "X"),
               error = function(e) NULL)
if (!is.null(uk)) head(uk)

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

# Australia's top-level trade with China
tryCatch(ct_trade("AUS", partner = "CHN", year = 2023),
         error = function(e) NULL)
#> NULL

options(op)
# }