Skip to contents

Getting Started with comex

Source: vignettes/getting-started.Rmd
getting-started.Rmd

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
state state general, city
city city city
transport_mode transportMode general
customs_unit urf general
ncm ncm general
hs6 / sh6 sh6 general
hs4 / sh4 sh4 general
hs2 / sh2 sh2 general
section section general, city
cgce_n1 / cgce_n2 / cgce_n3 cgceN1/N2/N3 general
sitc_section … sitc_item cuciSection…cuciItem general
isic_section … isic_class isicSection…isicClass general
nbm nbm historical
company_size companySize general

Note: City endpoint uses heading (≈HS4), chapter (≈HS2), section — not sh2/sh4/sh6. 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