# Querying Trade Data

The comexr package provides three query endpoints, each covering a different time period and level of geographic detail:

Function | Endpoint | Period | Geography
--- | --- | --- | ---
`comex_query()` | POST /general | 1997–present | National
`comex_query_city()` | POST /cities | 1997–present | Municipal
`comex_historical()` | POST /historical-data/ | 1989–1996 | National

Convenience wrappers `comex_export()` and `comex_import()` call `comex_query()` with the flow pre-set.

## Basic queries

### Exports by country

    library(comexr)

    exports <- comex_export(
      start_period = "2024-01",
      end_period   = "2024-12",
      details      = "country"
    )
    #> ℹ Querying exports from 2024-01 to 2024-12
    #> ✔ POST /general [580ms]
    #> ✔ 219 records found

By default, `comex_export()` returns FOB value (US$) and net weight (kg). Each row is a combination of the requested detail fields and the year.

### Imports with CIF value

The import endpoint supports additional metrics — freight, insurance, and CIF:

    imports <- comex_import(
      start_period = "2024-01",
      end_period   = "2024-06",
      details      = "country",
      metric_cif   = TRUE
    )
    # Returns columns: year, country, metricFOB, metricKG, metricCIF

## Monthly breakdown

Set `month_detail = TRUE` to get data split by month:

    monthly <- comex_export(
      start_period = "2024-01",
      end_period   = "2024-06",
      details      = "country",
      month_detail = TRUE
    )
    # Now each row also includes a month column

## Multiple grouping fields

Pass a character vector to `details` to cross-tabulate:

    by_country_product <- comex_export(
      start_period = "2024-01",
      end_period   = "2024-03",
      details      = c("country", "hs4"),
      month_detail = TRUE
    )
    # Rows grouped by: year × month × country × HS4 product heading

## Applying filters

Use `filters` to restrict the query to specific values. Filter codes come from the auxiliary tables.

    # Step 1: Find the codes for China and USA
    countries <- comex_countries(search = "China")
    # id = 160 (China), 249 (United States)

    # Step 2: Query only exports to these countries
    to_china_usa <- comex_export(
      start_period = "2024-01",
      end_period   = "2024-12",
      details      = c("country", "section"),
      filters      = list(country = c(160, 249))
    )

Multiple filters can be combined:

    # Exports of HS section 02 (Vegetable products) from São Paulo
    sp_veg <- comex_export(
      start_period = "2024-01",
      end_period   = "2024-12",
      details      = c("state", "hs2"),
      filters      = list(state = 35, sh2 = "02")
    )

## The generic `comex_query()`

For full control, use `comex_query()` which lets you specify flow, metrics, and all options:

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

## City-level queries

The city endpoint provides municipal-level detail but with a more limited set of grouping fields and metrics.

    # Which details are available for city queries?
    comex_details("city")
    #> # A tibble: 7 × 2
    #>    filter        text
    #>    <chr>         <chr>
    #>  1 country       Countries
    #>  2 economicBlock Economic Blocks
    #>  3 state         States
    #>  4 city          Cities
    #>  5 heading       Headings
    #>  6 chapter       Chapters
    #>  7 section       Sections

    # Which metrics?
    comex_metrics("city")
    #> # A tibble: 2 × 2
    #>    id          text
    #>    <chr>       <chr>
    #>  1 metricFOB   US$ FOB
    #>  2 metricKG    Net Weight (KG)

Important: The city endpoint uses `heading`, `chapter`, and `section` instead of `sh6`/`sh4`/`sh2`. NCM and classification details (CGCE, SITC, ISIC) are not available. CIF and freight metrics are not available either.

    # Exports from Pernambuco (state 26) by country
    pe_exports <- comex_query_city(
      flow         = "export",
      start_period = "2024-01",
      end_period   = "2024-12",
      details      = c("state", "country"),
      filters      = list(state = 26)
    )

    # Exports from Recife (city 2611606) by product section
    recife <- comex_query_city(
      flow         = "export",
      start_period = "2024-01",
      end_period   = "2024-06",
      details      = c("city", "section"),
      filters      = list(city = 2611606)
    )

## Historical data (1989–1996)

The historical endpoint covers the period before the current NCM nomenclature was adopted. It uses the NBM (Nomenclatura Brasileira de Mercadorias) system.

    comex_available_years("historical")
    #> $max
    #> [1] "1996"
    #> $min
    #> [1] "1989"

    comex_details("historical")
    #> # A tibble: 4 × 2
    #>    filter  text
    #>    <chr>   <chr>
    #>  1 country Countries
    #>  2 state   States
    #>  3 nbm     NBM
    #>  4 section Sections

    # Historical exports by country in 1990
    hist_1990 <- comex_historical(
      flow         = "export",
      start_period = "1990-01",
      end_period   = "1990-12",
      details      = "country"
    )

## Working with results

All query functions return a data.frame (or tibble if the tibble package is installed). Column names come directly from the API — they are the same as the detail/metric names you requested.

    library(dplyr)

    # Top 10 export destinations in 2024 by FOB value
    top10 <- comex_export(
      start_period = "2024-01",
      end_period   = "2024-12",
      details      = "country"
    ) |>
      arrange(desc(metricFOB)) |>
      head(10)

    # Monthly export trend to China
    china_monthly <- comex_export(
      start_period = "2024-01",
      end_period   = "2024-12",
      details      = "country",
      filters      = list(country = 160),
      month_detail = TRUE
    )

## Tips and best practices

1. Start with discovery. Use `comex_details()`, `comex_filters()`, and `comex_metrics()` before building complex queries.

2. Use filters to reduce response size. The API has a limit of ~150,000 rows. If your query is too broad, the API will timeout. Add filters or reduce the date range.

3. Filter codes are integers. Use `comex_countries()`, `comex_states()`, `comex_filter_values()` to find the numeric codes.

4. The `details` parameter accepts user-friendly names. Write `"hs4"` (maps to API `heading`), `"transport_mode"` (maps to API `via`), `"cgce_n1"` (maps to API `BECLevel1`), `"sitc_section"` (maps to API `SITCSection`), `"isic_section"` (maps to API `ISICSection`). The package handles the translation automatically.

5. City endpoint has fewer features. Only 7 details, 2 metrics (FOB and KG), no transport mode or customs unit, and product grouping stops at HS4 (`heading`/`chapter`/`section`).

6. Historical endpoint uses NBM. The `"ncm"` detail is not available — use `"nbm"` instead.