comexr: R Client for the ComexStat API

Description

The comexr package provides a complete R interface to the ComexStat API from the Brazilian Ministry of Development, Industry, Trade and Services (MDIC).

The API provides Brazilian foreign trade data from 1997 (general data) and from 1989 (historical data), along with auxiliary tables for product nomenclatures, countries, economic classifications, and more.

Query functions (POST)

These functions query aggregated export and import data with configurable filters, details, and metrics:

• comex_query(): Query general foreign trade data

• comex_export(): Shortcut for export queries

• comex_import(): Shortcut for import queries

• comex_query_city(): Query city-level data

• comex_historical(): Query historical data (1989-1996)

API metadata (GET)

Functions to retrieve information about the API itself:

• comex_last_update(): Date of last data update

• comex_available_years(): Available years for queries

• comex_filters(): Available filters

• comex_filter_values(): Possible values for a filter

• comex_details(): Available detail/grouping fields

• comex_metrics(): Available metrics

Auxiliary tables - Geography (GET)

• comex_countries(), comex_country_detail()

• comex_blocs()

• comex_states(), comex_state_detail()

• comex_cities(), comex_city_detail()

• comex_transport_modes(), comex_transport_mode_detail()

• comex_customs_units(), comex_customs_unit_detail()

Auxiliary tables - Products (GET)

• comex_ncm(), comex_ncm_detail()

• comex_nbm(), comex_nbm_detail()

• comex_hs()

Auxiliary tables - Classifications (GET)

• comex_cgce()

• comex_sitc()

• comex_isic()

Dependencies

The package uses only two dependencies:

• httr2 for all HTTP requests (no headless browser needed)

• cli for formatted console messages

Author(s)

Maintainer: Andre Leite leite@castlab.org

Authors:

• Marcos Wasilew marcos.wasilew@gmail.com

• Hugo Vasconcelos hugo.vasconcelos@ufpe.br

• Carlos Amorin carlos.agaf@ufpe.br

• Diogo Bezerra diogo.bezerra@ufpe.br

See Also

Useful links:

• https://strategicprojects.github.io/comexr/

• https://github.com/StrategicProjects/comexr

• Report bugs at https://github.com/StrategicProjects/comexr/issues

Get available years for queries

Description

Returns the first and last years available for queries in the API.

Usage

comex_available_years(type = "general", verbose = FALSE)

Arguments

Value

A list with min and max year values.

Examples

## Not run: 
comex_available_years()
comex_available_years("city")
comex_available_years("historical")

## End(Not run)

Get economic blocs table

Description

Returns the economic blocs table with codes and names. Economic blocs represent trade agreements between countries and regions.

Usage

comex_blocs(language = "en", search = NULL, add = NULL, verbose = FALSE)

Arguments

Value

A data.frame with economic bloc codes and names.

Examples

## Not run: 
comex_blocs()
comex_blocs(search = "mercosul")
comex_blocs(add = "country")

## End(Not run)

Get CGCE (Classification by Broad Economic Categories) table

Description

Returns the CGCE classification table from the ⁠/tables/classifications⁠ endpoint. CGCE groups products by use or economic purpose (e.g. capital goods, intermediate goods, consumer goods).

Usage

comex_cgce(
  language = "en",
  search = NULL,
  add = NULL,
  page = NULL,
  per_page = NULL,
  verbose = FALSE
)

Arguments

Value

A data.frame with CGCE codes and descriptions.

Examples

## Not run: 
# All CGCE classifications
comex_cgce()

# Search within CGCE
comex_cgce(search = "110")

## End(Not run)

Get Brazilian cities table

Description

Returns the Brazilian cities table with codes and names.

Usage

comex_cities(verbose = FALSE)

Arguments

Value

A data.frame with city (IBGE) codes and names.

Examples

## Not run: 
comex_cities()

## End(Not run)

Get city details

Description

Returns details for a specific Brazilian city.

Usage

comex_city_detail(city_id, verbose = FALSE)

Arguments

Value

A list with city details.

Examples

## Not run: 
comex_city_detail(5300050)

## End(Not run)

Get countries table

Description

Returns the countries table with codes and names.

Usage

comex_countries(search = NULL, verbose = FALSE)

Arguments

Value

A data.frame with country codes and names.

Examples

## Not run: 
comex_countries()
comex_countries(search = "bra")

## End(Not run)

Get country details

Description

Returns details for a specific country by its code.

Usage

comex_country_detail(id, verbose = FALSE)

Arguments

Value

A list with country details.

Examples

## Not run: 
comex_country_detail(105)

## End(Not run)

Get customs unit details

Description

Returns details for a specific customs unit (URF).

Usage

comex_customs_unit_detail(urf_id, verbose = FALSE)

Arguments

Value

A list with customs unit details.

Examples

## Not run: 
comex_customs_unit_detail(8110000)

## End(Not run)

Get customs units (URF) table

Description

Returns the customs units table (Unidades da Receita Federal) with codes and names. These are the Federal Revenue Service administrative units responsible for overseeing foreign trade operations.

Usage

comex_customs_units(verbose = FALSE)

Arguments

Value

A data.frame with customs unit codes and names.

Examples

## Not run: 
comex_customs_units()

## End(Not run)

Get available detail/grouping fields

Description

Returns the list of detail fields that can be used to group query results.

Usage

comex_details(type = "general", language = "en", verbose = FALSE)

Arguments

Value

A data.frame with available details.

Examples

## Not run: 
comex_details()
comex_details("city")
comex_details("historical")

## End(Not run)

Query exports

Description

Shortcut for comex_query() with flow = "export".

Usage

comex_export(
  start_period,
  end_period,
  details = NULL,
  filters = NULL,
  month_detail = FALSE,
  metric_fob = TRUE,
  metric_kg = TRUE,
  metric_statistic = FALSE,
  metric_freight = FALSE,
  metric_insurance = FALSE,
  metric_cif = FALSE,
  language = "en",
  verbose = TRUE
)

Arguments

Value

A data.frame (or tibble) with export data.

Examples

## Not run: 
comex_export(
  start_period = "2023-01",
  end_period = "2023-12",
  details = "country"
)

## End(Not run)

Get values for a specific filter

Description

Returns the possible values for a given filter name.

Usage

comex_filter_values(filter, type = "general", language = "en", verbose = FALSE)

Arguments

Value

A data.frame with filter values.

Examples

## Not run: 
comex_filter_values("country")
comex_filter_values("state", type = "city")
comex_filter_values("economicBlock")

## End(Not run)

Get available filters

Description

Returns the list of filter types available for API queries.

Usage

comex_filters(type = "general", language = "en", verbose = FALSE)

Arguments

Value

A data.frame with available filters.

Examples

## Not run: 
comex_filters()
comex_filters("city")
comex_filters("historical")

## End(Not run)

Query historical foreign trade data (1989-1996)

Description

Query the historical data endpoint of the ComexStat API to retrieve Brazilian export and import data from 1989 to 1996, before the SISCOMEX system was implemented. Historical data uses the NBM (Brazilian Nomenclature of Goods) classification.

Usage

comex_historical(
  flow = "export",
  start_period,
  end_period,
  details = NULL,
  filters = NULL,
  month_detail = FALSE,
  metric_fob = TRUE,
  metric_kg = TRUE,
  metric_statistic = FALSE,
  metric_freight = FALSE,
  metric_insurance = FALSE,
  metric_cif = FALSE,
  language = "en",
  verbose = TRUE
)

Arguments

Details

Historical data differs from general data:

• Available period: 1989 to 1996 only

• Limited details: "country", "state", "ncm"

• Product classification is NBM (not NCM)

• All six metrics are available (FOB, KG, Statistic, Freight, Insurance, CIF)

Value

A data.frame (or tibble) with query results.

Examples

## Not run: 
# Historical exports 1995-1996 by country
comex_historical(
  flow = "export",
  start_period = "1995-01",
  end_period = "1996-12",
  details = "country"
)

# Historical imports with CIF value
comex_historical(
  flow = "import",
  start_period = "1990-01",
  end_period = "1992-12",
  details = c("ncm", "country"),
  metric_cif = TRUE
)

## End(Not run)

Get Harmonized System (HS) tables

Description

Returns Harmonized System classification tables. The HS is an international product nomenclature developed by the World Customs Organization (WCO).

Usage

comex_hs(
  language = "en",
  add = NULL,
  page = NULL,
  per_page = NULL,
  verbose = FALSE
)

Arguments

Details

The Harmonized System is organized hierarchically:

• Section: 21 sections (broadest grouping)

• Chapter (HS2): ~97 chapters (2 digits)

• Heading (HS4): 4 digits

• Subheading (HS6): 6 digits (most detailed)

The NCM adds 2 more digits to the HS6 code.

Value

A data.frame with HS codes and descriptions.

Examples

## Not run: 
# All HS classifications
comex_hs()

# With related NCM codes
comex_hs(add = "ncm", per_page = 10)

## End(Not run)

Query imports

Description

Shortcut for comex_query() with flow = "import".

Usage

comex_import(
  start_period,
  end_period,
  details = NULL,
  filters = NULL,
  month_detail = FALSE,
  metric_fob = TRUE,
  metric_kg = TRUE,
  metric_statistic = FALSE,
  metric_freight = FALSE,
  metric_insurance = FALSE,
  metric_cif = FALSE,
  language = "en",
  verbose = TRUE
)

Arguments

Value

A data.frame (or tibble) with import data.

Examples

## Not run: 
comex_import(
  start_period = "2023-01",
  end_period = "2023-12",
  details = "country",
  metric_cif = TRUE
)

## End(Not run)

Get ISIC (International Standard Industrial Classification) table

Description

Queries the ⁠/tables/product-categories⁠ endpoint to retrieve ISIC classification data. ISIC is an international classification of economic activities developed by the United Nations.

Usage

comex_isic(
  language = "en",
  search = NULL,
  add = NULL,
  page = NULL,
  per_page = NULL,
  verbose = FALSE
)

Arguments

Value

A data.frame with classification codes and descriptions.

Note

The OpenAPI specification does not define a dedicated ISIC table endpoint. ISIC codes are available as detail/grouping fields in trade queries (e.g. "isic_section", "isic_division"). This convenience function queries ⁠/tables/product-categories⁠, which may return ISIC data alongside CUCI/SITC classifications. You can also look up ISIC values using comex_filter_values() with filter names like "isicSection".

Examples

## Not run: 
# Browse product categories (includes ISIC)
comex_isic()

# Alternatively, look up ISIC values via filters:
comex_filter_values("isicSection")

## End(Not run)

Get last data update date

Description

Returns the date of the last data update in the API.

Usage

comex_last_update(type = "general", verbose = FALSE)

Arguments

Value

A list with last update information.

Examples

## Not run: 
comex_last_update()
comex_last_update("city")
comex_last_update("historical")

## End(Not run)

Get available metrics

Description

Returns the list of metrics (values) available for API queries.

Usage

comex_metrics(type = "general", language = "en", verbose = FALSE)

Arguments

Value

A data.frame with available metrics and their descriptions.

Examples

## Not run: 
comex_metrics()
comex_metrics("city")
comex_metrics("historical")

## End(Not run)

Get NBM (Brazilian Nomenclature of Goods) table

Description

Returns the NBM codes table with descriptions. NBM was the nomenclature used in Brazil before NCM adoption and is used only for historical data (1989-1996).

Usage

comex_nbm(
  language = "en",
  search = NULL,
  add = NULL,
  page = NULL,
  per_page = NULL,
  verbose = FALSE
)

Arguments

Value

A data.frame with NBM codes and descriptions.

Examples

## Not run: 
comex_nbm()
comex_nbm(search = "encomendas", per_page = 5)
comex_nbm(add = "ncm")

## End(Not run)

Get NBM code details

Description

Returns details for a specific NBM code.

Usage

comex_nbm_detail(nbm_code, verbose = FALSE)

Arguments

Value

A list with NBM details.

Examples

## Not run: 
comex_nbm_detail("2924101100")

## End(Not run)

Get NCM (Mercosur Common Nomenclature) table

Description

Returns the NCM codes table with descriptions. NCM is the product classification used by Mercosur countries, based on the Harmonized System (HS) with 8 digits.

Usage

comex_ncm(
  language = "en",
  search = NULL,
  add = NULL,
  page = NULL,
  per_page = NULL,
  verbose = FALSE
)

Arguments

Value

A data.frame with NCM codes and descriptions.

Examples

## Not run: 
ncm <- comex_ncm()
comex_ncm(search = "animal", per_page = 10)
comex_ncm(add = "cuci")

## End(Not run)

Get NCM code details

Description

Returns details for a specific NCM code, including product description and its HS classification hierarchy.

Usage

comex_ncm_detail(ncm_code, verbose = FALSE)

Arguments

Value

A list with NCM details.

Examples

## Not run: 
comex_ncm_detail("02042200")

## End(Not run)

Query general foreign trade data

Description

Query the main ComexStat API endpoint to retrieve Brazilian export and import data. Supports filtering and grouping by multiple classifications such as NCM, Harmonized System, countries, states, etc.

Data is available monthly from 1997 to the most recent complete month.

Usage

comex_query(
  flow = "export",
  start_period,
  end_period,
  details = NULL,
  filters = NULL,
  month_detail = FALSE,
  metric_fob = TRUE,
  metric_kg = TRUE,
  metric_statistic = FALSE,
  metric_freight = FALSE,
  metric_insurance = FALSE,
  metric_cif = FALSE,
  language = "en",
  verbose = TRUE
)

Arguments

Value

A data.frame (or tibble if available) with query results.

Examples

## Not run: 
# Brazilian exports in 2023, by country
comex_query(
  flow = "export",
  start_period = "2023-01",
  end_period = "2023-12",
  details = "country"
)

# Imports 2023 by NCM + country, filtered by specific countries
comex_query(
  flow = "import",
  start_period = "2023-01",
  end_period = "2023-12",
  details = c("ncm", "country"),
  filters = list(country = c(160, 249)),
  month_detail = TRUE,
  metric_cif = TRUE
)

## End(Not run)

Query city-level foreign trade data

Description

Query the city endpoint of the ComexStat API. City-level data is more aggregated than general data, with fewer available details and metrics.

City information is based on the declarant of exports/imports, not the producer or buyer.

Usage

comex_query_city(
  flow = "export",
  start_period,
  end_period,
  details = NULL,
  filters = NULL,
  month_detail = FALSE,
  metric_fob = TRUE,
  metric_kg = TRUE,
  metric_statistic = FALSE,
  language = "en",
  verbose = TRUE
)

Arguments

Details

City-level data differs from general data:

• Full NCM is not available (use HS6/SH4/SH2)

• Classifications like CGCE, SITC, and ISIC are not available

• Only FOB, KG, and Statistical quantity metrics are available

• Freight, Insurance, and CIF metrics are not available

Value

A data.frame (or tibble) with query results.

Examples

## Not run: 
# Exports from Pernambuco in 2023
comex_query_city(
  flow = "export",
  start_period = "2023-01",
  end_period = "2023-12",
  details = c("country", "state"),
  filters = list(state = 26)
)

## End(Not run)

Get SITC/CUCI (Standard International Trade Classification) table

Description

Returns the CUCI (Classificacao Uniforme para o Comercio Internacional) table from the ⁠/tables/product-categories⁠ endpoint. CUCI is the Portuguese name for SITC (Standard International Trade Classification).

Usage

comex_sitc(
  language = "en",
  search = NULL,
  add = NULL,
  page = NULL,
  per_page = NULL,
  verbose = FALSE
)

Arguments

Value

A data.frame with CUCI/SITC codes and descriptions.

Examples

## Not run: 
# All CUCI/SITC classifications
comex_sitc()

# Search for products
comex_sitc(search = "carne")

## End(Not run)

Get state details

Description

Returns details for a specific Brazilian state.

Usage

comex_state_detail(uf_id, verbose = FALSE)

Arguments

Value

A list with state details.

Examples

## Not run: 
comex_state_detail(26)

## End(Not run)

Get Brazilian states (UF) table

Description

Returns the Brazilian states table with codes and names.

Usage

comex_states(verbose = FALSE)

Arguments

Value

A data.frame with state codes and names.

Examples

## Not run: 
comex_states()

## End(Not run)

Get transport mode details

Description

Returns details for a specific transport mode.

Usage

comex_transport_mode_detail(mode_id, verbose = FALSE)

Arguments

Value

A list with transport mode details.

Examples

## Not run: 
comex_transport_mode_detail(5)

## End(Not run)

Get transport modes table

Description

Returns the transport modes table with codes and names.

Usage

comex_transport_modes(verbose = FALSE)

Arguments

Value

A data.frame with transport mode codes and names.

Examples

## Not run: 
comex_transport_modes()

## End(Not run)