brmunipanel 0.1.0__tar.gz

brmunipanel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Guesse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

brmunipanel-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE
+include README.md
+include pyproject.toml
+graft tests
+recursive-include src/brmunipanel/metadata *.json
+global-exclude *.py[cod] __pycache__ *.so

brmunipanel-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: brmunipanel
+Version: 0.1.0
+Summary: ETL library for a harmonized panel of socioeconomic, fiscal, health, territorial and educational indicators for Brazilian municipalities (IBGE, Tesouro Nacional, IPEA Data, DATASUS, INEP).
+Author: Lucas Guesse
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lucasguesse/brmunipanel
+Project-URL: Repository, https://github.com/lucasguesse/brmunipanel
+Project-URL: Issues, https://github.com/lucasguesse/brmunipanel/issues
+Project-URL: Documentation, https://github.com/lucasguesse/brmunipanel#readme
+Keywords: brazil,municipalities,panel,etl,indicators,ibge,inep,siconfi,datasus
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: duckdb>=1.0.0
+Requires-Dist: polars>=1.0.0
+Requires-Dist: pyarrow>=16.0.0
+Requires-Dist: pandas>=2.2.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: xlrd>=2.0.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: requests>=2.32.0
+Requires-Dist: tqdm>=4.66.0
+Requires-Dist: access-parser==0.0.6
+Requires-Dist: construct>=2.10.70
+Requires-Dist: tabulate>=0.10.0
+Provides-Extra: plots
+Requires-Dist: matplotlib>=3.9.0; extra == "plots"
+Requires-Dist: seaborn>=0.13.0; extra == "plots"
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: tomli>=1.1.0; python_version < "3.11" and extra == "dev"
+Dynamic: license-file
+
+# BRMuniPanel
+
+[![CI](https://github.com/lucasguesse/brmunipanel/actions/workflows/ci.yml/badge.svg)](https://github.com/lucasguesse/brmunipanel/actions/workflows/ci.yml)
+
+**A Python ETL library and data access tool for the Harmonized Suite of Tables of Socioeconomic, Fiscal, Territorial, Health, and Educational Indicators for Brazilian Municipalities (2006–2023).**
+
+## Overview
+`brmunipanel` is an open-source Python library designed to fully automate the extraction, transformation, and loading (ETL) of public administrative records from multiple Brazilian federal agencies. It solves the massive structural burden of dealing with fragmented, historically inconsistent, and undocumented municipal data in Brazil.
+
+By standardizing the 7-digit IBGE municipality code as the primary join key and freezing the territorial division to the 2025 canonical grid, this library allows researchers and data scientists to easily build and consume a longitudinal structural database of 5,571 municipalities, structured across six standardized tables: two territorial tables and four longitudinal thematic tables (Demographics/Economy/Social, Public Finances, Health, and Education).
+
+This library provides the reproducible scientific protocol and supporting codebase for building the harmonized dataset of Brazilian municipal indicators.
+
+## Key Features
+- **Fully Reproducible ETL:** Transparent code that downloads raw data directly from official sources (IBGE, Tesouro Nacional/SICONFI, DATASUS, IPEA Data, INEP) and processes it systematically.
+- **Harmonized Joins:** Automatically aligns historical data (2006–2023) against the most recent and stable territorial division grid (DTB 2025).
+- **Thematic Modularity:** Provides six standardized tables:
+  - `municipios`: Canonical territorial crosswalk and municipal metadata (DTB 2025, territorial area in km², coordinates of municipal seat, border and coastal indicators).
+  - `demografia_economia_social`: Longitudinal panel covering population estimates, municipal GDP, formal employment from CEMPRE, and Bolsa Família beneficiaries and transfers.
+  - `financas_publicas`: Longitudinal panel covering municipal budgetary expenditures by functional classification (28 functions) combining FINBRA (2006–2012) and SICONFI (2013–2023).
+  - `saude`: Longitudinal panel covering health infrastructure, human resources, mortality, and live births from DATASUS (CNES, SIM, Sinasc).
+  - `municipios_limitrofes`: Adjacency pairs identifying contiguous neighbor municipalities across Brazil.
+  - `educacao`: Observed municipal panel aggregating microdata from School Census (Censo Escolar), Higher Education Census (Censo da Educação Superior), and observed public school IDEB scores across primary, lower secondary, and upper secondary education.
+- **Extensive Metadata & Data Dictionaries:** Exposes variables with explicitly documented domain rules, missing value tracking, and schema changes over the years.
+- **Highly Performant:** Built with `duckdb` and `polars`/`pyarrow` for blazing fast in-memory analytics of large municipal microdata.
+
+## Installation
+
+You can install the library directly from PyPI (once published) or from the source repository:
+
+```bash
+# Recommended via pip (once published on PyPI)
+pip install brmunipanel
+
+# From the GitHub repository
+pip install git+https://github.com/lucasguesse/brmunipanel.git
+```
+
+## Quick Start (Usage Example)
+
+The library exposes version metadata and source namespaces at top level, along with modular ETL and harmonization routines in each submodule:
+
+```python
+from pathlib import Path
+import brmunipanel as bmp
+from brmunipanel.ibge import populacao, pib
+from brmunipanel.ipea import pbf
+from brmunipanel.inep import (
+    harmonizar_censo_escolar,
+    harmonizar_censo_superior,
+    harmonizar_ideb,
+)
+from brmunipanel.tesouro import siconfi, finbra
+from brmunipanel.datasus import saude
+
+# Package version and source namespaces
+print(bmp.__version__)
+# Available namespaces: bmp.ibge, bmp.tesouro, bmp.ipea, bmp.datasus, bmp.inep
+
+# Example: Harmonize population estimates from a local SIDRA raw folder
+# df_pop = populacao.harmonizar(Path("raw/bases-de-dados/ibge/populacao"))
+
+# Example: Harmonize Bolsa Família records from an IPEA Data raw folder
+# df_pbf = pbf.harmonizar(Path("raw/bases-de-dados/ipea"))
+
+# Example: Harmonize public school IDEB scores with municipal crosswalk
+# df_ideb = harmonizar_ideb(Path("raw/bases-de-dados/ideb"), municipios_df)
+```
+
+## Data Sources Handled
+The library currently wraps and harmonizes the following official sources:
+* **IBGE (Instituto Brasileiro de Geografia e Estatística):**
+  * Population estimates (SIDRA Table 6579)
+  * Municipal GDP (PIB Municipal, SIDRA Table 5938)
+  * Central Register of Enterprises (CEMPRE, SIDRA Tables 1685 and 9509)
+  * Territorial grids (DTB 2025, Area, Municipal Seat Coordinates, Adjacency matrices)
+* **Tesouro Nacional (STN):**
+  * FINBRA (2006–2012, budgetary expenditure by function)
+  * SICONFI (2013–2023, budgetary expenditure by function)
+* **IPEA Data (MDS):**
+  * Programa Bolsa Família (beneficiaries and financial transfers, FAM_PBF / VAL_PBF)
+* **Ministério da Saúde (DATASUS):**
+  * CNES: Hospital beds, ICU capacity, diagnostic imaging equipment, and physicians per municipality
+  * SIM: Violent deaths and infant mortality
+  * Sinasc: Live births
+  * Health Regions and Macro-regions
+* **INEP (Instituto Nacional de Estudos e Pesquisas Educacionais Anísio Teixeira):**
+  * Censo Escolar: Active schools, enrollments, and teachers across basic education stages
+  * Censo da Educação Superior: In-person higher education institutions and enrollments
+  * IDEB: Observed public school scores across primary (anos iniciais), lower secondary (anos finais), and upper secondary (ensino médio) education
+
+## Development, Testing, and Building
+To set up the library for local development, run tests, and build verifiable distribution packages according to the Python Packaging User Guide:
+
+```bash
+# 1. Clone repository and navigate to root
+git clone https://github.com/lucasguesse/brmunipanel.git
+cd brmunipanel
+
+# 2. Create and activate a dedicated virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# 3. Install in editable mode with development dependencies
+pip install -e ".[dev]"
+
+# 4. Run the full test suite
+pytest
+
+# 5. Build standard distribution artifacts (sdist and wheel)
+# Ensure dist/ is clean before building
+python -m build
+
+# 6. Validate distribution artifacts strictly with Twine
+python -m twine check --strict dist/*
+
+# 7. Test installation of the built wheel in a separate, clean virtual environment
+python -m venv .venv-clean
+source .venv-clean/bin/activate  # On Windows: .venv-clean\Scripts\activate
+pip install --no-deps dist/brmunipanel-0.1.0-py3-none-any.whl
+python -c "import brmunipanel as bmp; print(bmp.__version__)"
+deactivate
+```
+
+> **Note on Publishing:** Distribution packages are published to TestPyPI and PyPI via GitHub Actions using PyPA Trusted Publishing (OIDC) without persistent tokens or secrets. Publishing to TestPyPI is triggered manually via `workflow_dispatch`, while official publishing to PyPI is triggered strictly upon a published GitHub Release (`v*`). Version `0.1.0` has been published and validated on TestPyPI, while official publication to PyPI remains pending the first official GitHub Release. Never commit API tokens, credentials, or `.pypirc` files to version control.
+
+Full end-to-end pipeline execution and paper reproduction scripts are maintained in the companion research repository.
+
+## How to Cite
+If you use this library or its data routines in your research, please cite this software repository and specify the release version used while a definitive academic citation is not yet available:
+
+- **Repository:** [https://github.com/lucasguesse/brmunipanel](https://github.com/lucasguesse/brmunipanel)
+- **Release:** Specify the release tag or version used in your analysis.
+
+A formal academic citation will be provided here once available.
+
+## License
+MIT License. See [LICENSE](LICENSE) for details.
+

brmunipanel-0.1.0/README.md

@@ -0,0 +1,139 @@
+# BRMuniPanel
+
+[![CI](https://github.com/lucasguesse/brmunipanel/actions/workflows/ci.yml/badge.svg)](https://github.com/lucasguesse/brmunipanel/actions/workflows/ci.yml)
+
+**A Python ETL library and data access tool for the Harmonized Suite of Tables of Socioeconomic, Fiscal, Territorial, Health, and Educational Indicators for Brazilian Municipalities (2006–2023).**
+
+## Overview
+`brmunipanel` is an open-source Python library designed to fully automate the extraction, transformation, and loading (ETL) of public administrative records from multiple Brazilian federal agencies. It solves the massive structural burden of dealing with fragmented, historically inconsistent, and undocumented municipal data in Brazil.
+
+By standardizing the 7-digit IBGE municipality code as the primary join key and freezing the territorial division to the 2025 canonical grid, this library allows researchers and data scientists to easily build and consume a longitudinal structural database of 5,571 municipalities, structured across six standardized tables: two territorial tables and four longitudinal thematic tables (Demographics/Economy/Social, Public Finances, Health, and Education).
+
+This library provides the reproducible scientific protocol and supporting codebase for building the harmonized dataset of Brazilian municipal indicators.
+
+## Key Features
+- **Fully Reproducible ETL:** Transparent code that downloads raw data directly from official sources (IBGE, Tesouro Nacional/SICONFI, DATASUS, IPEA Data, INEP) and processes it systematically.
+- **Harmonized Joins:** Automatically aligns historical data (2006–2023) against the most recent and stable territorial division grid (DTB 2025).
+- **Thematic Modularity:** Provides six standardized tables:
+  - `municipios`: Canonical territorial crosswalk and municipal metadata (DTB 2025, territorial area in km², coordinates of municipal seat, border and coastal indicators).
+  - `demografia_economia_social`: Longitudinal panel covering population estimates, municipal GDP, formal employment from CEMPRE, and Bolsa Família beneficiaries and transfers.
+  - `financas_publicas`: Longitudinal panel covering municipal budgetary expenditures by functional classification (28 functions) combining FINBRA (2006–2012) and SICONFI (2013–2023).
+  - `saude`: Longitudinal panel covering health infrastructure, human resources, mortality, and live births from DATASUS (CNES, SIM, Sinasc).
+  - `municipios_limitrofes`: Adjacency pairs identifying contiguous neighbor municipalities across Brazil.
+  - `educacao`: Observed municipal panel aggregating microdata from School Census (Censo Escolar), Higher Education Census (Censo da Educação Superior), and observed public school IDEB scores across primary, lower secondary, and upper secondary education.
+- **Extensive Metadata & Data Dictionaries:** Exposes variables with explicitly documented domain rules, missing value tracking, and schema changes over the years.
+- **Highly Performant:** Built with `duckdb` and `polars`/`pyarrow` for blazing fast in-memory analytics of large municipal microdata.
+
+## Installation
+
+You can install the library directly from PyPI (once published) or from the source repository:
+
+```bash
+# Recommended via pip (once published on PyPI)
+pip install brmunipanel
+
+# From the GitHub repository
+pip install git+https://github.com/lucasguesse/brmunipanel.git
+```
+
+## Quick Start (Usage Example)
+
+The library exposes version metadata and source namespaces at top level, along with modular ETL and harmonization routines in each submodule:
+
+```python
+from pathlib import Path
+import brmunipanel as bmp
+from brmunipanel.ibge import populacao, pib
+from brmunipanel.ipea import pbf
+from brmunipanel.inep import (
+    harmonizar_censo_escolar,
+    harmonizar_censo_superior,
+    harmonizar_ideb,
+)
+from brmunipanel.tesouro import siconfi, finbra
+from brmunipanel.datasus import saude
+
+# Package version and source namespaces
+print(bmp.__version__)
+# Available namespaces: bmp.ibge, bmp.tesouro, bmp.ipea, bmp.datasus, bmp.inep
+
+# Example: Harmonize population estimates from a local SIDRA raw folder
+# df_pop = populacao.harmonizar(Path("raw/bases-de-dados/ibge/populacao"))
+
+# Example: Harmonize Bolsa Família records from an IPEA Data raw folder
+# df_pbf = pbf.harmonizar(Path("raw/bases-de-dados/ipea"))
+
+# Example: Harmonize public school IDEB scores with municipal crosswalk
+# df_ideb = harmonizar_ideb(Path("raw/bases-de-dados/ideb"), municipios_df)
+```
+
+## Data Sources Handled
+The library currently wraps and harmonizes the following official sources:
+* **IBGE (Instituto Brasileiro de Geografia e Estatística):**
+  * Population estimates (SIDRA Table 6579)
+  * Municipal GDP (PIB Municipal, SIDRA Table 5938)
+  * Central Register of Enterprises (CEMPRE, SIDRA Tables 1685 and 9509)
+  * Territorial grids (DTB 2025, Area, Municipal Seat Coordinates, Adjacency matrices)
+* **Tesouro Nacional (STN):**
+  * FINBRA (2006–2012, budgetary expenditure by function)
+  * SICONFI (2013–2023, budgetary expenditure by function)
+* **IPEA Data (MDS):**
+  * Programa Bolsa Família (beneficiaries and financial transfers, FAM_PBF / VAL_PBF)
+* **Ministério da Saúde (DATASUS):**
+  * CNES: Hospital beds, ICU capacity, diagnostic imaging equipment, and physicians per municipality
+  * SIM: Violent deaths and infant mortality
+  * Sinasc: Live births
+  * Health Regions and Macro-regions
+* **INEP (Instituto Nacional de Estudos e Pesquisas Educacionais Anísio Teixeira):**
+  * Censo Escolar: Active schools, enrollments, and teachers across basic education stages
+  * Censo da Educação Superior: In-person higher education institutions and enrollments
+  * IDEB: Observed public school scores across primary (anos iniciais), lower secondary (anos finais), and upper secondary (ensino médio) education
+
+## Development, Testing, and Building
+To set up the library for local development, run tests, and build verifiable distribution packages according to the Python Packaging User Guide:
+
+```bash
+# 1. Clone repository and navigate to root
+git clone https://github.com/lucasguesse/brmunipanel.git
+cd brmunipanel
+
+# 2. Create and activate a dedicated virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# 3. Install in editable mode with development dependencies
+pip install -e ".[dev]"
+
+# 4. Run the full test suite
+pytest
+
+# 5. Build standard distribution artifacts (sdist and wheel)
+# Ensure dist/ is clean before building
+python -m build
+
+# 6. Validate distribution artifacts strictly with Twine
+python -m twine check --strict dist/*
+
+# 7. Test installation of the built wheel in a separate, clean virtual environment
+python -m venv .venv-clean
+source .venv-clean/bin/activate  # On Windows: .venv-clean\Scripts\activate
+pip install --no-deps dist/brmunipanel-0.1.0-py3-none-any.whl
+python -c "import brmunipanel as bmp; print(bmp.__version__)"
+deactivate
+```
+
+> **Note on Publishing:** Distribution packages are published to TestPyPI and PyPI via GitHub Actions using PyPA Trusted Publishing (OIDC) without persistent tokens or secrets. Publishing to TestPyPI is triggered manually via `workflow_dispatch`, while official publishing to PyPI is triggered strictly upon a published GitHub Release (`v*`). Version `0.1.0` has been published and validated on TestPyPI, while official publication to PyPI remains pending the first official GitHub Release. Never commit API tokens, credentials, or `.pypirc` files to version control.
+
+Full end-to-end pipeline execution and paper reproduction scripts are maintained in the companion research repository.
+
+## How to Cite
+If you use this library or its data routines in your research, please cite this software repository and specify the release version used while a definitive academic citation is not yet available:
+
+- **Repository:** [https://github.com/lucasguesse/brmunipanel](https://github.com/lucasguesse/brmunipanel)
+- **Release:** Specify the release tag or version used in your analysis.
+
+A formal academic citation will be provided here once available.
+
+## License
+MIT License. See [LICENSE](LICENSE) for details.
+

brmunipanel-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "brmunipanel"
+version = "0.1.0"
+description = "ETL library for a harmonized panel of socioeconomic, fiscal, health, territorial and educational indicators for Brazilian municipalities (IBGE, Tesouro Nacional, IPEA Data, DATASUS, INEP)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Lucas Guesse" }]
+keywords = [
+    "brazil",
+    "municipalities",
+    "panel",
+    "etl",
+    "indicators",
+    "ibge",
+    "inep",
+    "siconfi",
+    "datasus",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "duckdb>=1.0.0",
+    "polars>=1.0.0",
+    "pyarrow>=16.0.0",
+    "pandas>=2.2.0",
+    "numpy>=1.26.0",
+    "xlrd>=2.0.0",
+    "openpyxl>=3.1.0",
+    "requests>=2.32.0",
+    "tqdm>=4.66.0",
+    "access-parser==0.0.6",
+    "construct>=2.10.70",
+    "tabulate>=0.10.0",
+]
+
+[project.optional-dependencies]
+plots = ["matplotlib>=3.9.0", "seaborn>=0.13.0"]
+dev = [
+    "build>=1.2.0",
+    "pytest>=8.0.0",
+    "twine>=5.0.0",
+    'tomli>=1.1.0; python_version < "3.11"',
+]
+
+[project.urls]
+Homepage = "https://github.com/lucasguesse/brmunipanel"
+Repository = "https://github.com/lucasguesse/brmunipanel"
+Issues = "https://github.com/lucasguesse/brmunipanel/issues"
+Documentation = "https://github.com/lucasguesse/brmunipanel#readme"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+brmunipanel = ["metadata/variaveis.json"]

brmunipanel-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

brmunipanel-0.1.0/src/brmunipanel/__init__.py

@@ -0,0 +1,39 @@
+"""ETL library for a harmonized panel of Brazilian municipal indicators (IBGE, Tesouro Nacional, IPEA Data, DATASUS, INEP)."""
+
+import importlib
+from typing import TYPE_CHECKING
+
+__version__ = "0.1.0"
+
+_SUBMODULES = {
+    "datasus",
+    "ibge",
+    "inep",
+    "ipea",
+    "tesouro",
+}
+
+__all__ = [
+    "__version__",
+    "datasus",
+    "ibge",
+    "inep",
+    "ipea",
+    "tesouro",
+]
+
+if TYPE_CHECKING:
+    from brmunipanel import datasus, ibge, inep, ipea, tesouro
+
+
+def __getattr__(name: str):
+    if name in _SUBMODULES:
+        module = importlib.import_module(f"brmunipanel.{name}")
+        globals()[name] = module
+        return module
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+def __dir__():
+    return __all__
+

brmunipanel-0.1.0/src/brmunipanel/datasus/__init__.py

@@ -0,0 +1 @@
+"""Módulos de coleta e harmonização de dados do Ministério da Saúde / DATASUS."""

brmunipanel-0.1.0/src/brmunipanel/datasus/regioes_saude.py

@@ -0,0 +1,153 @@
+"""Regiões e macrorregiões de saúde por município (API de Dados Abertos do Ministério da Saúde).
+
+Endpoint: https://apidadosabertos.saude.gov.br/macrorregiao-e-regiao-de-saude/municipio
+Os códigos de município chegam com 6 dígitos e são convertidos para os 7 dígitos da DTB.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+import polars as pl
+import requests
+
+from .. import nucleo
+from ..nucleo import Requisicao, RespostaInvalida
+
+URL_BASE = "https://apidadosabertos.saude.gov.br/macrorregiao-e-regiao-de-saude/municipio"
+CHAVE_RESPOSTA = "macrorregiao_regiao_saude_municipios"
+LIMITE_PAGINA = 1000
+
+
+def validar(conteudo: bytes) -> None:
+    """Valida se o conteúdo é um JSON com o formato esperado da API de regiões de saúde."""
+    try:
+        dados = json.loads(conteudo)
+        if not isinstance(dados, dict):
+            raise RespostaInvalida("Resposta não é um objeto JSON")
+        itens = dados.get(CHAVE_RESPOSTA)
+        if not isinstance(itens, list):
+            raise RespostaInvalida(f"Chave '{CHAVE_RESPOSTA}' ausente ou não é uma lista")
+    except (json.JSONDecodeError, RespostaInvalida) as erro:
+        raise RespostaInvalida(f"Conteúdo inválido da API de regiões de saúde: {erro}") from erro
+
+
+def baixar(pasta: Path, **opcoes) -> list[dict]:
+    """Baixa todas as páginas da API de regiões de saúde avançando o offset pelo total de itens recebidos."""
+    pasta = Path(pasta)
+    offset = 0
+    registros = []
+    sessao = opcoes.pop("sessao", None) or requests.Session()
+    intervalo = opcoes.pop("intervalo", 1.0)
+
+    while True:
+        chave = f"offset{offset:04d}"
+        arquivo = f"regioes_saude_offset{offset:04d}.json.gz"
+        url = f"{URL_BASE}?limit={LIMITE_PAGINA}&offset={offset}"
+        req = Requisicao(chave=chave, url=url, arquivo=arquivo, compactar=True)
+
+        registro, baixou = nucleo.baixar(req, pasta, sessao=sessao, validar=validar, **opcoes)
+        registros.append(registro)
+        if baixou and intervalo:
+            time.sleep(intervalo)
+
+        conteudo = nucleo.ler_bruto(pasta, req.arquivo)
+        dados = json.loads(conteudo)
+        itens = dados.get(CHAVE_RESPOSTA, [])
+        if not itens:
+            break
+        offset += len(itens)
+
+    return registros
+
+
+def processar_itens(
+    itens: list[dict[str, Any]],
+    municipios: pl.DataFrame,
+) -> tuple[pl.DataFrame, list[dict[str, Any]]]:
+    """Converte os itens da API para tabela harmonizada usando `cod_municipio_6` de `municipios`.
+
+    Retorna o DataFrame harmonizado e a lista de itens descartados por falta de correspondência na DTB.
+    Levanta ValueError se houver código de município repetido entre os itens recebidos.
+    """
+    vistos: set[str] = set()
+    repetidos: set[str] = set()
+    for item in itens:
+        cod_6 = str(item.get("codigo_municipio", "")).strip()
+        if not cod_6:
+            continue
+        if cod_6 in vistos:
+            repetidos.add(cod_6)
+        vistos.add(cod_6)
+
+    if repetidos:
+        raise ValueError(
+            f"Códigos de município repetidos encontrados na paginação da API ({len(repetidos)}): {sorted(repetidos)}"
+        )
+
+    crosswalk = dict(zip(municipios["cod_municipio_6"].to_list(), municipios["cod_municipio"].to_list()))
+
+    linhas = []
+    descartados = []
+    for item in itens:
+        cod_6 = str(item.get("codigo_municipio", "")).strip()
+        cod_7 = crosswalk.get(cod_6)
+        if cod_7 is None:
+            descartados.append(item)
+            continue
+
+        linhas.append({
+            "cod_municipio": cod_7,
+            "cod_regiao_saude": str(item.get("codigo_regiao_saude", "")).strip(),
+            "nome_regiao_saude": str(item.get("regiao_saude", "")).strip(),
+            "cod_macrorregiao_saude": str(item.get("codigo_macrorregiao_saude", "")).strip(),
+            "nome_macrorregiao_saude": str(item.get("macrorregiao_saude", "")).strip(),
+        })
+
+    if not linhas:
+        df = pl.DataFrame(
+            schema={
+                "cod_municipio": pl.String,
+                "cod_regiao_saude": pl.String,
+                "nome_regiao_saude": pl.String,
+                "cod_macrorregiao_saude": pl.String,
+                "nome_macrorregiao_saude": pl.String,
+            }
+        )
+    else:
+        df = pl.DataFrame(linhas, schema_overrides={
+            "cod_municipio": pl.String,
+            "cod_regiao_saude": pl.String,
+            "nome_regiao_saude": pl.String,
+            "cod_macrorregiao_saude": pl.String,
+            "nome_macrorregiao_saude": pl.String,
+        }).sort("cod_municipio")
+
+    return df, descartados
+
+
+def harmonizar(pasta: Path, municipios: pl.DataFrame) -> pl.DataFrame:
+    """Lê os arquivos baixados em `pasta`, extrai todos os registros e harmoniza contra `municipios`."""
+    pasta = Path(pasta)
+    manifesto = nucleo.ler_manifesto(pasta)
+
+    arquivos: list[str] = []
+    if manifesto:
+        for chave in sorted(manifesto.keys()):
+            arquivos.append(manifesto[chave]["arquivo"])
+    else:
+        arquivos = sorted(p.name for p in pasta.glob("regioes_saude_offset*.json.gz"))
+
+    todos_itens: list[dict[str, Any]] = []
+    for arquivo in arquivos:
+        conteudo = nucleo.ler_bruto(pasta, arquivo)
+        dados = json.loads(conteudo)
+        todos_itens.extend(dados.get(CHAVE_RESPOSTA, []))
+
+    df, descartados = processar_itens(todos_itens, municipios)
+    if descartados:
+        print(f"Aviso: {len(descartados)} registros da API sem correspondência na DTB descartados.")
+    return df