# 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 values are only exposed by the API as filter values, not as a
    # dedicated table. `comex_isic()` calls the matching /general/filters/
    # endpoint for the requested level.
    isic <- comex_isic(level = "section", language = "en")

Note: The ComexStat API does not expose an ISIC table endpoint. `comex_isic()` instead retrieves ISIC values from `/general/filters/ISICSection|ISICDivision|ISICGroup|ISICClass`.

## 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
      )
    )

## Pagination

Some product tables have thousands of entries. Use `page` and `per_page` to paginate:

    # Get all NCM codes (13,730 entries), 500 at a time
    all_ncm <- list()
    page <- 1

    repeat {
      batch <- comex_ncm(language = "en", page = page, per_page = 500)
      if (nrow(batch) == 0) break
      all_ncm[[page]] <- batch
      page <- page + 1
    }

    all_ncm_df <- do.call(rbind, all_ncm)
    nrow(all_ncm_df)
    #> [1] 13730

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