Querying Trade Data

The comexr package provides three query endpoints, each covering a different time period and level of geographic detail:

Function	Endpoint	Period	Geography
`comex_query()`	POST /general	1997–present	National
`comex_query_city()`	POST /cities	1997–present	Municipal
`comex_historical()`	POST /historical-data/	1989–1996	National

Convenience wrappers comex_export() and comex_import() call comex_query() with the flow pre-set.

Basic queries

Exports by country

library(comexr)

exports <- comex_export(
  start_period = "2024-01",
  end_period   = "2024-12",
  details      = "country"
)
#> ℹ Querying exports from 2024-01 to 2024-12
#> ✔ POST /general [580ms]
#> ✔ 219 records found

By default, comex_export() returns FOB value (US$) and net weight (kg). Each row is a combination of the requested detail fields and the year.

Imports with CIF value

The import endpoint supports additional metrics — freight, insurance, and CIF:

imports <- comex_import(
  start_period = "2024-01",
  end_period   = "2024-06",
  details      = "country",
  metric_cif   = TRUE
)
# Returns columns: year, country, metricFOB, metricKG, metricCIF

Monthly breakdown

Set month_detail = TRUE to get data split by month:

monthly <- comex_export(
  start_period = "2024-01",
  end_period   = "2024-06",
  details      = "country",
  month_detail = TRUE
)
# Now each row also includes a month column

Multiple grouping fields

Pass a character vector to details to cross-tabulate:

by_country_product <- comex_export(
  start_period = "2024-01",
  end_period   = "2024-03",
  details      = c("country", "hs4"),
  month_detail = TRUE
)
# Rows grouped by: year × month × country × HS4 product heading

Applying filters

Use filters to restrict the query to specific values. Filter codes come from the auxiliary tables.

# Step 1: Find the codes for China and USA
countries <- comex_countries(search = "China")
# id = 160 (China), 249 (United States)

# Step 2: Query only exports to these countries
to_china_usa <- comex_export(
  start_period = "2024-01",
  end_period   = "2024-12",
  details      = c("country", "section"),
  filters      = list(country = c(160, 249))
)

Multiple filters can be combined:

# Exports of HS section 02 (Vegetable products) from São Paulo
sp_veg <- comex_export(
  start_period = "2024-01",
  end_period   = "2024-12",
  details      = c("state", "hs2"),
  filters      = list(state = 35, sh2 = "02")
)

The generic `comex_query()`

For full control, use comex_query() which lets you specify flow, metrics, and all options:

result <- comex_query(
  flow         = "import",
  start_period = "2023-01",
  end_period   = "2023-12",
  details      = c("country", "ncm"),
  filters      = list(country = c(160)),
  month_detail = FALSE,
  metric_fob   = TRUE,
  metric_kg    = TRUE,
  metric_statistic = TRUE,
  metric_freight   = TRUE,
  metric_insurance = TRUE,
  metric_cif       = TRUE,
  language     = "en"
)

City-level queries

The city endpoint provides municipal-level detail but with a more limited set of grouping fields and metrics.

# Which details are available for city queries?
comex_details("city")
#> # A tibble: 7 × 2
#>    filter        text
#>    <chr>         <chr>
#>  1 country       Countries
#>  2 economicBlock Economic Blocks
#>  3 state         States
#>  4 city          Cities
#>  5 heading       Headings
#>  6 chapter       Chapters
#>  7 section       Sections

# Which metrics?
comex_metrics("city")
#> # A tibble: 2 × 2
#>    id          text
#>    <chr>       <chr>
#>  1 metricFOB   US$ FOB
#>  2 metricKG    Net Weight (KG)

Important: The city endpoint uses heading, chapter, and section instead of sh6/sh4/sh2. NCM and classification details (CGCE, SITC, ISIC) are not available. CIF and freight metrics are not available either.

# Exports from Pernambuco (state 26) by country
pe_exports <- comex_query_city(
  flow         = "export",
  start_period = "2024-01",
  end_period   = "2024-12",
  details      = c("state", "country"),
  filters      = list(state = 26)
)

# Exports from Recife (city 2611606) by product section
recife <- comex_query_city(
  flow         = "export",
  start_period = "2024-01",
  end_period   = "2024-06",
  details      = c("city", "section"),
  filters      = list(city = 2611606)
)

Historical data (1989–1996)

The historical endpoint covers the period before the current NCM nomenclature was adopted. It uses the NBM (Nomenclatura Brasileira de Mercadorias) system.

comex_available_years("historical")
#> $max
#> [1] "1996"
#> $min
#> [1] "1989"

comex_details("historical")
#> # A tibble: 4 × 2
#>    filter  text
#>    <chr>   <chr>
#>  1 country Countries
#>  2 state   States
#>  3 nbm     NBM
#>  4 section Sections

# Historical exports by country in 1990
hist_1990 <- comex_historical(
  flow         = "export",
  start_period = "1990-01",
  end_period   = "1990-12",
  details      = "country"
)

Working with results

All query functions return a data.frame (or tibble if the tibble package is installed). Column names come directly from the API — they are the same as the detail/metric names you requested.

library(dplyr)

# Top 10 export destinations in 2024 by FOB value
top10 <- comex_export(
  start_period = "2024-01",
  end_period   = "2024-12",
  details      = "country"
) |>
  arrange(desc(metricFOB)) |>
  head(10)

# Monthly export trend to China
china_monthly <- comex_export(
  start_period = "2024-01",
  end_period   = "2024-12",
  details      = "country",
  filters      = list(country = 160),
  month_detail = TRUE
)

Tips and best practices

Start with discovery. Use comex_details(), comex_filters(), and comex_metrics() before building complex queries.
Use filters to reduce response size. The API has a limit of ~150,000 rows. If your query is too broad, the API will timeout. Add filters or reduce the date range.
Filter codes are integers. Use comex_countries(), comex_states(), comex_filter_values() to find the numeric codes.
The details parameter accepts user-friendly names. Write "hs4" instead of "sh4", "transport_mode" instead of "transportMode". The package maps them automatically.
City endpoint has fewer features. Only 7 details, 2 metrics, and different product grouping names (heading/chapter/section).
Historical endpoint uses NBM. The "ncm" detail is not available — use "nbm" instead.