---
title: "Querying Trade Data"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Querying Trade Data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

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

```{r exports_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:

```{r imports_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:

```{r monthly}
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:

```{r multi_details}
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.

```{r filtered}
# 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:

```{r multi_filters}
# 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:

```{r generic}
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.

```{r city_discover}
# 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.

```{r city_query}
# 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.

```{r historical_discover}
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
```

```{r historical_query}
# 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.

```{r post_process}
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"` instead of `"sh4"`, `"transport_mode"` instead of
   `"transportMode"`. The package maps them automatically.

5. **City endpoint has fewer features.** Only 7 details, 2 metrics,
   and different product grouping names (heading/chapter/section).

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