ibgepy

PyPI Python versions License: MIT

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

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. Developed by the ibgepy authors.

Project links

Data verified by PyPI on Jul 8, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for milkway from gravatar.com milkway

Credits

Author: Andre Leite

GitHub Statistics

Data verified by PyPI on Jul 8, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT License)

Requires

Python >=3.9

Provides Extra

dev docs

Tags

Brazil IBGE SIDRA open-data pandas statistics

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ibgepy-0.2.0.tar.gz (32.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

ibgepy-0.2.0-py3-none-any.whl (32.2 kB view details)

Uploaded Python 3

File details

Details for the file ibgepy-0.2.0.tar.gz.

File metadata

  • Download URL: ibgepy-0.2.0.tar.gz
  • Upload date:
  • Size: 32.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for ibgepy-0.2.0.tar.gz
Algorithm Hash digest
SHA256 31fefd67c9a60de68cb5bb9648b06be6f795ccbac47af3147dc39a5871e94dd9
MD5 8ff280c93fdcd1ebf3e236062c3aef37
BLAKE2b-256 556807909d40d0cbf6ba9f65fe110aeb752e6c4de0f5c32b753b86278d350691

See more details on using hashes here.

Provenance

The following attestation bundles were made for ibgepy-0.2.0.tar.gz:

Publisher: publish.yml on StrategicProjects/ibgepy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ibgepy-0.2.0-py3-none-any.whl.

File metadata

  • Download URL: ibgepy-0.2.0-py3-none-any.whl
  • Upload date:
  • Size: 32.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for ibgepy-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f3d38cadb1c8c7ed2c77008192803f0e2a28159e2f38b270318359539c04d76a
MD5 278a41ff4845578a69d45c8d178ac8f2
BLAKE2b-256 a88dd0ecc3104dc6339ff77f356bd4d701f6e7207bd1f4452ccfeb0e87d7a96a

See more details on using hashes here.

Provenance

The following attestation bundles were made for ibgepy-0.2.0-py3-none-any.whl:

Publisher: publish.yml on StrategicProjects/ibgepy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page