### Example of comex_transport_modes

Source: https://strategicprojects.github.io/comexr/reference/comex_transport_modes.html

Example demonstrating how to call the function.

```R
if (FALSE) { # \dontrun{
comex_transport_modes()
} # }
```

--------------------------------

### Install comexr from GitHub

Source: https://strategicprojects.github.io/comexr/index.html

Use the remotes package to install the development version of comexr.

```R
# Install from GitHub
# install.packages("remotes")
remotes::install_github("StrategicProjects/comexr")
```

--------------------------------

### Example of comex_states

Source: https://strategicprojects.github.io/comexr/reference/comex_states.html

Basic execution example for retrieving the states table.

```R
if (FALSE) { # \dontrun{
comex_states()
} # }
```

--------------------------------

### Example usage of comex_nbm_detail

Source: https://strategicprojects.github.io/comexr/reference/comex_nbm_detail.html

Example demonstrating how to call the function with a specific NBM code string.

```R
if (FALSE) { # \dontrun{
comex_nbm_detail("2924101100")
} # }
```

--------------------------------

### Example of comex_state_detail

Source: https://strategicprojects.github.io/comexr/reference/comex_state_detail.html

Example demonstrating how to call the function with a state ID.

```R
if (FALSE) { # \dontrun{
comex_state_detail(26)
} # }
```

--------------------------------

### Example usage of comex_ncm_detail

Source: https://strategicprojects.github.io/comexr/reference/comex_ncm_detail.html

Example demonstrating how to query details for a specific NCM code.

```R
if (FALSE) { # \dontrun{
comex_ncm_detail("02042200")
} # }
```

--------------------------------

### Examples of comex_last_update

Source: https://strategicprojects.github.io/comexr/reference/comex_last_update.html

Demonstrates how to call the function for different data types.

```R
if (FALSE) { # \dontrun{
comex_last_update()
comex_last_update("city")
comex_last_update("historical")
} # }
```

--------------------------------

### NBM function examples

Source: https://strategicprojects.github.io/comexr/reference/comex_nbm.html

Demonstrates basic usage, searching with pagination, and joining with NCM data.

```R
if (FALSE) { # \dontrun{
comex_nbm()
comex_nbm(search = "encomendas", per_page = 5)
comex_nbm(add = "ncm")
} # }
```

--------------------------------

### Examples of comex_available_years

Source: https://strategicprojects.github.io/comexr/reference/comex_available_years.html

Demonstrates how to call the function for different data types. Note that these examples are wrapped in a dontrun block.

```R
if (FALSE) { # \dontrun{
comex_available_years()
comex_available_years("city")
comex_available_years("historical")
} # }
```

--------------------------------

### comex_ncm Examples

Source: https://strategicprojects.github.io/comexr/reference/comex_ncm.html

Demonstrates basic function calls including default retrieval, filtered searches, and adding related classification tables.

```R
if (FALSE) { # \dontrun{
ncm <- comex_ncm()
comex_ncm(search = "animal", per_page = 10)
comex_ncm(add = "cuci")
} # }
```

--------------------------------

### Example usage of comex_details

Source: https://strategicprojects.github.io/comexr/reference/comex_details.html

Demonstrates how to call the function for different data types.

```R
if (FALSE) { # \dontrun{
comex_details()
comex_details("city")
comex_details("historical")
} # }
```

--------------------------------

### Install comex from GitHub

Source: https://strategicprojects.github.io/comexr/articles/getting-started.html

Use the remotes package to install the latest version of comex directly from the GitHub repository.

```R
# Install from GitHub:
remotes::install_github("StrategicProjects/comexr")
```

--------------------------------

### Query import data example

Source: https://strategicprojects.github.io/comexr/reference/comex_import.html

A basic example of how to call comex_import to retrieve import data by country with CIF metrics enabled.

```R
if (FALSE) { # \dontrun{
comex_import(
  start_period = "2023-01",
  end_period = "2023-12",
  details = "country",
  metric_cif = TRUE
)
} # }
```

--------------------------------

### Example usage of comex_city_detail

Source: https://strategicprojects.github.io/comexr/reference/comex_city_detail.html

Example of how to call the function with a specific IBGE city code.

```R
if (FALSE) { # \dontrun{
comex_city_detail(5300050)
} # }
```

--------------------------------

### Example usage of comex_customs_unit_detail

Source: https://strategicprojects.github.io/comexr/reference/comex_customs_unit_detail.html

Example demonstrating how to call the function with a specific customs unit ID.

```R
if (FALSE) { # \dontrun{
comex_customs_unit_detail(8110000)
} # }
```

--------------------------------

### Example usage of comex_filter_values

Source: https://strategicprojects.github.io/comexr/reference/comex_filter_values.html

Examples demonstrating how to retrieve values for different filter categories and data types.

```R
if (FALSE) { # \dontrun{
comex_filter_values("country")
comex_filter_values("state", type = "city")
comex_filter_values("economicBlock")
comex_filter_values("BECLevel1")
comex_filter_values("ISICSection")
} # }
```

--------------------------------

### Execute export query example

Source: https://strategicprojects.github.io/comexr/reference/comex_export.html

A basic example of how to call comex_export to retrieve export data grouped by country for a specific year.

```R
if (FALSE) { # \dontrun{
comex_export(
  start_period = "2023-01",
  end_period = "2023-12",
  details = "country"
)
} # }
```

--------------------------------

### Example usage of comex_cities

Source: https://strategicprojects.github.io/comexr/reference/comex_cities.html

Demonstrates how to call the function in an R environment.

```R
if (FALSE) { # \dontrun{
comex_cities()
} # }
```

--------------------------------

### Examples of comex_blocs usage

Source: https://strategicprojects.github.io/comexr/reference/comex_blocs.html

Demonstrates fetching all blocs, filtering by search term, and joining with country data.

```R
if (FALSE) { # \dontrun{
comex_blocs()
comex_blocs(search = "mercosul")
comex_blocs(add = "country")
} # }
```

--------------------------------

### comex_sitc Examples

Source: https://strategicprojects.github.io/comexr/reference/comex_sitc.html

Demonstrates how to retrieve all SITC classifications or filter results using a search term.

```R
if (FALSE) { # \dontrun{
# All CUCI/SITC classifications
comex_sitc()

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

--------------------------------

### Example usage of comex_transport_mode_detail

Source: https://strategicprojects.github.io/comexr/reference/comex_transport_mode_detail.html

Demonstrates how to call the function with a specific transport mode ID.

```R
if (FALSE) { # \dontrun{
comex_transport_mode_detail(5)
} # }
```

--------------------------------

### Examples of comex_query usage

Source: https://strategicprojects.github.io/comexr/reference/comex_query.html

Demonstrates how to query export data by country and import data with specific filters and metrics.

```R
if (FALSE) { # \dontrun{
# 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
)
} # }
```

--------------------------------

### Examples of HS classification queries

Source: https://strategicprojects.github.io/comexr/reference/comex_hs.html

Demonstrates basic usage and fetching data with additional NCM codes and pagination.

```R
if (FALSE) { # \dontrun{
# All HS classifications
comex_hs()

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

--------------------------------

### Examples of comex_cgce usage

Source: https://strategicprojects.github.io/comexr/reference/comex_cgce.html

Demonstrates how to retrieve all CGCE classifications or filter them using a search term.

```R
if (FALSE) { # \dontrun{
# All CGCE classifications
comex_cgce()

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

--------------------------------

### Querying city-level exports

Source: https://strategicprojects.github.io/comexr/reference/comex_query_city.html

Example demonstrating how to filter export data for a specific state over a defined time period.

```R
if (FALSE) { # \dontrun{
# 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)
)
} # }
```

--------------------------------

### Get detailed country information

Source: https://strategicprojects.github.io/comexr/articles/auxiliary-tables.html

Retrieves specific details for a country using its ID.

```R
comex_country_detail(105)
#> $id
#> [1] "105"
#> $country
#> [1] "Brasil"
#> $coPaisIson3
#> [1] "076"
#> $coPaisIsoa3
#> [1] "BRA"
```

--------------------------------

### Load the comex library

Source: https://strategicprojects.github.io/comexr/articles/getting-started.html

Initialize the package in your R session to begin querying trade data.

```R
library(comex)
```

--------------------------------

### Load comexr library

Source: https://strategicprojects.github.io/comexr/articles/state-trade-profile.html

Initializes the comexr package for use in the R environment.

```R
library(comexr)
```

--------------------------------

### Retrieve Transport Modes

Source: https://strategicprojects.github.io/comexr/articles/auxiliary-tables.html

List available transport modes or get details for a specific mode using its string code.

```R
comex_transport_modes()
```

```R
comex_transport_mode_detail("01")
```

--------------------------------

### comex_import()

Source: https://strategicprojects.github.io/comexr/reference/index.html

Query imports.

```APIDOC
## comex_import()

### Description
Query imports.
```

--------------------------------

### Initialize city trade query parameters

Source: https://strategicprojects.github.io/comexr/articles/city-profile.html

Define the target municipality IBGE code and the time period for the trade data analysis.

```R
library(comexr)

city_code <- "2611606"  # Recife - PE (IBGE)
year_from <- "2024-01"
year_to   <- "2024-12"
```

--------------------------------

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

Source: https://strategicprojects.github.io/comexr/reference/comex_sitc.html

Retrieves the CUCI/SITC table from the product categories endpoint.

```APIDOC
## comex_sitc

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

### Arguments
- **language** (string) - Optional - Language: "pt", "en", or "es". Default: "en".
- **search** (string) - Optional - Optional search term to filter results.
- **add** (string) - Optional - Optional related table to include (e.g. "ncm").
- **page** (integer) - Optional - Page number for pagination. Default: NULL.
- **per_page** (integer) - Optional - Number of results per page. Default: NULL.
- **verbose** (boolean) - Optional - Logical. Show progress messages. Default: FALSE.

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

### Examples
```r
# All CUCI/SITC classifications
comex_sitc()

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

--------------------------------

### Discover API Options and Metadata

Source: https://strategicprojects.github.io/comexr/index.html

Explore available grouping fields, filters, and auxiliary tables like countries and economic blocs.

```R
# What grouping fields are available?
comex_details("general")

# What filters can I use?
comex_filters("general")

# Look up country codes
countries <- comex_countries()
countries[grepl("China", countries$text, ignore.case = TRUE), ]

# Economic blocs in Portuguese
comex_blocs(language = "pt")
```

--------------------------------

### Paginate large product tables

Source: https://strategicprojects.github.io/comexr/articles/auxiliary-tables.html

Uses a repeat loop to fetch large datasets in batches using page and per_page parameters.

```R
# 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
```

--------------------------------

### Calculate monthly trade balance and visualize

Source: https://strategicprojects.github.io/comexr/articles/state-trade-profile.html

Aggregate trade data by date and flow, calculate the balance, and generate a base-R plot.

```R
monthly <- aggregate(metricFOB ~ date + flow, data = pe, FUN = sum)
monthly_wide <- reshape(monthly, idvar = "date", timevar = "flow",
                        direction = "wide")
names(monthly_wide) <- c("date", "exports", "imports")
monthly_wide$balance <- monthly_wide$exports - monthly_wide$imports
monthly_wide

# Base-R plot
with(monthly_wide, {
  plot(date, exports / 1e6, type = "b", pch = 19, col = "steelblue",
       ylim = range(c(exports, imports), na.rm = TRUE) / 1e6,
       xlab = "Month", ylab = "US$ millions",
       main = "Pernambuco: exports vs imports, 2026")
  lines(date, imports / 1e6, type = "b", pch = 17, col = "tomato")
  legend("topleft", legend = c("Exports", "Imports"),
         col = c("steelblue", "tomato"), pch = c(19, 17), bty = "n")
})
```

--------------------------------

### Usage of comex_nbm_detail

Source: https://strategicprojects.github.io/comexr/reference/comex_nbm_detail.html

Basic function call syntax for retrieving NBM details.

```R
comex_nbm_detail(nbm_code, verbose = FALSE)
```

--------------------------------

### comex_import(start_period, end_period, ...)

Source: https://strategicprojects.github.io/comexr/reference/comex_import.html

Queries import trade data for a specified period with optional grouping, filtering, and metric selection.

```APIDOC
## comex_import

### Description
Shortcut for `comex_query()` with `flow = "import"`. Retrieves import trade data as a data.frame or tibble.

### Usage
```r
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
)
```

### Parameters
- **start_period** (string) - Required - Start period in "YYYY-MM" format.
- **end_period** (string) - Required - End period in "YYYY-MM" format.
- **details** (character vector) - Optional - Fields for grouping/detail (e.g., "country", "ncm", "state").
- **filters** (list) - Optional - Named list of filters matching detail field names.
- **month_detail** (logical) - Optional - Break down results by month. Default: TRUE.
- **metric_fob** (logical) - Optional - Include FOB value (US$). Default: TRUE.
- **metric_kg** (logical) - Optional - Include net weight (kg). Default: TRUE.
- **metric_statistic** (logical) - Optional - Include statistical quantity. Default: FALSE.
- **metric_freight** (logical) - Optional - Include freight value (US$). Default: FALSE.
- **metric_insurance** (logical) - Optional - Include insurance value (US$). Default: FALSE.
- **metric_cif** (logical) - Optional - Include CIF value (US$). Default: FALSE.
- **language** (string) - Optional - Response language: "pt", "en", or "es". Default: "en".
- **verbose** (logical) - Optional - Show progress messages. Default: TRUE.

### Returns
- **data.frame/tibble** - A data frame containing the requested import trade data.
```

--------------------------------

### Visualize monthly exports in R

Source: https://strategicprojects.github.io/comexr/articles/city-profile.html

Prepare date and numeric columns before plotting monthly export trends.

```R
exports_monthly$date <- as.Date(
  sprintf("%s-%s-01", exports_monthly$year, exports_monthly$monthNumber)
)
exports_monthly$fob_musd <- as.numeric(exports_monthly$metricFOB) / 1e6

plot(
  exports_monthly$date, exports_monthly$fob_musd,
  type = "b", pch = 19,
  xlab = "Month", ylab = "Exports (US$ millions)",
  main = sprintf("Recife - PE exports, %s to %s", year_from, year_to)
)
```

--------------------------------

### Execute generic trade queries

Source: https://strategicprojects.github.io/comexr/articles/querying-trade-data.html

Use comex_query for full control over flow, metrics, and advanced query options.

```R
result <- comex_query(
  flow         = "import",
  start_period = "2023-01",
  end_period   = "2023-12",
  details      = c("country", "ncm"),
  filters      = list(country = c(160)),
  month_detail = FALSE,
  metric_fob   = TRUE,
  metric_kg    = TRUE,
  metric_statistic = TRUE,
  metric_freight   = TRUE,
  metric_insurance = TRUE,
  metric_cif       = TRUE,
  language     = "en"
)
```

--------------------------------

### Configure SSL Verification

Source: https://strategicprojects.github.io/comexr/index.html

Disable SSL verification if the API's certificate chain is not recognized on your system.

```R
options(comex.ssl_verifypeer = FALSE)
```

--------------------------------

### comex_query_city(flow, start_period, end_period, details, filters, month_detail, metric_fob, metric_kg, language, verbose)

Source: https://strategicprojects.github.io/comexr/reference/comex_query_city.html

Queries the city endpoint of the ComexStat API. Note that city-level data is more aggregated than general data and has specific limitations regarding available metrics and product detail levels.

```APIDOC
## comex_query_city

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

### Arguments
- **flow** (string) - Required - Trade flow: "export" or "import".
- **start_period** (string) - Required - Start period in "YYYY-MM" format.
- **end_period** (string) - Required - End period in "YYYY-MM" format.
- **details** (vector) - Optional - Character vector of detail/grouping fields (e.g., "country", "bloc", "state", "city", "hs4", "hs2", "section").
- **filters** (list) - Optional - Named list of filters (e.g., list(city = "3550308", state = "26")).
- **month_detail** (logical) - Optional - If TRUE, break down by month. Default: TRUE.
- **metric_fob** (logical) - Optional - Include FOB value (US$). Default: TRUE.
- **metric_kg** (logical) - Optional - Include net weight (kg). Default: TRUE.
- **language** (string) - Optional - Response language: "pt", "en", or "es". Default: "en".
- **verbose** (logical) - Optional - Show progress messages. Default: TRUE.

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

### Example
```r
comex_query_city(
  flow = "export",
  start_period = "2023-01",
  end_period = "2023-12",
  details = c("country", "state"),
  filters = list(state = 26)
)
```
```

--------------------------------

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

Source: https://strategicprojects.github.io/comexr/reference/comex_metrics.html

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

```APIDOC
## comex_metrics

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

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

### Arguments
- **type** (string) - Optional - Data type: "general", "city", or "historical".
- **language** (string) - Optional - Language: "pt", "en", or "es". Default: "en".
- **verbose** (logical) - Optional - Show progress messages. Default: FALSE.

### Value
A data.frame with available metrics and their descriptions.
```

--------------------------------

### Configure Language Output

Source: https://strategicprojects.github.io/comexr/articles/getting-started.html

Set the language parameter to receive results in Portuguese, English, or Spanish.

```R
comex_blocs(language = "pt")
```

```R
comex_blocs(language = "en")
```

--------------------------------

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

Source: https://strategicprojects.github.io/comexr/reference/comex_blocs.html

Retrieves the economic blocs table with codes and names. Users can filter results by search terms or include related tables.

```APIDOC
## comex_blocs

### 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
- **language** (string) - Optional - Language: "pt", "en", or "es". Default: "en".
- **search** (string) - Optional - Optional search term to filter results.
- **add** (string) - Optional - Optional related table to include (e.g. "country").
- **verbose** (boolean) - Optional - Logical. Default: FALSE.

### Value
A data.frame with economic bloc codes and names.

### Examples
comex_blocs()
comex_blocs(search = "mercosul")
comex_blocs(add = "country")
```

--------------------------------

### Retrieve NBM table

Source: https://strategicprojects.github.io/comexr/reference/comex_nbm.html

Fetches the NBM codes table with optional filtering, pagination, and related table inclusion.

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

--------------------------------

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

Source: https://strategicprojects.github.io/comexr/reference/comex_hs.html

Retrieves Harmonized System (HS) classification tables as a data.frame.

```APIDOC
## comex_hs

### Description
Returns Harmonized System (HS) 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
- **language** (string) - Optional - Language: "pt", "en", or "es". Default: "en".
- **add** (string) - Optional - Optional related table to include (e.g. "ncm").
- **page** (integer) - Optional - Page number for pagination. Default: NULL.
- **per_page** (integer) - Optional - Number of results per page. Default: NULL.
- **verbose** (logical) - Optional - Logical. Default: FALSE.

### Value
A data.frame with HS codes and descriptions.

### Examples
# All HS classifications
comex_hs()

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

--------------------------------

### Perform runtime discovery

Source: https://strategicprojects.github.io/comexr/articles/auxiliary-tables.html

Uses discovery functions to identify valid filters, filter values, and metrics for specific endpoints.

```R
# 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")
```

--------------------------------

### comex_cities

Source: https://strategicprojects.github.io/comexr/articles/auxiliary-tables.html

Retrieves a list of all 5,570 municipalities.

```APIDOC
## comex_cities()

### Description
Returns a tibble containing the full list of municipalities.

### Response
- **id** (string) - City ID
- **text** (string) - City name and state
- **noMunMin** (string) - City name
```

--------------------------------

### Querying with table codes

Source: https://strategicprojects.github.io/comexr/articles/auxiliary-tables.html

Demonstrates finding numeric codes for countries and states to use as filters in export queries.

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

--------------------------------

### comex_export()

Source: https://strategicprojects.github.io/comexr/reference/index.html

Query exports.

```APIDOC
## comex_export()

### Description
Query exports.
```

--------------------------------

### comex_nbm_detail(nbm_code, verbose = FALSE)

Source: https://strategicprojects.github.io/comexr/reference/comex_nbm_detail.html

Retrieves details for a specific NBM code.

```APIDOC
## comex_nbm_detail

### Description
Returns details for a specific NBM code.

### Usage
comex_nbm_detail(nbm_code, verbose = FALSE)

### Arguments
- **nbm_code** (string) - NBM code (e.g. "2924101100").
- **verbose** (logical) - Default: FALSE.

### Value
A list with NBM details.

### Examples
comex_nbm_detail("2924101100")
```

--------------------------------

### Inspect city endpoint capabilities

Source: https://strategicprojects.github.io/comexr/articles/city-profile.html

Check available filters, details, and metrics supported by the city-level endpoint.

```R
comex_filters("city")    # 7 filters
comex_details("city")    # 7 details (same names as filters)
comex_metrics("city")    # only FOB and KG
```

--------------------------------

### Usage of comex_city_detail

Source: https://strategicprojects.github.io/comexr/reference/comex_city_detail.html

Basic function call syntax for retrieving city information.

```R
comex_city_detail(city_id, verbose = FALSE)
```

--------------------------------

### comex_ncm_detail(ncm_code, verbose = FALSE)

Source: https://strategicprojects.github.io/comexr/reference/comex_ncm_detail.html

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

```APIDOC
## comex_ncm_detail

### 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
- **ncm_code** (character) - Required - NCM code (8 digits, e.g., "02042200").
- **verbose** (logical) - Optional - Default: FALSE.

### Value
A list with NCM details.

### Examples
```r
comex_ncm_detail("02042200")
```
```

--------------------------------

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

Source: https://strategicprojects.github.io/comexr/reference/comex_ncm.html

Retrieves the NCM codes table with descriptions, supporting filtering, pagination, and additional classification mappings.

```APIDOC
## comex_ncm

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

### Arguments
- **language** (string) - Optional - Language: "pt", "en", or "es". Default: "en".
- **search** (string) - Optional - Search term to filter results (e.g., "animal").
- **add** (string) - Optional - Related table to include in results. Options: "sh", "cuci", "cgce".
- **page** (integer) - Optional - Page number for pagination. Default: NULL (all results).
- **per_page** (integer) - Optional - Number of results per page. Default: NULL.
- **verbose** (boolean) - Optional - Show progress messages. Default: FALSE.

### Value
A data.frame with NCM codes and descriptions.

### Examples
```r
ncm <- comex_ncm()
comex_ncm(search = "animal", per_page = 10)
comex_ncm(add = "cuci")
```
```

--------------------------------

### Fetch exports and imports

Source: https://strategicprojects.github.io/comexr/articles/state-trade-profile.html

Perform two separate API calls for exports and imports, then combine them into a single data frame.

```R
exp_pe <- comex_query_city(
  flow         = "export",
  start_period = period_from,
  end_period   = period_to,
  details      = detalhes,
  filters      = filtros,
  month_detail = TRUE,
  metric_fob   = TRUE,
  metric_kg    = TRUE
)
exp_pe$flow <- "export"

imp_pe <- comex_query_city(
  flow         = "import",
  start_period = period_from,
  end_period   = period_to,
  details      = detalhes,
  filters      = filtros,
  month_detail = TRUE,
  metric_fob   = TRUE,
  metric_kg    = TRUE
)
imp_pe$flow <- "import"

pe <- rbind(exp_pe, imp_pe)
```

--------------------------------

### Usage of comex_state_detail

Source: https://strategicprojects.github.io/comexr/reference/comex_state_detail.html

Basic function call syntax for retrieving state details.

```R
comex_state_detail(uf_id, verbose = FALSE)
```

--------------------------------

### Function usage syntax

Source: https://strategicprojects.github.io/comexr/reference/comex_filter_values.html

The standard function signature for retrieving filter values.

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

--------------------------------

### comex_export(start_period, end_period, ...)

Source: https://strategicprojects.github.io/comexr/reference/comex_export.html

Queries Brazilian export trade data for a defined time range with customizable grouping and metrics.

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

### Description
Retrieves export trade data from the ComexStat API. This function acts as a wrapper for `comex_query()` with the flow parameter pre-set to "export".

### Parameters
- **start_period** (string) - Required - Start period in "YYYY-MM" format.
- **end_period** (string) - Required - End period in "YYYY-MM" format.
- **details** (character vector) - Optional - Fields to group by (e.g., "country", "state", "ncm").
- **filters** (list) - Optional - Named list of filters matching detail field names.
- **month_detail** (logical) - Optional - If TRUE, breaks down results by month. Default: TRUE.
- **metric_fob** (logical) - Optional - Include FOB value (US$). Default: TRUE.
- **metric_kg** (logical) - Optional - Include net weight (kg). Default: TRUE.
- **metric_statistic** (logical) - Optional - Include statistical quantity. Default: FALSE.
- **metric_freight** (logical) - Optional - Include freight value. Default: FALSE.
- **metric_insurance** (logical) - Optional - Include insurance value. Default: FALSE.
- **metric_cif** (logical) - Optional - Include CIF value. Default: FALSE.
- **language** (string) - Optional - Response language: "pt", "en", or "es". Default: "en".
- **verbose** (logical) - Optional - Show progress messages. Default: TRUE.

### Returns
A data.frame or tibble containing the requested export data.

### Example
```r
comex_export(
  start_period = "2023-01",
  end_period = "2023-12",
  details = "country"
)
```
```

--------------------------------

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

Source: https://strategicprojects.github.io/comexr/reference/comex_details.html

Retrieves a data frame containing available detail fields for grouping query results.

```APIDOC
## comex_details

### 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
- **type** (string) - Optional - Data type: "general", "city", or "historical".
- **language** (string) - Optional - Language: "pt", "en", or "es". Default: "en".
- **verbose** (logical) - Optional - Show progress messages. Default: FALSE.

### Value
A data.frame with available details.

### Examples
```r
comex_details()
comex_details("city")
comex_details("historical")
```
```

--------------------------------

### comex_city_detail(city_id, verbose = FALSE)

Source: https://strategicprojects.github.io/comexr/reference/comex_city_detail.html

Retrieves details for a specific Brazilian city based on the provided IBGE city code.

```APIDOC
## comex_city_detail(city_id, verbose = FALSE)

### Description
Returns a list containing details for a specific Brazilian city identified by its IBGE code.

### Arguments
- **city_id** (numeric/string) - Required - IBGE city code (e.g., 5300050).
- **verbose** (logical) - Optional - Default: FALSE. Controls whether to display additional information.

### Value
A list containing the city details.

### Example
```r
comex_city_detail(5300050)
```
```

--------------------------------

### Usage of comex_last_update

Source: https://strategicprojects.github.io/comexr/reference/comex_last_update.html

Basic function call syntax for retrieving the last update date.

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

--------------------------------

### Usage of comex_ncm_detail

Source: https://strategicprojects.github.io/comexr/reference/comex_ncm_detail.html

Basic function call syntax for retrieving NCM details.

```R
comex_ncm_detail(ncm_code, verbose = FALSE)
```

--------------------------------

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

Source: https://strategicprojects.github.io/comexr/reference/comex_nbm.html

Retrieves 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).

```APIDOC
## comex_nbm

### 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
- **language** (string) - Optional - Language: "pt", "en", or "es". Default: "en".
- **search** (string) - Optional - Optional search term to filter results.
- **add** (string) - Optional - Optional related table to include (e.g. "ncm").
- **page** (integer) - Optional - Page number for pagination. Default: NULL.
- **per_page** (integer) - Optional - Number of results per page. Default: NULL.
- **verbose** (logical) - Optional - Logical. Default: FALSE.

### Value
A data.frame with NBM codes and descriptions.

### Examples
comex_nbm()
comex_nbm(search = "encomendas", per_page = 5)
comex_nbm(add = "ncm")
```

--------------------------------

### Retrieve economic blocs

Source: https://strategicprojects.github.io/comexr/articles/auxiliary-tables.html

Fetches economic blocs with support for language selection and additional columns.

```R
# 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")
```

```R
comex_blocs(language = "en", add = TRUE)
```

--------------------------------

### Query top export products

Source: https://strategicprojects.github.io/comexr/articles/city-profile.html

Retrieves export data at the HS4 level and sorts by metricFOB. Use 'hs2' or 'section' for coarser product aggregation.

```R
top_export_products <- comex_query_city(
  flow         = "export",
  start_period = year_from,
  end_period   = year_to,
  details      = "hs4",   # → heading
  filters      = list(city = city_code),
  month_detail = FALSE
)

top_export_products <- top_export_products[
  order(-as.numeric(top_export_products$metricFOB)),
]
head(top_export_products, 10)
```

```R
exports_by_section <- comex_query_city(
  flow         = "export",
  start_period = year_from,
  end_period   = year_to,
  details      = "section",
  filters      = list(city = city_code),
  month_detail = FALSE
)
exports_by_section
```

--------------------------------

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

Source: https://strategicprojects.github.io/comexr/reference/comex_available_years.html

Returns the first and last years available for queries in the API based on the specified data type.

```APIDOC
## comex_available_years

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

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

### Arguments
- **type** (string) - Optional - Data type: "general", "city", or "historical". Default: "general".
- **verbose** (logical) - Optional - Show progress messages. Default: FALSE.

### Value
A list with `min` and `max` year values.

### Examples
```r
comex_available_years()
comex_available_years("city")
comex_available_years("historical")
```
```

--------------------------------

### Usage of comex_cgce function

Source: https://strategicprojects.github.io/comexr/reference/comex_cgce.html

Defines the parameters available for the comex_cgce function, including language selection and pagination options.

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

--------------------------------

### comex_cities(verbose = FALSE)

Source: https://strategicprojects.github.io/comexr/reference/comex_cities.html

Retrieves the Brazilian cities table including IBGE codes and city names.

```APIDOC
## comex_cities

### Description
Returns the Brazilian cities table with codes and names.

### Usage
```r
comex_cities(verbose = FALSE)
```

### Arguments
- **verbose** (logical) - Optional - Default: FALSE. If TRUE, provides additional output during execution.

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

### Examples
```r
comex_cities()
```
```

--------------------------------

### Inspect data structure

Source: https://strategicprojects.github.io/comexr/articles/state-trade-profile.html

Examine the structure and first few rows of the combined trade data frame.

```R
str(pe)
head(pe)
```

--------------------------------

### comex_query()

Source: https://strategicprojects.github.io/comexr/reference/index.html

Query general foreign trade data.

```APIDOC
## comex_query()

### Description
Query general foreign trade data.
```

--------------------------------

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

Source: https://strategicprojects.github.io/comexr/reference/comex_filters.html

Retrieves the list of filter types available for API queries.

```APIDOC
## comex_filters

### Description
Returns a data.frame containing the list of filter types available for API queries.

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

### Arguments
- **type** (string) - Optional - Data type: "general", "city", or "historical".
- **language** (string) - Optional - Language: "pt", "en", or "es". Default: "en".
- **verbose** (logical) - Optional - Show progress messages. Default: FALSE.

### Value
A data.frame with available filters.

### Examples
```r
comex_filters()
comex_filters("city")
comex_filters("historical")
```
```

--------------------------------

### BibTeX Citation for comexr

Source: https://strategicprojects.github.io/comexr/authors.html

Use this BibTeX entry to cite the comexr package in academic publications.

```BibTeX
@Manual{,
  title = {comexr: Client for the Brazilian Foreign Trade Statistics API ('ComexStat')},
  author = {Andre Leite and Marcos Wasilew and Hugo Vasconcelos and Carlos Amorin and Diogo Bezerra},
  year = {2026},
  note = {R package version 0.3.0},
  url = {https://strategicprojects.github.io/comexr/},
}
```

--------------------------------

### Load dplyr library

Source: https://strategicprojects.github.io/comexr/articles/querying-trade-data.html

Load the dplyr package for data manipulation.

```R
library(dplyr)
```

--------------------------------

### Querying imports with CIF value

Source: https://strategicprojects.github.io/comexr/articles/querying-trade-data.html

Retrieves import data with additional metrics like freight, insurance, and CIF enabled.

```R
imports <- comex_import(
  start_period = "2024-01",
  end_period   = "2024-06",
  details      = "country",
  metric_cif   = TRUE
)
```

--------------------------------

### Query exports by economic bloc

Source: https://strategicprojects.github.io/comexr/articles/city-profile.html

Retrieves export data grouped by economic bloc and sorts the results by metricFOB in descending order.

```R
exports_by_bloc <- comex_query_city(
  flow         = "export",
  start_period = year_from,
  end_period   = year_to,
  details      = "bloc",
  filters      = list(city = city_code),
  month_detail = FALSE
)

exports_by_bloc <- exports_by_bloc[
  order(-as.numeric(exports_by_bloc$metricFOB)),
]
exports_by_bloc
```

--------------------------------

### Retrieve NBM Product Nomenclature

Source: https://strategicprojects.github.io/comexr/articles/auxiliary-tables.html

Access historical Brazilian Nomenclature of Goods data.

```R
nbm <- comex_nbm(language = "en", page = 1, per_page = 5)
nbm
```

```R
comex_nbm_detail("2924101100")
```

--------------------------------

### Check Data Availability

Source: https://strategicprojects.github.io/comexr/articles/getting-started.html

Retrieve the most recent update date, available years, and valid detail fields for a specific endpoint.

```R
comex_last_update("general")
```

```R
comex_available_years("general")
```

```R
comex_details("general")
```

--------------------------------

### comex_states(verbose = FALSE)

Source: https://strategicprojects.github.io/comexr/reference/comex_states.html

Retrieves the Brazilian states table including codes and names.

```APIDOC
## comex_states

### Description
Returns the Brazilian states table with codes and names.

### Usage
```r
comex_states(verbose = FALSE)
```

### Arguments
- **verbose** (logical) - Optional - Default: FALSE. Controls whether to display verbose output.

### Value
A data.frame with state codes and names.

### Examples
```r
comex_states()
```
```

--------------------------------

### comex_sitc Function Usage

Source: https://strategicprojects.github.io/comexr/reference/comex_sitc.html

Defines the parameters for the comex_sitc function, including language selection, search filtering, and pagination options.

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

--------------------------------

### Retrieve HS Harmonized System

Source: https://strategicprojects.github.io/comexr/articles/auxiliary-tables.html

Access international product classification hierarchy data.

```R
hs <- comex_hs(language = "en", page = 1, per_page = 5)
hs
```

--------------------------------

### comex_countries(search, language)

Source: https://strategicprojects.github.io/comexr/articles/getting-started.html

Retrieves a list of countries or searches for a specific country.

```APIDOC
## comex_countries

### Description
Returns a table of countries or filters by a search term.

### Parameters
- **search** (string) - Optional - Search term to filter country names.
- **language** (string) - Optional - Language for text fields ('pt', 'en', 'es').
```

--------------------------------

### Retrieve available detail fields

Source: https://strategicprojects.github.io/comexr/reference/comex_details.html

Use this function to list the fields available for grouping query results. Specify the data type to filter the returned fields.

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

--------------------------------

### Query monthly export time series

Source: https://strategicprojects.github.io/comexr/articles/city-profile.html

Retrieves monthly export data by setting month_detail to TRUE.

```R
exports_monthly <- comex_query_city(
  flow         = "export",
  start_period = year_from,
  end_period   = year_to,
  filters      = list(city = city_code),
  month_detail = TRUE
)
exports_monthly  # year, monthNumber, metricFOB, metricKG
```

--------------------------------

### Retrieve City Information

Source: https://strategicprojects.github.io/comexr/articles/auxiliary-tables.html

Fetch the full list of municipalities or details for a specific city using its ID.

```R
cities <- comex_cities()
cities
```

```R
comex_city_detail(2611606)
```

--------------------------------

### Retrieve available metrics

Source: https://strategicprojects.github.io/comexr/reference/comex_metrics.html

Use this function to list metrics for general, city, or historical data types. The function returns a data frame containing metric names and descriptions.

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

```R
if (FALSE) { # \dontrun{
comex_metrics()
comex_metrics("city")
comex_metrics("historical")
} # }
```

--------------------------------

### comex_state_detail(uf_id, verbose = FALSE)

Source: https://strategicprojects.github.io/comexr/reference/comex_state_detail.html

Retrieves details for a specific Brazilian state based on the provided state ID.

```APIDOC
## comex_state_detail(uf_id, verbose = FALSE)

### Description
Returns a list containing details for a specific Brazilian state.

### Arguments
- **uf_id** (integer/string) - Required - State code (e.g., 26 for Pernambuco).
- **verbose** (logical) - Optional - Default: FALSE. Controls whether to display verbose output.

### Value
A list containing state details.

### Example
```r
comex_state_detail(26)
```
```

--------------------------------

### comex_city_detail

Source: https://strategicprojects.github.io/comexr/articles/auxiliary-tables.html

Retrieves detailed information for a specific city by its ID.

```APIDOC
## comex_city_detail(id)

### Description
Returns detailed information for a specific city based on the provided ID.

### Parameters
- **id** (integer/string) - Required - The city ID (e.g., 2611606)
```

--------------------------------

### comex_countries(search = NULL, verbose = FALSE)

Source: https://strategicprojects.github.io/comexr/reference/comex_countries.html

Retrieves the countries table containing codes and names. Users can optionally filter the results using a search term.

```APIDOC
## comex_countries

### Description
Returns the countries table with codes and names.

### Usage
`comex_countries(search = NULL, verbose = FALSE)`

### Arguments
- **search** (character) - Optional - Optional search term to filter results (e.g. "br").
- **verbose** (logical) - Optional - Show progress messages. Default: FALSE.

### Value
A data.frame with country codes and names.

### Examples
```r
comex_countries()
comex_countries(search = "bra")
```
```

--------------------------------

### Analyze top destinations by product

Source: https://strategicprojects.github.io/comexr/articles/city-profile.html

Filter exports by a specific HS4 product code to identify top destination countries.

```R
# 1. Find the top HS4
top_hs4 <- head(top_export_products, 1)$headingCode

# 2. Break that product down by destination
top_destinations_for_product <- comex_query_city(
  flow         = "export",
  start_period = year_from,
  end_period   = year_to,
  details      = c("country", "hs4"),
  filters      = list(city = city_code, hs4 = top_hs4),
  month_detail = FALSE
)
top_destinations_for_product
```

--------------------------------

### Retrieve economic blocs table

Source: https://strategicprojects.github.io/comexr/reference/comex_blocs.html

Basic usage of the comex_blocs function to fetch economic bloc data.

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

--------------------------------

### Usage of comex_customs_unit_detail

Source: https://strategicprojects.github.io/comexr/reference/comex_customs_unit_detail.html

Basic function signature for retrieving customs unit details.

```R
comex_customs_unit_detail(urf_id, verbose = FALSE)
```