Building a city trade profile (replicating the ComexStat municipality page)

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.

What the city endpoint exposes

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

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:

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

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:

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

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:

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

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:

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:

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

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:

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

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()]:

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.