# IBGE SIDRA Statistics (`maximedupre/ibge`) Actor

Get public IBGE SIDRA catalogue entries, aggregate metadata, available periods, territorial references, and source-linked observations. Choose a focused workflow and download the records for research, reporting, or data pipelines.

- **URL**: https://apify.com/maximedupre/ibge.md
- **Developed by:** [Maxime Dupré](https://apify.com/maximedupre) (community)
- **Categories:** Business, Education, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $25.30 / 1,000 catalogue entries

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### 📊 Explore IBGE SIDRA statistics

Researchers, analysts, journalists, and developers can use IBGE SIDRA to collect public Brazilian statistics in a structured way. Choose a target and get source-linked catalogue entries, territorial references, aggregate metadata, available periods, or observations in a downloadable Apify dataset. This keeps official IDs, labels, values, periods, and source links together for research, reporting, and data pipelines.

- Pull public data for a **[SIDRA IBGE](https://apify.com/maximedupre/ibge/examples/sidra-ibge)** project and keep the source link with each row.
- Build a place lookup with **[IBGE Cidades](https://apify.com/maximedupre/ibge/examples/ibge-cidades)** and use official territory names and IDs.
- Collect a **[Censo IBGE](https://apify.com/maximedupre/ibge/examples/censo-ibge)** view for a population or territorial research task.
- Compare state-level public statistics with **[IBGE Estados](https://apify.com/maximedupre/ibge/examples/ibge-estados)** in a structured dataset.
- Organize source-linked rows for **[IBGE Datasets](https://apify.com/maximedupre/ibge/examples/ibge-datasets)** and downstream analysis.
- Look up official IDs with **[IBGE Code](https://apify.com/maximedupre/ibge/examples/ibge-code)** when you need to join Brazilian geography data.

#### 📚 Browse IBGE SIDRA records

Each saved row has a `recordType`, an official `sourceUrl`, and a `collectedAt` time. The other fields depend on the target. IBGE source modification time appears as `sourceModifiedAt` when the source publishes it.

**Catalogue entry**

| Field | Type | What it does |
|---|---|---|
| `recordType` | string | Identifies this row as `catalogueEntry`. |
| `aggregate.id` | string | Official SIDRA aggregate ID. |
| `aggregate.name` | string | Name of the aggregate when published. |
| `aggregate.subject` | string | Subject covered by the aggregate when published. |
| `sourceUrl` | string (URL) | Official IBGE source page for the entry. |
| `sourceModifiedAt` | string (date-time, optional) | Time the source last changed when IBGE publishes it. |
| `collectedAt` | string (date-time) | Time this row was collected. |

**Territorial reference**

| Field | Type | What it does |
|---|---|---|
| `recordType` | string | Identifies this row as `territorialReference`. |
| `territory.id` | string | Official IBGE territory ID. |
| `territory.name` | string | Official territory name. |
| `territory.level` | string | Territory level: state, municipality, region, mesoregion, or microregion. |
| `territory.abbreviation` | string (optional) | Official abbreviation when IBGE publishes one. |
| `territory.regionalContext.stateId` | string (optional) | ID of the related state. |
| `territory.regionalContext.stateName` | string (optional) | Name of the related state. |
| `territory.regionalContext.regionId` | string (optional) | ID of the related region. |
| `territory.regionalContext.regionName` | string (optional) | Name of the related region. |
| `territory.regionalContext.mesoregionId` | string (optional) | ID of the related mesoregion. |
| `territory.regionalContext.mesoregionName` | string (optional) | Name of the related mesoregion. |
| `territory.regionalContext.microregionId` | string (optional) | ID of the related microregion. |
| `territory.regionalContext.microregionName` | string (optional) | Name of the related microregion. |
| `sourceUrl` | string (URL) | Official IBGE source page for the territory. |
| `sourceModifiedAt` | string (date-time, optional) | Time the source last changed when IBGE publishes it. |
| `collectedAt` | string (date-time) | Time this row was collected. |

**Example row**

```json
{
  "recordType": "territorialReference",
  "territory": {
    "id": "1101",
    "name": "Madeira-Guaporé",
    "level": "mesoregion",
    "regionalContext": {
      "mesoregionId": "1101",
      "mesoregionName": "Madeira-Guaporé",
      "stateId": "11",
      "stateName": "Rondônia",
      "regionId": "1",
      "regionName": "Norte"
    }
  },
  "sourceUrl": "https://servicodados.ibge.gov.br/api/v1/localidades/mesorregioes",
  "collectedAt": "2026-08-12T18:51:46.496Z"
}
```

**Aggregate metadata**

| Field | Type | What it does |
|---|---|---|
| `recordType` | string | Identifies this row as `aggregateMetadata`. |
| `aggregate.id` | string | Official SIDRA aggregate ID. |
| `aggregate.name` | string | Name of the aggregate when published. |
| `aggregate.subject` | string | Subject covered by the aggregate when published. |
| `variables` | object\[] | Variables published for the aggregate. |
| `variables[].id` | string | Official variable ID. |
| `variables[].name` | string | Variable label. |
| `variables[].unit` | string | Unit used by the variable. |
| `classifications` | object\[] | Classifications published for the aggregate. |
| `classifications[].id` | string | Official classification ID. |
| `classifications[].name` | string | Classification label. |
| `supportedTerritorialLevels` | string\[] | Territorial levels supported by the aggregate. |
| `frequency` | string | Publication frequency when available. |
| `sourceUrl` | string (URL) | Official IBGE source page for the metadata. |
| `sourceModifiedAt` | string (date-time, optional) | Time the source last changed when IBGE publishes it. |
| `collectedAt` | string (date-time) | Time this row was collected. |

**Example row**

```json
{
  "recordType": "aggregateMetadata",
  "aggregate": {
    "id": "4714",
    "name": "População Residente, Área territorial e Densidade demográfica",
    "subject": "Território"
  },
  "variables": [
    {
      "id": "93",
      "name": "População residente",
      "unit": "Pessoas"
    },
    {
      "id": "6318",
      "name": "Área da unidade territorial",
      "unit": "Quilômetros quadrados"
    },
    {
      "id": "614",
      "name": "Densidade demográfica",
      "unit": "Habitante por quilômetro quadrado"
    }
  ],
  "classifications": [],
  "supportedTerritorialLevels": [
    "region",
    "municipality",
    "state"
  ],
  "frequency": "anual",
  "sourceUrl": "https://sidra.ibge.gov.br/tabela/4714",
  "collectedAt": "2026-08-12T18:51:45.775Z"
}
```

**Available period**

| Field | Type | What it does |
|---|---|---|
| `recordType` | string | Identifies this row as `availablePeriod`. |
| `aggregate.id` | string | Official SIDRA aggregate ID. |
| `aggregate.name` | string | Name of the aggregate when published. |
| `aggregate.subject` | string | Subject covered by the aggregate when published. |
| `period` | string | Period available for the aggregate. |
| `sourceUrl` | string (URL) | Official IBGE source page for the period. |
| `sourceModifiedAt` | string (date-time, optional) | Time the source last changed when IBGE publishes it. |
| `collectedAt` | string (date-time) | Time this row was collected. |

**Example row**

```json
{
  "recordType": "availablePeriod",
  "aggregate": {
    "id": "4714",
    "name": "População Residente, Área territorial e Densidade demográfica",
    "subject": "Território"
  },
  "period": "2022",
  "sourceUrl": "https://sidra.ibge.gov.br/tabela/4714",
  "sourceModifiedAt": "2026-05-07T00:00:00.000Z",
  "collectedAt": "2026-08-12T18:51:45.342Z"
}
```

**Observation**

| Field | Type | What it does |
|---|---|---|
| `recordType` | string | Identifies this row as `observation`. |
| `aggregate.id` | string | Official SIDRA aggregate ID. |
| `aggregate.name` | string | Name of the aggregate when published. |
| `aggregate.subject` | string | Subject covered by the aggregate when published. |
| `variable.id` | string | Official variable ID. |
| `variable.name` | string | Variable label. |
| `variable.unit` | string | Unit used for the value. |
| `territory.id` | string | Official territory ID. |
| `territory.name` | string | Territory name. |
| `territory.level` | string | Territory level. |
| `territory.abbreviation` | string (optional) | Official abbreviation when IBGE publishes one. |
| `territory.regionalContext.stateId` | string (optional) | ID of the related state. |
| `territory.regionalContext.stateName` | string (optional) | Name of the related state. |
| `territory.regionalContext.regionId` | string (optional) | ID of the related region. |
| `territory.regionalContext.regionName` | string (optional) | Name of the related region. |
| `territory.regionalContext.mesoregionId` | string (optional) | ID of the related mesoregion. |
| `territory.regionalContext.mesoregionName` | string (optional) | Name of the related mesoregion. |
| `territory.regionalContext.microregionId` | string (optional) | ID of the related microregion. |
| `territory.regionalContext.microregionName` | string (optional) | Name of the related microregion. |
| `period` | string | Period for the observation. |
| `value` | number | Numeric value published by IBGE. |
| `valueOriginal` | string (optional) | Original source representation of the value when available. |
| `sourceUrl` | string (URL) | Official IBGE source page for the observation. |
| `sourceModifiedAt` | string (date-time, optional) | Time the source last changed when IBGE publishes it. |
| `collectedAt` | string (date-time) | Time this row was collected. |

**Example row**

```json
{
  "recordType": "observation",
  "aggregate": {
    "id": "4714",
    "name": "População Residente, Área territorial e Densidade demográfica",
    "subject": "Território"
  },
  "variable": {
    "id": "93",
    "name": "População residente",
    "unit": "Pessoas"
  },
  "territory": {
    "id": "11",
    "name": "Rondônia",
    "level": "state"
  },
  "period": "2022",
  "value": 1581196,
  "valueOriginal": "1581196",
  "sourceUrl": "https://sidra.ibge.gov.br/tabela/4714",
  "sourceModifiedAt": "2026-05-07T00:00:00.000Z",
  "collectedAt": "2026-08-12T18:48:26.213Z"
}
```

#### ▶️ Run an IBGE SIDRA lookup

**Run steps**

1. Pick one target in the input form.
2. Add aggregate IDs for metadata, periods, or observations. You can send up to 100 IDs for these targets.
3. Add periods, variable IDs, or territorial levels when you want a narrower observation scope.
4. Start the run and open the returned dataset after it finishes.

**What the run does**

One run covers one coherent target. An aggregate ID list is a same-kind batch for supported targets, not several separate workflows. The Actor reads public IBGE data and saves eligible rows with a source URL and collection time. Fields for another target stay visible in the form but are ignored.

**Access**

You do not need to provide a source credential. The successful run dataset stays available through the `datasetUrl` output link.

#### ⚙️ Input

Fields for another target stay visible but are ignored. Leave `periods`, `variableIds`, or `territorialLevels` empty to use all available values for the selected target. A broad empty scope can return all available results until the source is exhausted.

**Input fields**

| Field | Type | What it does |
|---|---|---|
| `target` | string | Required. Choose `catalogue`, `territorialReference`, `aggregateMetadata`, `availablePeriods`, or `observations`. |
| `periods` | string\[] | For observations, select one or more published periods. Leave empty to use all available periods. Other targets ignore this field. |
| `variableIds` | string\[] | For observations, select one or more variable IDs. Leave empty to use all available variables. Other targets ignore this field. |
| `aggregateIds` | string\[] | For aggregate metadata, available periods, or observations, enter one or more numeric SIDRA IDs. Up to 100 IDs are allowed. Other targets ignore this field. |
| `territorialLevels` | string\[] | For territorial references or observations, choose states, municipalities, regions, mesoregions, or microregions. Leave empty to use all available levels for the selected target. Other targets ignore this field. |

**Example input**

```json
{
  "target": "observations",
  "aggregateIds": [
    "4714"
  ],
  "periods": [
    "2022"
  ],
  "variableIds": [
    "93"
  ],
  "territorialLevels": [
    "states"
  ]
}
```

#### 🧾 Output

**Run output**

| Field | Type | What it does |
|---|---|---|
| `datasetUrl` | string (URL) | Link to the successful IBGE SIDRA records from this run. |

The dataset contains one row for each returned source item. The tables above describe the complete fields for each row shape, including nested fields such as `aggregate.id` and `territory.regionalContext.regionName`.

#### 💳 Pricing

**Pay per saved shape**

This Actor uses pay-per-event pricing. Successful saved rows use the buyer-facing event for their shape:

| Event | Charged for |
|---|---|
| Catalogue entry | One successful catalogue entry with its ID, name, subject, and source link. |
| Observation | One successful observation for its aggregate, period, variable, and territorial level. |
| Territory | One successful territory with its ID, name, level, and regional context when available. |
| Aggregate metadata | One successful aggregate metadata entry with its variables and units. |
| Available period | One successful available period for an aggregate. |

The Store Pricing panel shows the current tier prices. This page does not state a charge for setup, diagnostic, empty, or no-result work.

#### 🔌 Integrations

**Dataset workflow**

Download the run dataset from Apify and pass the structured rows to your research, reporting, or data pipeline after the run.

**Video guide**

https://www.youtube.com/watch?v=bNACk1\_S\_6w\&list=PLObrtcm1Kw6MUrlLNDbK9QRg8VDJg0gOW\&index=4

#### ❓ FAQ

##### Which target returns measured values?

Choose `observations` when you need a value for an aggregate, period, variable, and territorial level. The row includes the numeric value and its original source representation when available.

##### Which target tells me what an aggregate contains?

Choose `aggregateMetadata` to get its variables and units. The row can also include classifications, supported territorial levels, and frequency when published.

##### Can I see available periods before collecting observations?

Yes. Choose `availablePeriods` and provide the aggregate IDs. The result lists periods with a source modification time when IBGE publishes one.

##### What happens when I leave a scope list empty?

An empty `periods`, `variableIds`, or `territorialLevels` list uses all values available for the selected target. The run continues until the source is exhausted.

##### Can one run combine several targets?

No. One run covers one target. You can send a simple list of up to 100 aggregate IDs for the supported aggregate-oriented targets, but you cannot combine catalogue, territory, metadata, periods, and observations in one run.

##### Do I need an IBGE API key?

No source credential is required in the input. The Actor uses the supported public IBGE workflows.

##### Can I verify a returned value?

Yes. Each returned row includes an official `sourceUrl`, and it can include `sourceModifiedAt` when IBGE publishes that time. `collectedAt` tells you when the Actor fetched the row.

##### Does the Actor calculate forecasts or custom statistics?

No. It returns published IBGE catalogue, territorial, metadata, period, and observation records. It does not add forecasts, custom calculations, or interpretations.

### 📝 Changelog

**0.0: Initial release**

### 🆘 Support

For issues, questions, or feature requests, [file a ticket](https://console.apify.com/actors/maximedupre~ibge/issues) and I'll fix or implement it in less than 24h 🫡

### 🔗 Related Actors

- **[IBGE Brazil Official Statistics Scraper](https://apify.com/parseforge/ibge-brazil-scraper)** helps when you need a broader IBGE public API workflow with states, municipalities, catalogue data, metadata, or observations.
- **[INE Portugal Statistics Scraper](https://apify.com/parseforge/ine-portugal-scraper)** helps you collect official Portuguese indicator metadata or data series for comparison.
- **[INE Spain (Instituto Nacional de Estadistica) Scraper](https://apify.com/parseforge/ine-spain-scraper)** helps you browse Spanish statistical operations and pull labelled observations.
- **[Statistics Canada Web Data Service Scraper](https://apify.com/parseforge/statistics-canada-scraper)** helps you explore Canadian catalogue metadata, geography, frequencies, and time-series observations.
- **[ONS UK Statistics Beta API Scraper](https://apify.com/parseforge/ons-uk-scraper)** helps you collect UK dataset catalogues, metadata, editions, versions, and observations.

**Made with ❤️ by Maxime Dupré**

# Actor input Schema

## `target` (type: `string`):

Choose the public IBGE SIDRA data to return.

## `periods` (type: `array`):

For Observation data, enter one or more periods published by the selected aggregate. Leave empty to use all available periods. Other targets ignore this field.

## `variableIds` (type: `array`):

For Observation data, enter one or more variable IDs from the selected aggregate. Leave empty to use all available variables. Other targets ignore this field.

## `aggregateIds` (type: `array`):

Enter one or more SIDRA aggregate IDs for Aggregate metadata, Available periods, or Observation data. Enter up to 100 IDs. SIDRA aggregate catalogue and Territorial reference ignore this field.

## `territorialLevels` (type: `array`):

Choose one or more levels for Territorial reference or Observation data. Leave empty to use all levels available for the selected target. Other targets ignore this field.

## Actor input object example

```json
{
  "target": "observations",
  "periods": [
    "2022"
  ],
  "variableIds": [
    "93"
  ],
  "aggregateIds": [
    "4714"
  ],
  "territorialLevels": [
    "states"
  ]
}
```

# Actor output Schema

## `datasetUrl` (type: `string`):

Download the successful IBGE SIDRA records from this run.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "target": "observations",
    "periods": [
        "2022"
    ],
    "variableIds": [
        "93"
    ],
    "aggregateIds": [
        "4714"
    ],
    "territorialLevels": [
        "states"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("maximedupre/ibge").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "target": "observations",
    "periods": ["2022"],
    "variableIds": ["93"],
    "aggregateIds": ["4714"],
    "territorialLevels": ["states"],
}

# Run the Actor and wait for it to finish
run = client.actor("maximedupre/ibge").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "target": "observations",
  "periods": [
    "2022"
  ],
  "variableIds": [
    "93"
  ],
  "aggregateIds": [
    "4714"
  ],
  "territorialLevels": [
    "states"
  ]
}' |
apify call maximedupre/ibge --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,maximedupre/ibge"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/tevTC9kzZMUh5dAp8/builds/6V59W8PLEakRXl5t9/openapi.json