---
title: "Building a city trade profile (replicating the ComexStat municipality page)"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Building a city trade profile (replicating the ComexStat municipality page)}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

The public ComexStat website has a page per municipality at
`https://comexstat.mdic.gov.br/en/municipio/{code}` showing the city's
foreign trade profile. This vignette reproduces those panels — totals,
top trading partners, top economic blocs, top products and a monthly
time series — using only the `comexr` package.

We use **Recife - PE (IBGE 2611606)** as the example. The same pattern
works for any Brazilian municipality; just swap the IBGE code.

> **Note on city codes.** The ComexStat web URLs may use a legacy
> internal code (`co_mun_geo`). The API accepts only the standard 7-digit
> IBGE code (`coMunGeo`). Use [`comex_cities()`] or
> [`comex_city_detail()`] to look up the right code.

```{r load}
library(comexr)

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

## What the city endpoint exposes

City-level data is more limited than the general endpoint. Always
inspect the available options before building a query:

```{r explore-city}
comex_filters("city")    # 7 filters
comex_details("city")    # 7 details (same names as filters)
comex_metrics("city")    # only FOB and KG
```

| Available for cities | Not available for cities                         |
|----------------------|--------------------------------------------------|
| `country`            | `via` (transport mode)                           |
| `economicBlock`      | `urf` (customs unit)                             |
| `state`              | `ncm` (full 8-digit NCM)                         |
| `city`               | `subHeading` (HS6)                               |
| `heading` (HS4)      | CGCE / SITC / ISIC classifications               |
| `chapter` (HS2)      | `metricStatistic`, `metricFreight`, `metricCIF`, |
| `section`            | `metricInsurance`                                |

User-friendly aliases — `bloc` / `economic_block`, `hs4` / `sh4`,
`hs2` / `sh2` — are translated automatically by the package.

## 1. Headline totals (FOB and net weight)

Aggregate exports and imports for the period, with no detail grouping
beyond the year:

```{r totals}
exports_total <- comex_query_city(
  flow         = "export",
  start_period = year_from,
  end_period   = year_to,
  filters      = list(city = city_code),
  month_detail = FALSE
)

imports_total <- comex_query_city(
  flow         = "import",
  start_period = year_from,
  end_period   = year_to,
  filters      = list(city = city_code),
  month_detail = FALSE
)

exports_total
imports_total
```

The trade balance is just `metricFOB(export) - metricFOB(import)`:

```{r balance}
balance <- as.numeric(exports_total$metricFOB) -
           as.numeric(imports_total$metricFOB)
```

## 2. Top trading partners

The "Top countries" panel on the municipality page is a `country` group:

```{r top-countries}
top_export_countries <- comex_query_city(
  flow         = "export",
  start_period = year_from,
  end_period   = year_to,
  details      = "country",
  filters      = list(city = city_code),
  month_detail = FALSE
)

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

top_import_countries <- comex_query_city(
  flow         = "import",
  start_period = year_from,
  end_period   = year_to,
  details      = "country",
  filters      = list(city = city_code),
  month_detail = FALSE
)
top_import_countries <- top_import_countries[
  order(-as.numeric(top_import_countries$metricFOB)),
]
head(top_import_countries, 10)
```

## 3. Top economic blocs

The "Top blocs" panel groups by `economicBlock` (alias: `bloc`):

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

## 4. Top products (HS4 / heading)

Product detail goes down to HS4 (`heading`) for cities — HS6
(`subHeading`) is **not** available at this endpoint, and neither is
the full 8-digit NCM:

```{r top-products}
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)
```

For a coarser cut, use `"hs2"` (chapter) or `"section"`:

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

## 5. Monthly time series

Set `month_detail = TRUE` (the default) to reproduce the time-series
chart on the page:

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

Plot it with whichever graphics package you prefer:

```{r monthly-plot}
# Example with base 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)
)
```

## 6. Year-over-year comparison

To compare with prior years (the page typically shows a YoY change),
extend the period and group by year only:

```{r yearly}
exports_yearly <- comex_query_city(
  flow         = "export",
  start_period = "2019-01",
  end_period   = "2024-12",
  filters      = list(city = city_code),
  month_detail = FALSE
)
exports_yearly  # one row per year
```

## 7. Cross-cutting query: top destinations by product

You can combine details to drill in further — e.g. top destinations
for the city's leading product:

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

## Looking up the city code from a name

If you only have the city's name, search the cities table:

```{r lookup}
recife <- comex_cities()
recife[grepl("Recife", recife$text, ignore.case = TRUE), ]
# Use the `id` column (IBGE coMunGeo) in subsequent filters.
```

For an authoritative single-city lookup (with state), use
[`comex_city_detail()`]:

```{r detail}
comex_city_detail(2611606)
#> $coMunGeo  "2611606"
#> $noMun     "RECIFE"
#> $noMunMin  "Recife"
#> $sgUf      "PE"
```

## Tips

- City-level data follows the **declarant**'s municipality (where the
  exporter / importer is registered), not the origin or destination of
  the goods. A producer city and the declarant city can differ.
- The API caps responses to roughly 150,000 rows. If a query times
  out, add filters or shorten the date range.
- For deeper product detail (NCM, HS6) or for transport / customs-unit
  breakdowns, use [`comex_query()`] / [`comex_export()`] /
  [`comex_import()`] on the general endpoint instead — but those do
  not accept a `city` filter.