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 © André Leite — see LICENSE.

Project links

Data verified by PyPI on Jul 14, 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:
Latest release

1 maintainer

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

Credits

Author: André Leite

GitHub Statistics

Data verified by PyPI on Jul 14, 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.1.tar.gz (32.8 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.1-py3-none-any.whl (32.2 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: ibgepy-0.2.1.tar.gz
  • Upload date:
  • Size: 32.8 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.1.tar.gz
Algorithm Hash digest
SHA256 5d756c79862f87b1f70726ad503f21eb190b934029d7ed7cab18c47f843b6ffb
MD5 8b5f7e6f09c733f7f5a38162bdeaea84
BLAKE2b-256 2c7a7692622d5f5c5e0486ec886d67963974ebdc8e731bf89bc4dcb4a07fb7f9

See more details on using hashes here.

Provenance

The following attestation bundles were made for ibgepy-0.2.1.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.1-py3-none-any.whl.

File metadata

  • Download URL: ibgepy-0.2.1-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.1-py3-none-any.whl
Algorithm Hash digest
SHA256 cb8207160dc7838a00b4fc31d4d7ca2e4612d6e6028d67234a1da927076b6503
MD5 839be78ee498dc2a863bfe0426469082
BLAKE2b-256 3b396b64c07abad7daed748f4826f75d9063f33af85894cd27a4d4b254062e95

See more details on using hashes here.

Provenance

The following attestation bundles were made for ibgepy-0.2.1-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