ibgepy

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

ibgepy is a pandas-friendly interface to the IBGE aggregate data API 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; the public function names mirror the R API so knowledge transfers directly between the two.

Installation

pip install ibgepy

Requires Python 3.9+, requests and pandas.

Quick start

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:

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

Discover what to query

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)

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:

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

License

MIT © André Leite — see LICENSE.