The ComexStat API provides a rich set of auxiliary tables that serve two purposes: looking up the codes you need for filters, and enriching query results with human-readable labels.
Countries and economic blocs
Countries
library(comexr)
# Full list (281 entries)
countries <- comex_countries()
countries
#> # A tibble: 281 × 2
#> id text
#> <chr> <chr>
#> 1 994 A Designar
#> 2 132 Afeganistão
#> 3 175 Albânia
#> ...
# Search by name
comex_countries(search = "United")
#> # A tibble: 5 × 2
#> id text
#> <chr> <chr>
#> 1 249 Estados Unidos
#> 2 ...Note: The /tables/countries endpoint
does not accept a language parameter.
Country names are returned in Portuguese.
Get detailed info about a specific country:
comex_country_detail(105)
#> $id
#> [1] "105"
#> $country
#> [1] "Brasil"
#> $coPaisIson3
#> [1] "076"
#> $coPaisIsoa3
#> [1] "BRA"Economic blocs
# In Portuguese
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
#> 3 48 América do Sul
#> ...
# In English
comex_blocs(language = "en")The add parameter can request additional columns
(API-dependent):
comex_blocs(language = "en", add = TRUE)Geographic tables
States (UF)
states <- comex_states()
states
#> # A tibble: 34 × 3
#> text id uf
#> <chr> <chr> <chr>
#> 1 Acre 12 AC
#> 2 Alagoas 27 AL
#> 3 Amapá 16 AP
#> ...
# Detail for a specific state
comex_state_detail(26)
#> $coUf
#> [1] "26"
#> $sgUf
#> [1] "PE"
#> $noUf
#> [1] "Pernambuco"
#> $noRegiao
#> [1] "REGIAO NORDESTE"Cities
# Full list (5,570 municipalities)
cities <- comex_cities()
cities
#> # A tibble: 5,570 × 3
#> id text noMunMin
#> <chr> <chr> <chr>
#> 1 5300050 Abadia de Goiás - GO Abadia de Goiás
#> ...
# Detail for a specific city
comex_city_detail(2611606)
#> $coMunGeo
#> [1] "2611606"
#> $noMun
#> [1] "RECIFE"
#> $noMunMin
#> [1] "Recife"
#> $sgUf
#> [1] "PE"Transport modes
comex_transport_modes()
#> # A tibble: 17 × 2
#> id text
#> <chr> <chr>
#> 1 00 VIA NAO DECLARADA
#> 2 01 MARITIMA
#> 3 02 FLUVIAL
#> 4 04 AEREA
#> 5 05 POSTAL
#> ...
# Note: use string codes with leading zeros
comex_transport_mode_detail("01")
#> $coVia
#> [1] "01"
#> $noVia
#> [1] "MARITIMA"Customs units (URF)
customs <- comex_customs_units()
customs
#> # A tibble: 278 × 2
#> id text
#> <chr> <chr>
#> 1 0000000 0000000 - NAO INFORMADO
#> 2 0117600 0117600 - ALF - PORTO DE MANAUS
#> ...
comex_customs_unit_detail(817600)Product nomenclatures
NCM — Mercosur Common Nomenclature (1997–present)
The NCM is the primary product classification for Brazilian trade since 1997. It is an 8-digit code based on the Harmonized System (HS).
# Paginated — use page and per_page
ncm <- comex_ncm(language = "en", page = 1, per_page = 10)
ncm
#> # A tibble: 10 × 3
#> noNCM unit coNcm
#> <chr> <chr> <chr>
#> 1 Adhesives based on rubber KILOGRAM 35069110
#> ...
# Search by keyword
comex_ncm(language = "en", search = "soybean")
# Get detail for a specific NCM code
comex_ncm_detail("02042200")
#> $id
#> [1] "02042200"
#> $text
#> [1] "Outras peças não desossadas de ovino, frescas ou refrigeradas"NBM — Brazilian Nomenclature of Goods (historical, 1989–1996)
nbm <- comex_nbm(language = "en", page = 1, per_page = 5)
nbm
#> # A tibble: 5 × 2
#> nbm coNbm
#> <chr> <chr>
#> 1 3-IODO-1-PROPENO (IODETO DE ALILA) 2903300305
#> ...
comex_nbm_detail("2924101100")
#> $coNBM
#> [1] "2924101100"
#> $noNBM
#> [1] "ETILENO BIS ESTEARAMIDA"HS — Harmonized System
The HS table provides the international product classification hierarchy: subheading (6-digit), heading (4-digit), and chapter (2-digit).
hs <- comex_hs(language = "en", page = 1, per_page = 5)
hs
#> # A tibble: 5 × 6
#> subHeadingCode subHeading headingCode heading
#> <chr> <chr> <chr> <chr>
#> 1 010110 Pure-bred breeding horses ... 0101 Live horses, ...
#> ...Note: The HS table does not have a
search parameter — only language,
add, page, and per_page.
Classification tables
CGCE — Classification by Broad Economic Categories (BEC)
cgce <- comex_cgce(language = "en", page = 1, per_page = 5)
cgce
#> # A tibble: 5 × 6
#> coBECLevel3 BECLevel3 coBECLevel2 BECLevel2
#> <chr> <chr> <chr> <chr>
#> 1 110 Capital goods, except indust... 11 Capital goods, exce...
#> ...SITC — Standard International Trade Classification (CUCI)
sitc <- comex_sitc(language = "en", page = 1, per_page = 3)
sitc
#> # A tibble: 3 × 10
#> coSITCBasicHeading SITCBasicHeading coSITCSubGroup SITCSubGroup ...
#> <chr> <chr> <chr> <chr> ...
#> 1 I Gold, monetary 9710 Gold, non-m... ...
#> ...The SITC table has 5 levels of hierarchy: Section → Division → Group → Subgroup → Basic Heading.
ISIC — International Standard Industrial Classification
isic <- comex_isic(language = "en", page = 1, per_page = 5)Note: The ISIC table uses the same endpoint as SITC
(/tables/product-categories). The API does not currently
provide a separate ISIC-only table.
Using table codes in queries
The main purpose of these tables is to find the numeric codes to use
in filters:
# 1. Find country code for Argentina
countries <- comex_countries(search = "Argentina")
# id = "021"
# 2. Find state code for Rio Grande do Sul
states <- comex_states()
# RS = id "43"
# 3. Query: Exports from RS to Argentina, grouped by HS4
result <- comex_export(
start_period = "2024-01",
end_period = "2024-12",
details = c("state", "country", "hs4"),
filters = list(
country = 21,
state = 43
)
)Runtime discovery
If you are unsure which filters or details are valid for a given endpoint, use the discovery functions at runtime:
# What filters can I use for city queries?
comex_filters("city")
# What values does filter "state" accept for city queries?
comex_filter_values("state", type = "city")
# What metrics are available for historical queries?
comex_metrics("historical")This is particularly useful when the API is updated with new fields or metrics.