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.

Auxiliary Tables & Lookups

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.

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.