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 foundBy 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, metricCIFMonthly 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 columnMultiple 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 headingApplying 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(), andcomex_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
detailsparameter 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.