| Title: | Client for the Brazilian Foreign Trade Statistics API ('ComexStat') |
|---|---|
| Description: | Interface to the 'ComexStat' API <https://comexstat.mdic.gov.br/> from the Brazilian Ministry of Development, Industry, Trade and Services (MDIC). Provides access to detailed export and import data, including general trade statistics (1997-present), city-level data, historical data (1989-1996), and auxiliary tables with product codes (NCM - Nomenclatura Comum do Mercosul, NBM - Nomenclatura Brasileira de Mercadorias, HS - Harmonized System), countries, economic classifications (CGCE - Classificacao por Grandes Categorias Economicas, SITC - Standard International Trade Classification, ISIC - International Standard Industrial Classification), and other categories. Uses only 'httr2' for HTTP requests and 'cli' for console messages. |
| Authors: | Andre Leite [aut, cre], Marcos Wasilew [aut], Hugo Vasconcelos [aut], Carlos Amorin [aut], Diogo Bezerra [aut] |
| Maintainer: | Andre Leite <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.3.1 |
| Built: | 2026-06-02 14:53:49 UTC |
| Source: | https://github.com/strategicprojects/comexr |
Returns the first and last years available for queries in the API.
comex_available_years(type = "general", verbose = FALSE)comex_available_years(type = "general", verbose = FALSE)
type |
Data type: |
verbose |
Logical. Show progress messages. Default: |
A list with min and max year values.
## Not run: comex_available_years() comex_available_years("city") comex_available_years("historical") ## End(Not run)## Not run: comex_available_years() comex_available_years("city") comex_available_years("historical") ## End(Not run)
Returns the economic blocs table with codes and names. Economic blocs represent trade agreements between countries and regions.
comex_blocs(language = "en", search = NULL, add = NULL, verbose = FALSE)comex_blocs(language = "en", search = NULL, add = NULL, verbose = FALSE)
language |
Language: |
search |
Optional search term to filter results. |
add |
Optional related table to include (e.g. |
verbose |
Logical. Default: |
A data.frame with economic bloc codes and names.
## Not run: comex_blocs() comex_blocs(search = "mercosul") comex_blocs(add = "country") ## End(Not run)## Not run: comex_blocs() comex_blocs(search = "mercosul") comex_blocs(add = "country") ## End(Not run)
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).
comex_cgce( language = "en", search = NULL, add = NULL, page = NULL, per_page = NULL, verbose = FALSE )comex_cgce( language = "en", search = NULL, add = NULL, page = NULL, per_page = NULL, verbose = FALSE )
language |
Language: |
search |
Optional search term to filter results. |
add |
Optional related table to include (e.g. |
page |
Page number for pagination. Default: |
per_page |
Number of results per page. Default: |
verbose |
Logical. Show progress messages. Default: |
A data.frame with CGCE codes and descriptions.
## Not run: # All CGCE classifications comex_cgce() # Search within CGCE comex_cgce(search = "110") ## End(Not run)## Not run: # All CGCE classifications comex_cgce() # Search within CGCE comex_cgce(search = "110") ## End(Not run)
Returns the Brazilian cities table with codes and names.
comex_cities(verbose = FALSE)comex_cities(verbose = FALSE)
verbose |
Logical. Default: |
A data.frame with city (IBGE) codes and names.
## Not run: comex_cities() ## End(Not run)## Not run: comex_cities() ## End(Not run)
Returns details for a specific Brazilian city.
comex_city_detail(city_id, verbose = FALSE)comex_city_detail(city_id, verbose = FALSE)
city_id |
IBGE city code (e.g. |
verbose |
Logical. Default: |
A list with city details.
## Not run: comex_city_detail(5300050) ## End(Not run)## Not run: comex_city_detail(5300050) ## End(Not run)
Returns the countries table with codes and names.
comex_countries(search = NULL, verbose = FALSE)comex_countries(search = NULL, verbose = FALSE)
search |
Optional search term to filter results (e.g. |
verbose |
Logical. Show progress messages. Default: |
A data.frame with country codes and names.
## Not run: comex_countries() comex_countries(search = "bra") ## End(Not run)## Not run: comex_countries() comex_countries(search = "bra") ## End(Not run)
Returns details for a specific country by its code.
comex_country_detail(id, verbose = FALSE)comex_country_detail(id, verbose = FALSE)
id |
Country code (e.g. |
verbose |
Logical. Default: |
A list with country details.
## Not run: comex_country_detail(105) ## End(Not run)## Not run: comex_country_detail(105) ## End(Not run)
Returns details for a specific customs unit (URF).
comex_customs_unit_detail(urf_id, verbose = FALSE)comex_customs_unit_detail(urf_id, verbose = FALSE)
urf_id |
Customs unit code (e.g. |
verbose |
Logical. Default: |
A list with customs unit details.
## Not run: comex_customs_unit_detail(8110000) ## End(Not run)## Not run: comex_customs_unit_detail(8110000) ## End(Not run)
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.
comex_customs_units(verbose = FALSE)comex_customs_units(verbose = FALSE)
verbose |
Logical. Default: |
A data.frame with customs unit codes and names.
## Not run: comex_customs_units() ## End(Not run)## Not run: comex_customs_units() ## End(Not run)
Returns the list of detail fields that can be used to group query results.
comex_details(type = "general", language = "en", verbose = FALSE)comex_details(type = "general", language = "en", verbose = FALSE)
type |
Data type: |
language |
Language: |
verbose |
Logical. Show progress messages. Default: |
A data.frame with available details.
## Not run: comex_details() comex_details("city") comex_details("historical") ## End(Not run)## Not run: comex_details() comex_details("city") comex_details("historical") ## End(Not run)
Shortcut for comex_query() with flow = "export".
comex_export( start_period, end_period, details = NULL, filters = NULL, month_detail = TRUE, metric_fob = TRUE, metric_kg = TRUE, metric_statistic = FALSE, metric_freight = FALSE, metric_insurance = FALSE, metric_cif = FALSE, language = "en", verbose = TRUE )comex_export( start_period, end_period, details = NULL, filters = NULL, month_detail = TRUE, metric_fob = TRUE, metric_kg = TRUE, metric_statistic = FALSE, metric_freight = FALSE, metric_insurance = FALSE, metric_cif = FALSE, language = "en", verbose = TRUE )
start_period |
Start period in |
end_period |
End period in |
details |
Character vector of detail/grouping fields. The names below
are user-friendly aliases; the package translates each to the underlying
API name. The API names returned by Geographic: Products: CGCE (BEC): SITC/CUCI: ISIC: |
filters |
Named list of filters. Names should match detail field names.
Example: |
month_detail |
Logical. If |
metric_fob |
Logical. Include FOB value (US$). Default: |
metric_kg |
Logical. Include net weight (kg). Default: |
metric_statistic |
Logical. Include statistical quantity. Default: |
metric_freight |
Logical. Include freight value (US$, imports only).
Default: |
metric_insurance |
Logical. Include insurance value (US$, imports only).
Default: |
metric_cif |
Logical. Include CIF value (US$, imports only).
Default: |
language |
Response language: |
verbose |
Logical. Show progress messages. Default: |
A data.frame (or tibble) with export data.
## Not run: comex_export( start_period = "2023-01", end_period = "2023-12", details = "country" ) ## End(Not run)## Not run: comex_export( start_period = "2023-01", end_period = "2023-12", details = "country" ) ## End(Not run)
Returns the possible values for a given filter name. The filter
argument is passed verbatim to the API and is case-sensitive — use
the exact name returned by comex_filters() (for example
"economicBlock", "BECLevel1", "SITCSection", "ISICSection",
"subHeading", "heading", "chapter").
comex_filter_values(filter, type = "general", language = "en", verbose = FALSE)comex_filter_values(filter, type = "general", language = "en", verbose = FALSE)
filter |
Filter name as returned by |
type |
Data type: |
language |
Language: |
verbose |
Logical. Show progress messages. Default: |
A data.frame with filter values.
## Not run: comex_filter_values("country") comex_filter_values("state", type = "city") comex_filter_values("economicBlock") comex_filter_values("BECLevel1") comex_filter_values("ISICSection") ## End(Not run)## Not run: comex_filter_values("country") comex_filter_values("state", type = "city") comex_filter_values("economicBlock") comex_filter_values("BECLevel1") comex_filter_values("ISICSection") ## End(Not run)
Returns the list of filter types available for API queries.
comex_filters(type = "general", language = "en", verbose = FALSE)comex_filters(type = "general", language = "en", verbose = FALSE)
type |
Data type: |
language |
Language: |
verbose |
Logical. Show progress messages. Default: |
A data.frame with available filters.
## Not run: comex_filters() comex_filters("city") comex_filters("historical") ## End(Not run)## Not run: comex_filters() comex_filters("city") comex_filters("historical") ## End(Not run)
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.
comex_historical( flow = "export", start_period, end_period, details = NULL, filters = NULL, month_detail = TRUE, metric_fob = TRUE, metric_kg = TRUE, language = "en", verbose = TRUE )comex_historical( flow = "export", start_period, end_period, details = NULL, filters = NULL, month_detail = TRUE, metric_fob = TRUE, metric_kg = TRUE, language = "en", verbose = TRUE )
flow |
Trade flow: |
start_period |
Start period in |
end_period |
End period in |
details |
Character vector of detail/grouping fields. The historical
endpoint supports only: |
filters |
Named list of filters. Accepts the same names as |
month_detail |
Logical. If |
metric_fob |
Logical. Include FOB value (US$). Default: |
metric_kg |
Logical. Include net weight (kg). Default: |
language |
Response language: |
verbose |
Logical. Show progress messages. Default: |
Historical data differs from general data:
Available period: 1989 to 1996 only
Limited details: "country", "state", "nbm"
Product classification is NBM (not NCM)
Only FOB and KG metrics are available (no statistic, freight, insurance, or CIF)
A data.frame (or tibble) with query results.
## Not run: # Historical exports 1995-1996 by country comex_historical( flow = "export", start_period = "1995-01", end_period = "1996-12", details = "country" ) ## End(Not run)## Not run: # Historical exports 1995-1996 by country comex_historical( flow = "export", start_period = "1995-01", end_period = "1996-12", details = "country" ) ## End(Not run)
Returns Harmonized System classification tables. The HS is an international product nomenclature developed by the World Customs Organization (WCO).
comex_hs( language = "en", add = NULL, page = NULL, per_page = NULL, verbose = FALSE )comex_hs( language = "en", add = NULL, page = NULL, per_page = NULL, verbose = FALSE )
language |
Language: |
add |
Optional related table to include (e.g. |
page |
Page number for pagination. Default: |
per_page |
Number of results per page. Default: |
verbose |
Logical. Default: |
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.
A data.frame with HS codes and descriptions.
## Not run: # All HS classifications comex_hs() # With related NCM codes comex_hs(add = "ncm", per_page = 10) ## End(Not run)## Not run: # All HS classifications comex_hs() # With related NCM codes comex_hs(add = "ncm", per_page = 10) ## End(Not run)
Shortcut for comex_query() with flow = "import".
comex_import( start_period, end_period, details = NULL, filters = NULL, month_detail = TRUE, metric_fob = TRUE, metric_kg = TRUE, metric_statistic = FALSE, metric_freight = FALSE, metric_insurance = FALSE, metric_cif = FALSE, language = "en", verbose = TRUE )comex_import( start_period, end_period, details = NULL, filters = NULL, month_detail = TRUE, metric_fob = TRUE, metric_kg = TRUE, metric_statistic = FALSE, metric_freight = FALSE, metric_insurance = FALSE, metric_cif = FALSE, language = "en", verbose = TRUE )
start_period |
Start period in |
end_period |
End period in |
details |
Character vector of detail/grouping fields. The names below
are user-friendly aliases; the package translates each to the underlying
API name. The API names returned by Geographic: Products: CGCE (BEC): SITC/CUCI: ISIC: |
filters |
Named list of filters. Names should match detail field names.
Example: |
month_detail |
Logical. If |
metric_fob |
Logical. Include FOB value (US$). Default: |
metric_kg |
Logical. Include net weight (kg). Default: |
metric_statistic |
Logical. Include statistical quantity. Default: |
metric_freight |
Logical. Include freight value (US$, imports only).
Default: |
metric_insurance |
Logical. Include insurance value (US$, imports only).
Default: |
metric_cif |
Logical. Include CIF value (US$, imports only).
Default: |
language |
Response language: |
verbose |
Logical. Show progress messages. Default: |
A data.frame (or tibble) with import data.
## Not run: comex_import( start_period = "2023-01", end_period = "2023-12", details = "country", metric_cif = TRUE ) ## End(Not run)## Not run: comex_import( start_period = "2023-01", end_period = "2023-12", details = "country", metric_cif = TRUE ) ## End(Not run)
Retrieves ISIC classification values at a chosen hierarchical level by
calling the corresponding /general/filters/{filter} endpoint, which
is the only place the ComexStat API exposes ISIC codes (there is no
/tables/isic endpoint).
comex_isic( level = c("section", "division", "group", "class"), language = "en", verbose = FALSE )comex_isic( level = c("section", "division", "group", "class"), language = "en", verbose = FALSE )
level |
Hierarchical level. One of |
language |
Language: |
verbose |
Logical. Show progress messages. Default: |
ISIC is the international classification of economic activities maintained by the United Nations.
A data.frame with ISIC codes and descriptions for the given level.
## Not run: comex_isic("section") comex_isic("division", language = "pt") ## End(Not run)## Not run: comex_isic("section") comex_isic("division", language = "pt") ## End(Not run)
Returns the date of the last data update in the API.
comex_last_update(type = "general", verbose = FALSE)comex_last_update(type = "general", verbose = FALSE)
type |
Data type: |
verbose |
Logical. Show progress messages. Default: |
A list with last update information.
## Not run: comex_last_update() comex_last_update("city") comex_last_update("historical") ## End(Not run)## Not run: comex_last_update() comex_last_update("city") comex_last_update("historical") ## End(Not run)
Returns the list of metrics (values) available for API queries.
comex_metrics(type = "general", language = "en", verbose = FALSE)comex_metrics(type = "general", language = "en", verbose = FALSE)
type |
Data type: |
language |
Language: |
verbose |
Logical. Show progress messages. Default: |
A data.frame with available metrics and their descriptions.
## Not run: comex_metrics() comex_metrics("city") comex_metrics("historical") ## End(Not run)## Not run: comex_metrics() comex_metrics("city") comex_metrics("historical") ## End(Not run)
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).
comex_nbm( language = "en", search = NULL, add = NULL, page = NULL, per_page = NULL, verbose = FALSE )comex_nbm( language = "en", search = NULL, add = NULL, page = NULL, per_page = NULL, verbose = FALSE )
language |
Language: |
search |
Optional search term to filter results. |
add |
Optional related table to include (e.g. |
page |
Page number for pagination. Default: |
per_page |
Number of results per page. Default: |
verbose |
Logical. Default: |
A data.frame with NBM codes and descriptions.
## Not run: comex_nbm() comex_nbm(search = "encomendas", per_page = 5) comex_nbm(add = "ncm") ## End(Not run)## Not run: comex_nbm() comex_nbm(search = "encomendas", per_page = 5) comex_nbm(add = "ncm") ## End(Not run)
Returns details for a specific NBM code.
comex_nbm_detail(nbm_code, verbose = FALSE)comex_nbm_detail(nbm_code, verbose = FALSE)
nbm_code |
NBM code (e.g. |
verbose |
Logical. Default: |
A list with NBM details.
## Not run: comex_nbm_detail("2924101100") ## End(Not run)## Not run: comex_nbm_detail("2924101100") ## End(Not run)
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.
comex_ncm( language = "en", search = NULL, add = NULL, page = NULL, per_page = NULL, verbose = FALSE )comex_ncm( language = "en", search = NULL, add = NULL, page = NULL, per_page = NULL, verbose = FALSE )
language |
Language: |
search |
Optional search term to filter results (e.g. |
add |
Optional related table to include in results. Options:
|
page |
Page number for pagination. Default: |
per_page |
Number of results per page. Default: |
verbose |
Logical. Show progress messages. Default: |
A data.frame with NCM codes and descriptions.
## Not run: ncm <- comex_ncm() comex_ncm(search = "animal", per_page = 10) comex_ncm(add = "cuci") ## End(Not run)## Not run: ncm <- comex_ncm() comex_ncm(search = "animal", per_page = 10) comex_ncm(add = "cuci") ## End(Not run)
Returns details for a specific NCM code, including product description and its HS classification hierarchy.
comex_ncm_detail(ncm_code, verbose = FALSE)comex_ncm_detail(ncm_code, verbose = FALSE)
ncm_code |
NCM code (8 digits, as character, e.g. |
verbose |
Logical. Default: |
A list with NCM details.
## Not run: comex_ncm_detail("02042200") ## End(Not run)## Not run: comex_ncm_detail("02042200") ## End(Not run)
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.
comex_query( flow = "export", start_period, end_period, details = NULL, filters = NULL, month_detail = TRUE, metric_fob = TRUE, metric_kg = TRUE, metric_statistic = FALSE, metric_freight = FALSE, metric_insurance = FALSE, metric_cif = FALSE, language = "en", verbose = TRUE )comex_query( flow = "export", start_period, end_period, details = NULL, filters = NULL, month_detail = TRUE, metric_fob = TRUE, metric_kg = TRUE, metric_statistic = FALSE, metric_freight = FALSE, metric_insurance = FALSE, metric_cif = FALSE, language = "en", verbose = TRUE )
flow |
Trade flow: |
start_period |
Start period in |
end_period |
End period in |
details |
Character vector of detail/grouping fields. The names below
are user-friendly aliases; the package translates each to the underlying
API name. The API names returned by Geographic: Products: CGCE (BEC): SITC/CUCI: ISIC: |
filters |
Named list of filters. Names should match detail field names.
Example: |
month_detail |
Logical. If |
metric_fob |
Logical. Include FOB value (US$). Default: |
metric_kg |
Logical. Include net weight (kg). Default: |
metric_statistic |
Logical. Include statistical quantity. Default: |
metric_freight |
Logical. Include freight value (US$, imports only).
Default: |
metric_insurance |
Logical. Include insurance value (US$, imports only).
Default: |
metric_cif |
Logical. Include CIF value (US$, imports only).
Default: |
language |
Response language: |
verbose |
Logical. Show progress messages. Default: |
A data.frame (or tibble if available) with query results.
## 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)## 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 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.
comex_query_city( flow = "export", start_period, end_period, details = NULL, filters = NULL, month_detail = TRUE, metric_fob = TRUE, metric_kg = TRUE, language = "en", verbose = TRUE )comex_query_city( flow = "export", start_period, end_period, details = NULL, filters = NULL, month_detail = TRUE, metric_fob = TRUE, metric_kg = TRUE, language = "en", verbose = TRUE )
flow |
Trade flow: |
start_period |
Start period in |
end_period |
End period in |
details |
Character vector of detail/grouping fields. The city endpoint accepts only a subset of the general-endpoint fields: Geographic: Products: |
filters |
Named list of filters. Accepts the same names as |
month_detail |
Logical. If |
metric_fob |
Logical. Include FOB value (US$). Default: |
metric_kg |
Logical. Include net weight (kg). Default: |
language |
Response language: |
verbose |
Logical. Show progress messages. Default: |
City-level data differs from general data:
Full NCM is not available; product detail goes only down to HS4 (heading). HS6 (subheading) is also not available.
Classifications like CGCE, SITC, and ISIC are not available
Transport mode (via) and customs unit (urf) are not available
Only FOB and KG metrics are supported; statistical quantity, freight, insurance, and CIF metrics are not available
A data.frame (or tibble) with query results.
## 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)## 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)
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).
comex_sitc( language = "en", search = NULL, add = NULL, page = NULL, per_page = NULL, verbose = FALSE )comex_sitc( language = "en", search = NULL, add = NULL, page = NULL, per_page = NULL, verbose = FALSE )
language |
Language: |
search |
Optional search term to filter results. |
add |
Optional related table to include (e.g. |
page |
Page number for pagination. Default: |
per_page |
Number of results per page. Default: |
verbose |
Logical. Show progress messages. Default: |
A data.frame with CUCI/SITC codes and descriptions.
## Not run: # All CUCI/SITC classifications comex_sitc() # Search for products comex_sitc(search = "carne") ## End(Not run)## Not run: # All CUCI/SITC classifications comex_sitc() # Search for products comex_sitc(search = "carne") ## End(Not run)
Returns details for a specific Brazilian state.
comex_state_detail(uf_id, verbose = FALSE)comex_state_detail(uf_id, verbose = FALSE)
uf_id |
State code (e.g. |
verbose |
Logical. Default: |
A list with state details.
## Not run: comex_state_detail(26) ## End(Not run)## Not run: comex_state_detail(26) ## End(Not run)
Returns the Brazilian states table with codes and names.
comex_states(verbose = FALSE)comex_states(verbose = FALSE)
verbose |
Logical. Default: |
A data.frame with state codes and names.
## Not run: comex_states() ## End(Not run)## Not run: comex_states() ## End(Not run)
Returns details for a specific transport mode.
comex_transport_mode_detail(mode_id, verbose = FALSE)comex_transport_mode_detail(mode_id, verbose = FALSE)
mode_id |
Transport mode code (e.g. |
verbose |
Logical. Default: |
A list with transport mode details.
## Not run: comex_transport_mode_detail(5) ## End(Not run)## Not run: comex_transport_mode_detail(5) ## End(Not run)
Returns the transport modes table with codes and names.
comex_transport_modes(verbose = FALSE)comex_transport_modes(verbose = FALSE)
verbose |
Logical. Default: |
A data.frame with transport mode codes and names.
## Not run: comex_transport_modes() ## End(Not run)## Not run: comex_transport_modes() ## End(Not run)