Metadata-Version: 2.4
Name: ibgepy
Version: 0.1.0
Summary: Access the IBGE Aggregate Data API (SIDRA) from Python
Project-URL: Homepage, https://github.com/StrategicProjects/ibgepy
Project-URL: Repository, https://github.com/StrategicProjects/ibgepy
Project-URL: Issues, https://github.com/StrategicProjects/ibgepy/issues
Project-URL: R package (ibger), https://github.com/StrategicProjects/ibger
Author-email: Andre Leite <leite@castlab.org>, Marcos Wasilew <marcos.wasilew@gmail.com>, Hugo Vasconcelos <hugo.vasconcelos@ufpe.br>, Carlos Amorin <carlos.agaf@ufpe.br>, Diogo Bezerra <diogo.bezerra@ufpe.br>
License: MIT License
        
        Copyright (c) 2026 ibgepy authors
        
        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.
License-File: LICENSE
Keywords: Brazil,IBGE,SIDRA,open-data,pandas,statistics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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
Requires-Python: >=3.9
Requires-Dist: pandas>=1.3
Requires-Dist: requests>=2.25
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: responses>=0.23; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Description-Content-Type: text/markdown

# ibgepy

[![PyPI](https://img.shields.io/pypi/v/ibgepy.svg)](https://pypi.org/project/ibgepy/)
[![Python versions](https://img.shields.io/pypi/pyversions/ibgepy.svg)](https://pypi.org/project/ibgepy/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**Access the IBGE Aggregate Data API (SIDRA) from Python.**

`ibgepy` is a pandas-friendly interface to the [IBGE aggregate data
API](https://servicodados.ibge.gov.br/api/docs/agregados?versao=3) of the
Brazilian Institute of Geography and Statistics (IBGE). Query aggregates,
variables, localities, periods, subjects, surveys and metadata from the
surveys and censuses conducted by IBGE — every fetch returns a
`pandas.DataFrame`.

This is the Python port of the R package
[`ibger`](https://github.com/StrategicProjects/ibger); the public function
names mirror the R API so knowledge transfers directly between the two.

## Installation

```bash
pip install ibgepy
```

Requires Python 3.9+, `requests` and `pandas`.

## Quick start

```python
import ibgepy

# IPCA in Brazil (aggregate 7060), last 6 periods
df = ibgepy.ibge_variables(7060, localities="BR")

# Specific variables for all states
ibgepy.ibge_variables(1705, variable=[284, 285], localities="N3")

# Specific municipalities (São Paulo, Rio) with a classification
ibgepy.ibge_variables(
    aggregate=1712,
    variable=214,
    periods=-3,
    localities={"N6": [3550308, 3304557]},
    classification={"226": [4844, 96608]},
)
```

The `value` column comes back as strings (IBGE uses special codes such as
`-`, `..`, `...`, `X`). Convert it with `parse_ibge_value`:

```python
df["value"] = ibgepy.parse_ibge_value(df["value"])
```

## Discover what to query

```python
ibgepy.ibge_aggregates(periodicity="P5")   # list monthly tables
ibgepy.ibge_metadata(7060)                  # full metadata for a table
ibgepy.ibge_periods(1705)                   # available periods
ibgepy.ibge_localities(1437, level="N6")    # localities at a level
ibgepy.ibge_subjects("internet")            # built-in subject-code lookup
```

`ibge_metadata()` returns an `IbgeMetadata` object whose `.variables` and
`.classifications` are DataFrames (the `categories` column holds a nested
DataFrame per classification).

## Survey catalog (Metadata API v2)

```python
ibgepy.ibge_surveys()                       # institutional survey catalog
ibgepy.ibge_survey_periods("SC")            # periods with metadata
ibgepy.ibge_survey_metadata("CD", year=2022)
```

## Coming from SIDRA URLs

Already have a SIDRA API URL (e.g. from the SIDRA Query Builder or the R
`sidrar` package)? Inspect or run it directly:

```python
url = "https://apisidra.ibge.gov.br/values/t/7060/n1/all/v/63/p/last%2012/c315/7169"

ibgepy.parse_sidra_url(url)   # human-readable breakdown + equivalent call
ibgepy.fetch_sidra_url(url)   # fetch as a tidy DataFrame
```

## Caching and messages

Metadata and the survey catalog are cached in memory per session. Clear it
with `ibgepy.ibge_clear_cache()`. Silence the progress/success messages with
`ibgepy.set_verbose(False)`.

## Public API

| Function | Purpose |
|----------|---------|
| `ibge_variables` | Fetch variable data (main function) |
| `ibge_aggregates` | List aggregates (tables) |
| `ibge_metadata` | Full aggregate metadata |
| `ibge_periods` | Available periods |
| `ibge_localities` | Localities at given levels |
| `ibge_subjects` | Built-in subject-code lookup |
| `ibge_surveys` / `ibge_survey_periods` / `ibge_survey_metadata` | Survey catalog (Metadata API v2) |
| `parse_ibge_value` | Convert IBGE value codes to numeric |
| `parse_sidra_url` / `fetch_sidra_url` | Translate/execute SIDRA URLs |
| `ibge_clear_cache` | Clear the in-memory cache |
| `set_verbose` | Toggle console messages |

## License

MIT — see [LICENSE](LICENSE). Developed by the ibgepy authors.
