Getting Started with comex

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.

Overview

The comex package provides an R interface to the ComexStat API from the Brazilian Ministry of Development, Industry, Trade and Services (MDIC). It gives you programmatic access to:

General trade data — exports and imports from 1997 to present, with 22 detail/grouping fields and 6 metrics.
City-level trade data — trade statistics broken down by municipality.
Historical data — export/import records from 1989 to 1996 using the older NBM nomenclature.
Auxiliary lookup tables — countries, economic blocs, states, cities, transport modes, customs units, and product nomenclatures (NCM, NBM, HS, CGCE, SITC).

The package has only two dependencies (httr2 and cli) and does not require a headless browser or any external software.

Installation

# Install from GitHub:
remotes::install_github("StrategicProjects/comexr")

Quick start

1. Check what data is available

Before querying, you can discover the date range, available grouping fields (details), and metrics for each data type:

library(comex)

# What is the most recent data available?
comex_last_update("general")
#> $updated
#> [1] "2026-02-05"
#> $year
#> [1] "2026"
#> $monthNumber
#> [1] "01"

# What years are covered?
comex_available_years("general")
#> $max
#> [1] "2026"
#> $min
#> [1] "1997"

# What detail/grouping fields can I use?
comex_details("general")
#> # A tibble: 22 × 2
#>    filter        text
#>    <chr>         <chr>
#>  1 country       Countries
#>  2 economicBlock Economic Blocks
#>  3 state         States
#>  4 ...

2. Run a simple export query

The easiest way to query is with comex_export() and comex_import():

# Top export destinations in January 2024
exports <- comex_export(
  start_period = "2024-01",
  end_period   = "2024-01",
  details      = "country"
)

exports
#> # A tibble: 219 × 4
#>    year  country                   metricFOB metricKG
#>    <chr> <chr>                         <dbl>    <dbl>
#>  1 2024  China                    7812623070    ...
#>  2 2024  United States            3254810234    ...
#>  3 2024  Argentina                 916456789    ...
#>  ...

3. Add filters and multiple details

# Exports to China and USA, broken down by HS4 product group
exports_filtered <- comex_export(
  start_period = "2024-01",
  end_period   = "2024-06",
  details      = c("country", "hs4"),
  filters      = list(country = c(160, 249)),
  month_detail = TRUE
)

Filter codes come from the auxiliary tables — use comex_countries(), comex_states(), etc. to look them up.

4. Look up auxiliary tables

# All countries
countries <- comex_countries()
countries
#> # A tibble: 281 × 2
#>    id    text
#>    <chr> <chr>
#>  1 994   A Designar
#>  2 132   Afeganistão
#>  ...

# Search for a specific country
comex_countries(search = "Brazil")

Available detail names

The details parameter accepts user-friendly names that are mapped to the API’s internal names. Here is the full list:

User name	API name	Available in
`country`	`country`	general, city, historical
`bloc` / `economic_block`	`economicBlock`	general, city, historical
`state`	`state`	general, city, historical
`city`	`city`	city
`transport_mode`	`via`	general
`customs_unit`	`urf`	general
`ncm`	`ncm`	general
`hs6` / `sh6`	`subHeading`	general
`hs4` / `sh4`	`heading`	general, city
`hs2` / `sh2`	`chapter`	general, city
`section`	`section`	general, city
`cgce_n1` / `cgce_n2` / `cgce_n3`	`BECLevel1` / `BECLevel2` / `BECLevel3`	general
`sitc_section` / `sitc_division` / `sitc_group` / `sitc_subgroup` / `sitc_basic_heading`	`SITCSection` / `SITCDivision` / `SITCGroup` / `SITCSubGroup` / `SITCBasicHeading`	general
`isic_section` / `isic_division` / `isic_group` / `isic_class`	`ISICSection` / `ISICDivision` / `ISICGroup` / `ISICClass`	general
`nbm`	`nbm`	historical

Note: City endpoint uses heading (≈HS4), chapter (≈HS2), section — HS6 (subHeading) is not available for cities. Use comex_details("city") to confirm.

Language support

All functions accept a language parameter. Use "pt" (Portuguese), "en" (English), or "es" (Spanish):

comex_blocs(language = "pt")
#> # A tibble: 12 × 2
#>    id    text
#>    <chr> <chr>
#>  1 105   América Central e Caribe
#>  2 107   América do Norte
#>  ...

comex_blocs(language = "en")
#> # A tibble: 12 × 2
#>    id    text
#>    <chr> <chr>
#>  1 105   Central America and Caribbean
#>  2 107   North America
#>  ...

Next steps

See vignette("querying-trade-data") for advanced query patterns including monthly breakdowns, multiple metrics, CIF values, and working with city and historical endpoints.
See vignette("auxiliary-tables") for a tour of all lookup tables (NCM, HS, countries, blocs, classifications).

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.