The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

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

  1. Start with discovery. Use comex_details(), comex_filters(), and comex_metrics() before building complex queries.

  2. 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.

  3. Filter codes are integers. Use comex_countries(), comex_states(), comex_filter_values() to find the numeric codes.

  4. The details parameter accepts user-friendly names. Write "hs4" instead of "sh4", "transport_mode" instead of "transportMode". The package maps them automatically.

  5. City endpoint has fewer features. Only 7 details, 2 metrics, and different product grouping names (heading/chapter/section).

  6. Historical endpoint uses NBM. The "ncm" detail is not available — use "nbm" instead.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.