IBGE Brazil Statistics Scraper

IBGE Brazil Statistics Scraper

Scrape official Brazilian statistics from the IBGE SIDRA database, from census data to economic indicators. Get localidades, aggregate metadata, observations, and period lists in one structured dataset. Export to CSV, JSON, Excel, or XML.

The IBGE SIDRA API is capable but its query syntax is complex and its endpoints return deeply nested JSON. This Actor reads the public catalogue directly, letting you pull Brazilian states, municipalities, statistical aggregates, and their observations by choosing a mode and an ID. It flattens every response into a clean row so you can work with IBGE data immediately.

Who uses it	What they scrape IBGE for
Economists	Pull monthly PNAD or IPCA data for a specific state to update a forecast model.
Data journalists	Fetch municipality-level census data to build a story on regional inequality.
Academic researchers	Collect historical aggregate observations for a longitudinal study on Brazilian demographics.
Real estate analysts	Scrape construction cost indices and population estimates by mesoregion for site selection.

What it does

This Actor collects official IBGE statistics by mode: localidades, aggregate catalogue, data observations, metadata, or available periods, and returns each record as a flat row.

• 🗺️ Localidades mode: fetch the official list of Brazilian states, municipalities, regions, mesoregions, or microregions.
• 📋 Aggregados mode: browse the full SIDRA catalogue of statistical aggregates, or look up a single aggregate by ID.
• 📊 Data mode: pull observations for one or more aggregates, filtered by period, variable, and territorial level.
• 🏷️ Metadata mode: get the variables, classifications, and measurement units that define an aggregate.
• 📅 Periods mode: list every available time period for an aggregate before you request its data.

Results export to CSV, JSON, Excel, or XML, or straight from the API.

What you can do with IBGE data

📈 Monitor inflation and employment.

An economist sets data mode with the IPCA aggregate ID, period 'all', and level N1 to get the monthly national inflation series for a dashboard.

🗳️ Map demographic shifts by municipality.

A researcher pulls the latest population estimates for every Brazilian municipality to update a demographic change map.

🏗️ Compare construction costs across regions.

A cost estimator fetches the SINAPI construction index for multiple states to adjust project budgets by location.

📰 Fact-check a public claim with official data.

A journalist scrapes a specific aggregate observation for a given year and state to verify a government statistic before publication.

Why choose this scraper

	What you get
No API key required	Reads the public IBGE SIDRA endpoints with no registration or authentication.
Flat, analysis-ready rows	Every response, from nested JSON to multi-level classifications, is normalized into one consistent schema.
Batch aggregate lookup	Pass up to 100 aggregate IDs in one run to fetch their data, metadata, or periods together.
Full territorial hierarchy	Request data at the Brazil, region, state, municipality, or mesoregion level with a single parameter.

How it compares

This Actor and the IBGE SIDRA Statistics actor both pull data from the official IBGE SIDRA catalogue, but they offer different workflows for accessing the same public endpoints.

Feature	ParseForge	IBGE SIDRA Statistics
Batch aggregate lookup (up to 100 IDs)	Yes	Not listed
Localidades mode (states, municipalities, regions)	Yes	Not listed
Periods mode (list available periods for an aggregate)	Yes	Yes
Metadata mode (variables and units for an aggregate)	Yes	Yes
Territorial level filter (N1 to N7)	Yes	Not listed

Configure the run

Drive the Actor by selecting a mode and providing an aggregate ID, a list of IDs, or a locality type. Filters for period, variable, and territorial level apply in data mode so only the observations you need reach your dataset. The Input tab lists every parameter.

A first run with the defaults:

{
 "mode": "aggregados",
 "localidadesType": "estados",
 "period": "all",
 "variable": "allxp",
 "level": "N3",
 "maxItems": 10
}

A larger pull:

{
 "mode": "aggregados",
 "localidadesType": "estados",
 "period": "all",
 "variable": "allxp",
 "level": "N3",
 "maxItems": 200
}

Pricing

Pay-per-result: $0.0375 per result collected. You pay only for the results written to your dataset.

Results collected	Approximate cost
100 results	$3.75
1,000 results	$37.50
10,000 results	$375.00

New Apify accounts start with $5 in free credit.

Free users

Free-plan runs return up to 10 results as a preview. Upgrade your Apify plan to collect up to 1,000,000 results per run.

Run it

1. Create a free Apify account with $5 in credit.
2. Open the IBGE Brazil Statistics Scraper.
3. Set your inputs and any filters, then click Start.
4. Export the results as CSV, Excel, JSON, or XML from the Dataset tab.

Run it programmatically through the Apify API (run-sync-get-dataset-items) or the ApifyClient for JavaScript and Python.

Use with AI agents (MCP)

Give an AI agent live access to IBGE through the Model Context Protocol. Add the Actor to Claude, Cursor, or any MCP client:

claude mcp add --transport http apify "https://mcp.apify.com?tools=parseforge/ibge-brazil-scraper"

Then prompt it in plain language to run the scraper and read back the results.

Troubleshooting

Why am I getting no results in data mode?

Check that your aggregate ID is correct by running 'aggregados' mode first. Also verify that the period code matches the format the API expects, like '2021' for a year or '202101' for a month.

The Actor returns an error about an invalid aggregate ID.

SIDRA aggregate IDs are numeric strings. Make sure you are not including letters or special characters. Use 'aggregados' mode to confirm the ID exists in the current catalogue.

I asked for municipality-level data but got state-level rows.

Set the 'level' field to 'N6' for municipality. The default is 'N3' (state). Each territorial level has a specific code: N1, N2, N3, N6, N7.

My run is taking a long time with 'all' periods.

Some aggregates have decades of monthly data. Set 'maxItems' to a reasonable limit, or narrow the request to a specific period code instead of 'all'.

I got a list of IDs from localidades mode but cannot use them in data mode.

Localidades mode returns geographic entity IDs for reference. Data mode uses the territorial level codes (N1, N2, N3, N6, N7) to filter observations, not the specific locality IDs.

FAQ

Question	Answer
What is IBGE SIDRA?	SIDRA is the IBGE's online statistical database. It holds thousands of aggregates covering population, economy, health, education, and prices for Brazil, its states, and its municipalities.
Do I need an API key to scrape IBGE data?	No. This Actor reads the public, unauthenticated SIDRA endpoints. You do not need to register an application or manage tokens.
How do I find the aggregate ID I need?	Run the Actor in 'aggregados' mode first. It returns the full catalogue with IDs and descriptions. You can also look up a single ID if you already know it.
Can I get data for more than one aggregate at a time?	Yes. Use the 'aggregateIds' field to pass a list of up to 100 SIDRA aggregate IDs. The Actor fetches data, metadata, or periods for all of them in one run.
What territorial levels are available?	You can request data at five levels: N1 (Brazil), N2 (region), N3 (state), N6 (municipality), and N7 (mesoregion).
How do I get all variables for an aggregate?	Set the 'variable' field to 'allxp' in data mode. This tells the SIDRA API to return every variable available for that aggregate.
What does 'localidades' mode return?	It returns the official IBGE list of geographic entities for the type you choose: states, municipalities, regions, mesoregions, or microregions, each with its ID and name.
Can I limit how many records the Actor collects?	Yes. Set 'maxItems' to any number between 1 and 1,000,000. The Actor stops after collecting that many rows.
What export formats are supported?	You can export your dataset in CSV, JSON, Excel, or XML from the Apify platform after the run finishes.
Is this Actor suitable for scraping the full Brazilian census?	Yes. The census data is published as SIDRA aggregates. Find the correct aggregate ID, set the territorial level and variables, and the Actor will pull the observations.

Related actors

Browse the full ParseForge collection for more scrapers.

🆘 Need help? Email parseforge@protonmail.com with your run ID, your input, and what you expected.

⚠️ Disclaimer. This Actor is unofficial and is not affiliated with, endorsed by, or sponsored by Instituto Brasileiro de Geografia e Estatística. It collects only publicly available data. You are responsible for using the collected data in compliance with the source's terms of service and applicable data-protection laws, including GDPR, CCPA, and PIPL. Do not use it to collect personal data unlawfully.