# IBGE

> Look up Brazil's official statistics from IBGE, the national statistics institute. Find states and municipalities with their IBGE codes and regions; see how common a first name is by decade and state; follow IBGE's news, new figures and release calendar; search and fetch any SIDRA statistics table, such as population estimates or IPCA inflation; compare countries on IBGE's indicators; and look up CNAE business activity codes. Everything reads: nothing here changes anything. No account or API key required.

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/ibge

## Actions

### Compare a name across states

See how common a first name is in each of the 27 states, as people per 100,000, most common first, from the 2010 census. Use it to find where a name is a regional favourite.

**Inputs**

- First name (`name`, text, required): One first name, such as Maria. Accents and capitals do not matter. IBGE counts single names only, so a compound name such as Maria Clara is refused.
- Sex (`sex`, text): Only women or only men. Leave it empty for everyone. One of: `F` (Women), `M` (Men).

**Outputs**

- `count` (number): How many states are in the result
- `found` (true/false): False when the census records nobody with the name
- `highest_state` (text): The state where the name is most common
- `lowest_state` (text): The state where it is least common
- `name` (text): The name, in capitals
- `searched_for` (text): The name that was looked up
- `sex` (text): F or M when narrowed to women or men, else empty
- `states` (list): One row per state, most common first

**Example output**

```json
{
  "count": 3,
  "found": true,
  "highest_state": "Cear\u00e1",
  "lowest_state": "Rio Grande do Sul",
  "name": "ANA",
  "searched_for": "Ana",
  "sex": "",
  "states": [
    {
      "count": 182135,
      "per_100k": 2154.84,
      "population": 8452381,
      "state_code": "CE",
      "state_id": 23,
      "state_name": "Cear\u00e1"
    },
    {
      "count": 49963,
      "per_100k": 1943.96,
      "population": 2570160,
      "state_code": "DF",
      "state_id": 53,
      "state_name": "Distrito Federal"
    },
    {
      "count": 60148,
      "per_100k": 1898.59,
      "population": 3168027,
      "state_code": "RN",
      "state_id": 24,
      "state_name": "Rio Grande do Norte"
    }
  ]
}
```

### Get a CNAE activity

Look up a CNAE code, the classification of economic activities every Brazilian company registers under, and get its name, the class, group, division and section above it, the activities filed under it and IBGE's notes on what it covers and excludes. Takes a subclass such as 6201-5/01 or a class such as 62.01-5.

**Inputs**

- CNAE code (`code`, text, required): The code, with or without its dots, dash and slash: 6201-5/01 and 6201501 are the same subclass.

**Outputs**

- `activities` (list): The activities filed under a subclass
- `class_code` (text): The class code
- `class_name` (text): The class name
- `code` (text): The code as digits
- `description` (text): Its name, in Portuguese
- `division_code` (text): The division code
- `division_name` (text): The division name
- `formatted_code` (text): The code as it is usually written
- `group_code` (text): The group code
- `group_name` (text): The group name
- `kind` (text): subclass for a 7-digit code, class for a 5-digit one
- `notes` (list): IBGE's notes on what it covers and excludes
- `section_code` (text): The section letter, A to U
- `section_name` (text): The section name

**Example output**

```json
{
  "activities": [
    "BANCO DE DADOS SOB ENCOMENDA; DESENVOLVIMENTO DE",
    "CRIA\u00c7\u00c3O, CONFIGURA\u00c7\u00c3O DE SOFTWARE DE BANCO DE DADOS SOB ENCOMENDA",
    "DESENVOLVIMENTO DE APLICATIVO INFORM\u00c1TICO SOB ENCOMENDA"
  ],
  "class_code": "62015",
  "class_name": "DESENVOLVIMENTO DE PROGRAMAS DE COMPUTADOR SOB ENCOMENDA",
  "code": "6201501",
  "description": "DESENVOLVIMENTO DE PROGRAMAS DE COMPUTADOR SOB ENCOMENDA",
  "division_code": "62",
  "division_name": "ATIVIDADES DOS SERVI\u00c7OS DE TECNOLOGIA DA INFORMA\u00c7\u00c3O",
  "formatted_code": "6201-5/01",
  "group_code": "620",
  "group_name": "ATIVIDADES DOS SERVI\u00c7OS DE TECNOLOGIA DA INFORMA\u00c7\u00c3O",
  "kind": "subclass",
  "notes": [
    "Esta subclasse compreende o desenvolvimento de sistemas para atender \u00e0s necessidades do cliente e a programa\u00e7\u00e3o com o uso de ferramentas e de linguagens de programa\u00e7\u00e3o"
  ],
  "section_code": "J",
  "section_name": "INFORMA\u00c7\u00c3O E COMUNICA\u00c7\u00c3O"
}
```

### Get a country profile

Get IBGE's profile of any country: its codes, its name in Portuguese, English and Spanish, capital, area, region, languages, currencies and a short history in Portuguese.

**Inputs**

- Country (`country`, text, required): The country. Pick it from the list, or give its two- or three-letter code such as AR or ARG.

**Outputs**

- `area_km2` (number): The area in square kilometres
- `capital` (text): The capital
- `code` (text): The ISO two-letter code, such as BR
- `currencies` (list): Its currencies
- `history` (text): IBGE's short history of the country, in Portuguese
- `intermediate_region` (text): The UN intermediate region, empty when none
- `iso3` (text): The ISO three-letter code, such as BRA
- `languages` (list): Its languages, in Portuguese
- `m49` (number): The UN M49 number
- `name` (text): The name in Portuguese
- `name_en` (text): The name in English
- `name_es` (text): The name in Spanish
- `region` (text): The continent, in Portuguese
- `subregion` (text): The UN subregion, in Portuguese

**Example output**

```json
{
  "area_km2": 8509360.85,
  "capital": "Bras\u00edlia",
  "code": "BR",
  "currencies": [
    {
      "code": "BRL",
      "name": "Real brasileiro"
    }
  ],
  "history": "Maior pa\u00eds da Am\u00e9rica do Sul, com vasta \u00e1rea de litoral banhada pelo oceano Atl\u00e2ntico. Tem fronteiras com Venezuela, Guiana, Suriname, Guiana Francesa, Col\u00f4mbia, Peru, Bol\u00edvia, Paraguai, Argentina e U",
  "intermediate_region": "Am\u00e9rica do sul",
  "iso3": "BRA",
  "languages": [
    "portugu\u00eas"
  ],
  "m49": 76,
  "name": "Brasil",
  "name_en": "Brazil",
  "name_es": "Brasil",
  "region": "Am\u00e9rica",
  "subregion": "Am\u00e9rica Latina e Caribe"
}
```

### Get a municipality

Look up one municipality by its code or its name and get its 7-digit IBGE code, its state and region, and the intermediate, immediate, meso and micro regions it sits in. A name several states share is refused with the states it was found in, rather than guessed.

**Inputs**

- State (`state`, text): The state the municipality is in. It fills the municipality list, and tells two places with the same name apart. Leave it empty when you give the municipality's code. One of: `AC` (Acre (AC)), `AL` (Alagoas (AL)), `AP` (Amapá (AP)), `AM` (Amazonas (AM)), `BA` (Bahia (BA)), `CE` (Ceará (CE)), `DF` (Distrito Federal (DF)), `ES` (Espírito Santo (ES)), `GO` (Goiás (GO)), `MA` (Maranhão (MA)), and 17 more.
- Municipality (`municipality`, text, required): The municipality. Choose the state to pick it from the list, or give IBGE's 7-digit code (3304557 is Rio de Janeiro), the 6-digit code some other systems use, or its name. Accents and capitals do not matter.

**Outputs**

- `id` (number): IBGE's 7-digit code for the municipality, such as 3304557
- `immediate_region_id` (number): IBGE's code for its immediate geographic region
- `immediate_region_name` (text): The immediate geographic region's name
- `intermediate_region_id` (number): IBGE's code for its intermediate geographic region
- `intermediate_region_name` (text): The intermediate geographic region's name
- `mesoregion_id` (number): IBGE's code for its mesoregion (the older division), empty for a municipality created after mesoregions were drawn
- `mesoregion_name` (text): The mesoregion's name, empty when it has none
- `microregion_id` (number): IBGE's code for its microregion (the older division), empty for a municipality created after microregions were drawn
- `microregion_name` (text): The microregion's name, empty when it has none
- `name` (text): The municipality's name
- `region_code` (text): Its region's abbreviation: N, NE, SE, S or CO
- `region_name` (text): Its region's name in Portuguese
- `searched_for` (text): What was looked up
- `state_code` (text): Its state's two-letter abbreviation
- `state_id` (number): IBGE's two-digit code for its state
- `state_name` (text): Its state's name

**Example output**

```json
{
  "id": 3303302,
  "immediate_region_id": 330001,
  "immediate_region_name": "Rio de Janeiro",
  "intermediate_region_id": 3301,
  "intermediate_region_name": "Rio de Janeiro",
  "mesoregion_id": 3306,
  "mesoregion_name": "Metropolitana do Rio de Janeiro",
  "microregion_id": 33018,
  "microregion_name": "Rio de Janeiro",
  "name": "Niter\u00f3i",
  "region_code": "SE",
  "region_name": "Sudeste",
  "searched_for": "3303302",
  "state_code": "RJ",
  "state_id": 33,
  "state_name": "Rio de Janeiro"
}
```

### Get a name's frequency by decade

Find out how many people in Brazil, a state or a municipality have a first name, decade by decade of birth, from the 2010 census, and which decade it peaked in. Use it to estimate someone's age from their name or to see a name rise and fall.

**Inputs**

- First name (`name`, text, required): One first name, such as Maria. Accents and capitals do not matter. IBGE counts single names only, so a compound name such as Maria Clara is refused.
- State (`state`, text): Only people in this state. Leave it empty for all of Brazil. One of: `AC` (Acre (AC)), `AL` (Alagoas (AL)), `AP` (Amapá (AP)), `AM` (Amazonas (AM)), `BA` (Bahia (BA)), `CE` (Ceará (CE)), `DF` (Distrito Federal (DF)), `ES` (Espírito Santo (ES)), `GO` (Goiás (GO)), `MA` (Maranhão (MA)), and 17 more.
- Municipality (`municipality`, text): Only people in this municipality. Choose the state to pick it from the list, or give its 7-digit code. Leave it empty for the whole state or country.
- Sex (`sex`, text): Only women or only men. Leave it empty for everyone. One of: `F` (Women), `M` (Men).

**Outputs**

- `decades` (list): One row per decade of birth, oldest first
- `found` (true/false): False when the census records nobody with the name
- `location_id` (text): BR, or IBGE's code for the state or municipality
- `location_name` (text): Where the people were counted
- `name` (text): The name as IBGE records it, in capitals without accents
- `peak_count` (number): How many were born in that decade
- `peak_decade` (text): The decade with the most births, such as 1950s
- `searched_for` (text): The name that was looked up
- `sex` (text): F or M when narrowed to women or men, else empty
- `total` (number): How many people have the name, across every decade

**Example output**

```json
{
  "decades": [
    {
      "count": 32373,
      "decade": "before_1930",
      "from_year": null,
      "label": "Before 1930",
      "to_year": 1929
    },
    {
      "count": 69578,
      "decade": "1930s",
      "from_year": 1930,
      "label": "1930s",
      "to_year": 1939
    },
    {
      "count": 126572,
      "decade": "1940s",
      "from_year": 1940,
      "label": "1940s",
      "to_year": 1949
    },
    {
      "count": 188459,
      "decade": "1950s",
      "from_year": 1950,
      "label": "1950s",
      "to_year": 1959
    },
    {
      "count": 143828,
      "decade": "1960s",
      "from_year": 1960,
      "label": "1960s",
      "to_year": 1969
    },
    {
      "count": 65015,
      "decade": "1970s",
      "from_year": 1970,
      "label": "1970s",
      "to_year": 1979
    },
    {
      "count": 27944,
      "decade": "1980s",
      "from_year": 1980,
      "label": "1980s",
      "to_year": 1989
    },
    {
      "count": 17632,
      "decade": "1990s",
      "from_year": 1990,
      "label": "1990s",
      "to_year": 1999
    },
    {
      "count": 78126,
      "decade": "2000s",
      "from_year": 2000,
      "label": "2000s",
      "to_year": 2009
    }
  ],
  "found": true,
  "location_id": "33",
  "location_name": "Rio de Janeiro",
  "name": "MARIA",
  "peak_count": 188459,
  "peak_decade": "1950s",
  "searched_for": "Maria",
  "sex": "F",
  "total": 749527
}
```

### Get a table's details

Read what a SIDRA table holds: its survey, how often it is updated and over which periods, the variables it measures with their units, the kinds of place it covers, and the classifications that break its figures down.

**Inputs**

- Table (`table`, text, required): The SIDRA table's number, such as 6579 for the population estimates or 1737 for the IPCA inflation series. It is in the table's address on sidra.ibge.gov.br, and 'Search statistics tables' finds one.

**Outputs**

- `classifications` (list): How its figures are broken down, if at all
- `first_period` (text): The first period it has figures for
- `frequency` (text): How often it is updated, in Portuguese, such as mensal
- `id` (number): The table's number
- `last_period` (text): The latest period it has figures for
- `levels` (list): The kinds of place it has figures for
- `name` (text): The table's title, in Portuguese
- `subject` (text): Its subject, in Portuguese
- `survey` (text): The survey it belongs to
- `url` (text): The table on SIDRA
- `variables` (list): What it measures

**Example output**

```json
{
  "classifications": [],
  "first_period": "2001",
  "frequency": "anual",
  "id": 6579,
  "last_period": "2026",
  "levels": [
    {
      "id": "N1",
      "name": "Brasil"
    },
    {
      "id": "N2",
      "name": "Grande Regi\u00e3o"
    },
    {
      "id": "N6",
      "name": "Munic\u00edpio"
    },
    {
      "id": "N3",
      "name": "Unidade da Federa\u00e7\u00e3o"
    }
  ],
  "name": "Popula\u00e7\u00e3o residente estimada",
  "subject": "Geral",
  "survey": "Estimativas de Popula\u00e7\u00e3o",
  "url": "https://sidra.ibge.gov.br/tabela/6579",
  "variables": [
    {
      "id": 9324,
      "name": "Popula\u00e7\u00e3o residente estimada",
      "unit": "Pessoas"
    }
  ]
}
```

### Get country indicators

Compare countries on IBGE's indicators, such as GDP per capita, population, life expectancy, internet use or exports: the latest figure and its whole series for each country and indicator. IBGE has no figures for a few countries, such as Argentina, and the result names them.

**Inputs**

- Countries (`countries`, list, required): The countries to compare. Pick as many as you like.
- Indicators (`indicators`, list): Which indicators. Leave it empty for all 34.

**Outputs**

- `count` (number): How many rows there are
- `countries` (list): The two-letter codes of the countries read
- `countries_without_figures` (list): Countries IBGE has no figures for, such as Argentina, whose rows come back empty
- `indicators` (list): One row per country and indicator

**Example output**

```json
{
  "count": 1,
  "countries": [
    "BR"
  ],
  "countries_without_figures": [],
  "indicators": [
    {
      "country": "Brasil",
      "country_code": "BR",
      "indicator": "Economia - PIB per capita",
      "indicator_id": 77823,
      "latest_period": "2023",
      "latest_value": 10294.87,
      "multiplier": 1,
      "series": [
        {
          "period": "2021",
          "value": 7972.54
        },
        {
          "period": "2022",
          "value": 9281.33
        },
        {
          "period": "2023",
          "value": 10294.87
        }
      ],
      "unit": "US$"
    }
  ]
}
```

### Get values from a table

Fetch figures from a SIDRA table: the latest population of every municipality in a state, the last twelve months of inflation, a harvest by crop. Choose the variables, the kind of place and which places, the periods (or just the latest), and the categories. Every figure comes back as its own row with a number ready to compare. A step returns at most 10,000 figures.

**Inputs**

- Table (`table`, text, required): The SIDRA table's number, such as 6579 for the population estimates or 1737 for the IPCA inflation series. It is in the table's address on sidra.ibge.gov.br, and 'Search statistics tables' finds one.
- Variables (`variables`, list): What to fetch. Leave it empty for every variable in the table.
- Kind of place (`level`, text): Brazil, regions, states, municipalities, and so on: the list holds the ones this table covers. Leave it empty for Brazil as a whole.
- Places (`locations`, list): Which places of that kind. Leave it empty for all of them, or for all of them in the state chosen below.
- Only in state (`state`, text): Only places in this state, such as every municipality in RJ. Leave it empty for all of Brazil. One of: `AC` (Acre (AC)), `AL` (Alagoas (AL)), `AP` (Amapá (AP)), `AM` (Amazonas (AM)), `BA` (Bahia (BA)), `CE` (Ceará (CE)), `DF` (Distrito Federal (DF)), `ES` (Espírito Santo (ES)), `GO` (Goiás (GO)), `MA` (Maranhão (MA)), and 17 more.
- Periods (`periods`, list): Which periods. Leave it empty to get the latest ones instead, as many as the next field says.
- Latest periods (`latest`, number): When no periods are chosen, how many of the most recent to fetch. Defaults to 1, the latest. From 1 to 120. Default: `1`.
- Break down by (`classification`, text): A classification to break the figures down by, such as product group for the IPCA. Leave it empty for the table's totals.
- Categories (`categories`, list): Which categories of that classification. Leave it empty for every one.

**Outputs**

- `classification` (text): The classification broken down by, else empty
- `count` (number): How many figures were returned
- `level` (text): The kind of place, such as N3 for states
- `periods` (list): The periods the figures are for
- `table_id` (number): The table's number
- `table_name` (text): The table's title
- `values` (list): One row per figure

**Example output**

```json
{
  "classification": "",
  "count": 2,
  "level": "N3",
  "periods": [
    "2026"
  ],
  "table_id": 6579,
  "table_name": "Popula\u00e7\u00e3o residente estimada",
  "values": [
    {
      "category": "",
      "category_id": "",
      "level": "N3",
      "location": "Rio de Janeiro",
      "location_id": "33",
      "period": "2026",
      "period_label": "2026",
      "unit": "Pessoas",
      "value": 17225410,
      "value_text": "17225410",
      "variable": "Popula\u00e7\u00e3o residente estimada",
      "variable_id": 9324
    },
    {
      "category": "",
      "category_id": "",
      "level": "N3",
      "location": "S\u00e3o Paulo",
      "location_id": "35",
      "period": "2026",
      "period_label": "2026",
      "unit": "Pessoas",
      "value": 46179008,
      "value_text": "46179008",
      "variable": "Popula\u00e7\u00e3o residente estimada",
      "variable_id": 9324
    }
  ]
}
```

### List a municipality's districts

List the districts a municipality is divided into, with IBGE's 9-digit code for each. São Paulo has 96; most small municipalities have one, named after the town.

**Inputs**

- State (`state`, text): The state the municipality is in. It fills the municipality list, and tells two places with the same name apart. Leave it empty when you give the municipality's code. One of: `AC` (Acre (AC)), `AL` (Alagoas (AL)), `AP` (Amapá (AP)), `AM` (Amazonas (AM)), `BA` (Bahia (BA)), `CE` (Ceará (CE)), `DF` (Distrito Federal (DF)), `ES` (Espírito Santo (ES)), `GO` (Goiás (GO)), `MA` (Maranhão (MA)), and 17 more.
- Municipality (`municipality`, text, required): The municipality. Choose the state to pick it from the list, or give IBGE's 7-digit code (3304557 is Rio de Janeiro), the 6-digit code some other systems use, or its name. Accents and capitals do not matter.

**Outputs**

- `count` (number): How many districts there are
- `districts` (list): The districts, by name
- `municipality_id` (number): The municipality's 7-digit code
- `municipality_name` (text): The municipality's name
- `state_code` (text): The municipality's state

**Example output**

```json
{
  "count": 1,
  "districts": [
    {
      "id": 330455705,
      "name": "Rio de Janeiro"
    }
  ],
  "municipality_id": 3304557,
  "municipality_name": "Rio de Janeiro",
  "state_code": "RJ"
}
```

### List a table's periods

List every period a SIDRA table has figures for, oldest first, with when each was last revised. Gaps are real: the population estimates skip census years.

**Inputs**

- Table (`table`, text, required): The SIDRA table's number, such as 6579 for the population estimates or 1737 for the IPCA inflation series. It is in the table's address on sidra.ibge.gov.br, and 'Search statistics tables' finds one.

**Outputs**

- `count` (number): How many periods there are
- `first_period` (text): The first period
- `last_period` (text): The latest period
- `periods` (list): The periods, oldest first
- `table_id` (number): The table's number
- `table_name` (text): The table's title

**Example output**

```json
{
  "count": 3,
  "first_period": "2001",
  "last_period": "2003",
  "periods": [
    {
      "id": "2001",
      "label": "2001",
      "updated": "30/08/2017"
    },
    {
      "id": "2002",
      "label": "2002",
      "updated": "30/08/2017"
    },
    {
      "id": "2003",
      "label": "2003",
      "updated": "30/08/2017"
    }
  ],
  "table_id": 6579,
  "table_name": "Popula\u00e7\u00e3o residente estimada"
}
```

### List immediate regions

List a state's immediate geographic regions, the groups of municipalities around a nearby city that replaced the old microregions, each with the intermediate region it belongs to. Narrow it to one intermediate region if you like.

**Inputs**

- State (`state`, text, required): The Brazilian state. Pick it from the list, or use its two-letter code such as RJ. One of: `AC` (Acre (AC)), `AL` (Alagoas (AL)), `AP` (Amapá (AP)), `AM` (Amazonas (AM)), `BA` (Bahia (BA)), `CE` (Ceará (CE)), `DF` (Distrito Federal (DF)), `ES` (Espírito Santo (ES)), `GO` (Goiás (GO)), `MA` (Maranhão (MA)), and 17 more.
- Intermediate region (`intermediate_region`, text): Only the immediate regions inside this intermediate region. Leave it empty for the whole state.

**Outputs**

- `count` (number): How many there are
- `intermediate_region_name` (text): The intermediate region asked for, empty for the whole state
- `regions` (list): The immediate regions, by code
- `state_code` (text): The state's two-letter code
- `state_name` (text): The state's name

**Example output**

```json
{
  "count": 3,
  "intermediate_region_name": "Rio de Janeiro",
  "regions": [
    {
      "id": 330001,
      "intermediate_region_id": 3301,
      "intermediate_region_name": "Rio de Janeiro",
      "name": "Rio de Janeiro"
    },
    {
      "id": 330002,
      "intermediate_region_id": 3301,
      "intermediate_region_name": "Rio de Janeiro",
      "name": "Angra dos Reis"
    },
    {
      "id": 330003,
      "intermediate_region_id": 3301,
      "intermediate_region_name": "Rio de Janeiro",
      "name": "Rio Bonito"
    }
  ],
  "state_code": "RJ",
  "state_name": "Rio de Janeiro"
}
```

### List intermediate regions

List a state's intermediate geographic regions, the divisions IBGE drew in 2017 around a state's main cities to replace the old mesoregions.

**Inputs**

- State (`state`, text, required): The Brazilian state. Pick it from the list, or use its two-letter code such as RJ. One of: `AC` (Acre (AC)), `AL` (Alagoas (AL)), `AP` (Amapá (AP)), `AM` (Amazonas (AM)), `BA` (Bahia (BA)), `CE` (Ceará (CE)), `DF` (Distrito Federal (DF)), `ES` (Espírito Santo (ES)), `GO` (Goiás (GO)), `MA` (Maranhão (MA)), and 17 more.

**Outputs**

- `count` (number): How many there are
- `regions` (list): The intermediate regions, by code
- `state_code` (text): The state's two-letter code
- `state_name` (text): The state's name

**Example output**

```json
{
  "count": 3,
  "regions": [
    {
      "id": 3301,
      "name": "Rio de Janeiro"
    },
    {
      "id": 3302,
      "name": "Volta Redonda - Barra Mansa"
    },
    {
      "id": 3303,
      "name": "Petr\u00f3polis"
    }
  ],
  "state_code": "RJ",
  "state_name": "Rio de Janeiro"
}
```

### List metropolitan regions

List a state's metropolitan regions as its state law defines them, each with every municipality in it. Use it to decide whether an address is in Greater São Paulo or Greater Rio.

**Inputs**

- State (`state`, text, required): The Brazilian state. Pick it from the list, or use its two-letter code such as RJ. One of: `AC` (Acre (AC)), `AL` (Alagoas (AL)), `AP` (Amapá (AP)), `AM` (Amazonas (AM)), `BA` (Bahia (BA)), `CE` (Ceará (CE)), `DF` (Distrito Federal (DF)), `ES` (Espírito Santo (ES)), `GO` (Goiás (GO)), `MA` (Maranhão (MA)), and 17 more.

**Outputs**

- `count` (number): How many there are
- `regions` (list): The metropolitan regions, by name
- `state_code` (text): The state's two-letter code
- `state_name` (text): The state's name

**Example output**

```json
{
  "count": 1,
  "regions": [
    {
      "id": "04701",
      "municipalities": [
        {
          "id": 3201308,
          "name": "Cariacica"
        },
        {
          "id": 3202207,
          "name": "Fund\u00e3o"
        },
        {
          "id": 3202405,
          "name": "Guarapari"
        },
        {
          "id": 3205002,
          "name": "Serra"
        },
        {
          "id": 3205101,
          "name": "Viana"
        },
        {
          "id": 3205200,
          "name": "Vila Velha"
        },
        {
          "id": 3205309,
          "name": "Vit\u00f3ria"
        }
      ],
      "municipality_count": 7,
      "name": "Regi\u00e3o Metropolitana da Grande Vit\u00f3ria"
    }
  ],
  "state_code": "ES",
  "state_name": "Esp\u00edrito Santo"
}
```

### List municipalities

List municipalities in one state or in all of Brazil (5,571 of them), optionally only those whose name contains some text, with each one's 7-digit IBGE code and the regions it belongs to. Use it to build a lookup table or to turn a list of city names into codes.

**Inputs**

- State (`state`, text): Only municipalities in this state. Leave it empty for all of Brazil. One of: `AC` (Acre (AC)), `AL` (Alagoas (AL)), `AP` (Amapá (AP)), `AM` (Amazonas (AM)), `BA` (Bahia (BA)), `CE` (Ceará (CE)), `DF` (Distrito Federal (DF)), `ES` (Espírito Santo (ES)), `GO` (Goiás (GO)), `MA` (Maranhão (MA)), and 17 more.
- Name contains (`name_contains`, text): Only municipalities whose name contains this text. Accents and capitals do not matter.
- How many to return (`limit`, number): How many municipalities to return, in alphabetical order. Defaults to 100; 6000 returns every one. From 1 to 6000. Default: `100`.

**Outputs**

- `count` (number): How many are in the result
- `matched_count` (number): How many matched before the limit
- `municipalities` (list): The municipalities, by name
- `name_contains` (text): The text the names were narrowed to
- `state_code` (text): The state asked for, empty for all of Brazil
- `total_count` (number): How many municipalities the state or Brazil has

**Example output**

```json
{
  "count": 2,
  "matched_count": 8,
  "municipalities": [
    {
      "id": 3300704,
      "immediate_region_id": 330013,
      "immediate_region_name": "Cabo Frio",
      "intermediate_region_id": 3305,
      "intermediate_region_name": "Maca\u00e9 - Rio das Ostras - Cabo Frio",
      "mesoregion_id": 3304,
      "mesoregion_name": "Baixadas",
      "microregion_id": 33010,
      "microregion_name": "Lagos",
      "name": "Cabo Frio",
      "region_code": "SE",
      "region_name": "Sudeste",
      "state_code": "RJ",
      "state_id": 33,
      "state_name": "Rio de Janeiro"
    },
    {
      "id": 3304300,
      "immediate_region_id": 330003,
      "immediate_region_name": "Rio Bonito",
      "intermediate_region_id": 3301,
      "intermediate_region_name": "Rio de Janeiro",
      "mesoregion_id": 3306,
      "mesoregion_name": "Metropolitana do Rio de Janeiro",
      "microregion_id": 33016,
      "microregion_name": "Macacu-Caceribu",
      "name": "Rio Bonito",
      "region_code": "SE",
      "region_name": "Sudeste",
      "state_code": "RJ",
      "state_id": 33,
      "state_name": "Rio de Janeiro"
    }
  ],
  "name_contains": "rio",
  "state_code": "RJ",
  "total_count": 92
}
```

### List states

List Brazil's 26 states and the Federal District, or those of one region, with the two-letter code, IBGE's number for each and the region it belongs to.

**Inputs**

- Region (`region`, text): Only the states of this region. Leave it empty for all 27. One of: `N` (North (Norte)), `NE` (Northeast (Nordeste)), `SE` (Southeast (Sudeste)), `S` (South (Sul)), `CO` (Center-West (Centro-Oeste)).

**Outputs**

- `count` (number): How many states are in the result
- `region_code` (text): The region asked for, empty for all of Brazil
- `region_name` (text): The region's name, empty for all of Brazil
- `states` (list): The states, in alphabetical order

**Example output**

```json
{
  "count": 3,
  "region_code": "SE",
  "region_name": "Sudeste",
  "states": [
    {
      "code": "ES",
      "id": 32,
      "name": "Esp\u00edrito Santo",
      "region_code": "SE",
      "region_id": 3,
      "region_name": "Sudeste"
    },
    {
      "code": "MG",
      "id": 31,
      "name": "Minas Gerais",
      "region_code": "SE",
      "region_id": 3,
      "region_name": "Sudeste"
    },
    {
      "code": "RJ",
      "id": 33,
      "name": "Rio de Janeiro",
      "region_code": "SE",
      "region_id": 3,
      "region_name": "Sudeste"
    }
  ]
}
```

### List the release calendar

List what IBGE has scheduled to publish, soonest first: inflation, jobs, GDP and every other survey, from today or between two dates, for one survey or all of them. Use it to plan around the day new figures come out.

**Inputs**

- From (`from_date`, date): The first day to include. Leave it empty to start today.
- To (`to_date`, date): The last day to include. Leave it empty for everything scheduled.
- Survey (`survey`, text): Only items about this IBGE survey, such as the monthly PNAD or the IPCA. Pick it from the list, or give IBGE's survey number. Leave it empty for every survey.
- How many to return (`limit`, number): How many to return at most. The result says how many matched in all. Defaults to 50. From 1 to 500. Default: `50`.

**Outputs**

- `count` (number): How many are in the result
- `from_date` (text): The first day included, as YYYY-MM-DD
- `matched_count` (number): How many are scheduled in the range in all
- `releases` (list): The scheduled releases, soonest first
- `survey_name` (text): The survey asked for, empty for every survey
- `to_date` (text): The last day included, empty for no end

**Example output**

```json
{
  "count": 2,
  "from_date": "2026-10-21",
  "matched_count": 57,
  "releases": [
    {
      "category": "Produtos Geocient\u00edficos Experimentais",
      "id": 4573,
      "reference_end": "",
      "reference_start": "",
      "release_date": "2026-10-22",
      "survey_alias": "contas-de-ecossistemas",
      "survey_id": 28920,
      "survey_name": "Contas de Ecossistemas",
      "title": "Contas Econ\u00f4micas Ambientais - Contas de Ecossistemas: uma abordagem para Unidades de Conserva\u00e7\u00e3o",
      "url": ""
    },
    {
      "category": "Divulga\u00e7\u00e3o de Indicadores",
      "id": 4314,
      "reference_end": "",
      "reference_start": "2026-10",
      "release_date": "2026-10-23",
      "survey_alias": "indice-nacional-de-precos-ao-consumidor-amplo-15",
      "survey_id": 9260,
      "survey_name": "\u00cdndice Nacional de Pre\u00e7os ao Consumidor Amplo 15",
      "title": "\u00cdndice Nacional de Pre\u00e7os ao Consumidor Amplo 15",
      "url": ""
    }
  ],
  "survey_name": "",
  "to_date": ""
}
```

### Rank the most common names

Get the 20 most common first names from the 2010 census, for all of Brazil, a state or a municipality, for people born in one decade, and for women or men.

**Inputs**

- Decade of birth (`decade`, text): Only people born in this decade. Leave it empty for everyone. One of: `before_1930` (Born before 1930), `1930s` (Born in the 1930s), `1940s` (Born in the 1940s), `1950s` (Born in the 1950s), `1960s` (Born in the 1960s), `1970s` (Born in the 1970s), `1980s` (Born in the 1980s), `1990s` (Born in the 1990s), `2000s` (Born in the 2000s).
- State (`state`, text): Only people in this state. Leave it empty for all of Brazil. One of: `AC` (Acre (AC)), `AL` (Alagoas (AL)), `AP` (Amapá (AP)), `AM` (Amazonas (AM)), `BA` (Bahia (BA)), `CE` (Ceará (CE)), `DF` (Distrito Federal (DF)), `ES` (Espírito Santo (ES)), `GO` (Goiás (GO)), `MA` (Maranhão (MA)), and 17 more.
- Municipality (`municipality`, text): Only people in this municipality. Choose the state to pick it from the list, or give its 7-digit code. Leave it empty for the whole state or country.
- Sex (`sex`, text): Only women or only men. Leave it empty for everyone. One of: `F` (Women), `M` (Men).

**Outputs**

- `count` (number): How many names are in the ranking
- `decade` (text): The decade of birth, or All decades
- `location_id` (text): BR, or IBGE's code for the state or municipality
- `location_name` (text): Where the people were counted
- `names` (list): The names, most common first
- `sex` (text): F or M when narrowed to women or men, else empty

**Example output**

```json
{
  "count": 3,
  "decade": "1990s",
  "location_id": "35",
  "location_name": "S\u00e3o Paulo",
  "names": [
    {
      "count": 100875,
      "name": "ANA",
      "rank": 1
    },
    {
      "count": 88688,
      "name": "JESSICA",
      "rank": 2
    },
    {
      "count": 72495,
      "name": "BRUNA",
      "rank": 3
    }
  ],
  "sex": "F"
}
```

### Search CNAE activities

Find the CNAE code for a kind of business from words that describe it, in Portuguese: 'padaria' finds bakeries that make their own bread and those that resell it. Searches both the subclass names and the thousands of activities filed under them.

**Inputs**

- Search (`search`, text, required): Words describing the activity, in Portuguese. Every word must appear; accents do not matter.
- Section (`section`, text): Only activities in this section. Leave it empty for all. One of: `A` (A: Agriculture, livestock, forestry and fishing), `B` (B: Mining and quarrying), `C` (C: Manufacturing), `D` (D: Electricity and gas), `E` (E: Water, sewage and waste), `F` (F: Construction), `G` (G: Trade and vehicle repair), `H` (H: Transport, storage and mail), `I` (I: Accommodation and food), `J` (J: Information and communication), and 11 more.
- How many to return (`limit`, number): How many to return at most. The result says how many matched in all. Defaults to 25. From 1 to 200. Default: `25`.

**Outputs**

- `activities` (list): The matching subclasses, name matches first
- `count` (number): How many are in the result
- `matched_count` (number): How many matched in all
- `searched_for` (text): The words searched for
- `section_code` (text): The section asked for, empty for all

**Example output**

```json
{
  "activities": [
    {
      "class_name": "FABRICA\u00c7\u00c3O DE PRODUTOS DE PANIFICA\u00c7\u00c3O",
      "code": "1091102",
      "description": "FABRICA\u00c7\u00c3O DE PRODUTOS DE PADARIA E CONFEITARIA COM PREDOMIN\u00c2NCIA  DE PRODU\u00c7\u00c3O PR\u00d3PRIA",
      "division_name": "FABRICA\u00c7\u00c3O DE PRODUTOS ALIMENT\u00cdCIOS",
      "formatted_code": "1091-1/02",
      "matched_activity": "",
      "section_code": "C",
      "section_name": "IND\u00daSTRIAS DE TRANSFORMA\u00c7\u00c3O"
    },
    {
      "class_name": "COM\u00c9RCIO VAREJISTA DE PRODUTOS DE PADARIA, LATIC\u00cdNIO, DOCES, BALAS E SEMELHANTES",
      "code": "4721102",
      "description": "PADARIA E CONFEITARIA COM PREDOMIN\u00c2NCIA DE REVENDA",
      "division_name": "COM\u00c9RCIO VAREJISTA",
      "formatted_code": "4721-1/02",
      "matched_activity": "",
      "section_code": "G",
      "section_name": "COM\u00c9RCIO; REPARA\u00c7\u00c3O DE VE\u00cdCULOS AUTOMOTORES E MOTOCICLETAS"
    }
  ],
  "count": 2,
  "matched_count": 6,
  "searched_for": "padaria",
  "section_code": ""
}
```

### Search news and releases

Search the IBGE news agency's stories and its releases of new figures (inflation, unemployment, GDP, harvests), newest first, by words, kind, survey and date. Each item comes with its headline, opening paragraph and link, in Portuguese.

**Inputs**

- Search (`search`, text): Words to look for, in Portuguese. Accents do not matter. Leave it empty for everything.
- Kind (`news_type`, text): News stories, or releases of new figures. Leave it empty for both.
- Published on or after (`published_from`, date): Only items published on this day or later.
- Published on or before (`published_to`, date): Only items published on this day or earlier.
- Survey (`survey`, text): Only items about this IBGE survey, such as the monthly PNAD or the IPCA. Pick it from the list, or give IBGE's survey number. Leave it empty for every survey.
- How many to return (`limit`, number): How many to return at most. The result says how many matched in all. Defaults to 20. From 1 to 100. Default: `20`.

**Outputs**

- `count` (number): How many items are in the result
- `items` (list): The items, newest first
- `more_available` (true/false): True when more items matched than were returned
- `news_type` (text): news or release when narrowed to one kind, else empty
- `searched_for` (text): The words searched for
- `survey_name` (text): The survey asked for, empty for every survey
- `total_count` (number): How many items matched in all

**Example output**

```json
{
  "count": 2,
  "items": [
    {
      "id": 48292,
      "image_url": "https://agenciadenoticias.ibge.gov.br/images/agenciadenoticias/releases/PMC_release.png",
      "introduction": "Em agosto de 2026, o volume de vendas no com\u00e9rcio varejista registrou varia\u00e7\u00e3o de 0,1% frente a julho, na s\u00e9rie com ajuste sazonal, ap\u00f3s queda de 0,8% em julho ...",
      "is_highlight": true,
      "published_date": "2026-10-15",
      "section": "economicas",
      "survey_id": 9227,
      "survey_name": "Pesquisa Mensal de Com\u00e9rcio",
      "title": "Em agosto, com\u00e9rcio varejista registra varia\u00e7\u00e3o de 0,1%",
      "type": "release",
      "url": "https://agenciadenoticias.ibge.gov.br/agencia-sala-de-imprensa/2013-agencia-de-noticias/releases/48292-em-agosto-comercio-varejista-registra-variacao-0-1.html"
    },
    {
      "id": 48289,
      "image_url": "https://agenciadenoticias.ibge.gov.br/images/agenciadenoticias/releases/LSPA_Release.png",
      "introduction": "A estimativa de setembro do IBGE para a produ\u00e7\u00e3o de gr\u00e3os em 2026 foi de 354,5 milh\u00f5es de toneladas, 2,4% (8,4 milh\u00f5es de toneladas) maior que a obtida em 2025 ...",
      "is_highlight": true,
      "published_date": "2026-10-15",
      "section": "economicas",
      "survey_id": 9201,
      "survey_name": "Levantamento Sistem\u00e1tico da Produ\u00e7\u00e3o Agr\u00edcola",
      "title": "Em setembro, safra prevista pelo IBGE para 2026 \u00e9 de 354,5 milh\u00f5es de toneladas",
      "type": "release",
      "url": "https://agenciadenoticias.ibge.gov.br/agencia-sala-de-imprensa/2013-agencia-de-noticias/releases/48289-em-setembro-safra-prevista-pelo-ibge-para-2026-e-de-354-5-milhoes-de-toneladas.html"
    }
  ],
  "more_available": true,
  "news_type": "release",
  "searched_for": "",
  "survey_name": "",
  "total_count": 4171
}
```

### Search statistics tables

Find SIDRA tables, IBGE's published statistics, by words in the table's or its survey's name, optionally only those published for municipalities or states, or monthly. Each table comes with the number the other table actions take.

**Inputs**

- Search (`search`, text, required): Words from the table's name, in Portuguese. Every word must appear; accents do not matter and the start of a word is enough.
- Published for (`level`, text): Only tables with figures for this kind of place. Leave it empty for any. One of: `N1` (Brazil), `N2` (Major regions), `N3` (States), `N6` (Municipalities), `N7` (Metropolitan regions), `N8` (Mesoregions), `N9` (Microregions), `N10` (Districts).
- Frequency (`frequency`, text): Only tables updated this often. Leave it empty for any. One of: `P5` (Monthly), `P13` (Rolling quarter), `P9` (Quarterly), `P8` (Every six months), `P1` (Yearly).
- How many to return (`limit`, number): How many to return at most. The result says how many matched in all. Defaults to 25. From 1 to 200. Default: `25`.

**Outputs**

- `count` (number): How many are in the result
- `frequency` (text): The frequency asked for, empty for any
- `level` (text): The kind of place asked for, empty for any
- `matched_count` (number): How many matched in all
- `searched_for` (text): The words searched for
- `tables` (list): The matching tables, best match first

**Example output**

```json
{
  "count": 2,
  "frequency": "",
  "level": "",
  "matched_count": 3,
  "searched_for": "popula\u00e7\u00e3o residente estimada",
  "tables": [
    {
      "id": 6579,
      "name": "Popula\u00e7\u00e3o residente estimada",
      "survey_id": "XF",
      "survey_name": "Estimativas de Popula\u00e7\u00e3o",
      "url": "https://sidra.ibge.gov.br/tabela/6579"
    },
    {
      "id": 5456,
      "name": "Popula\u00e7\u00e3o residente estimada e pessoas de 10 anos ou mais de idade usu\u00e1rias da Internet, total e por 1.000 habitantes",
      "survey_id": "IU",
      "survey_name": "Indicadores de Desenvolvimento Sustent\u00e1vel",
      "url": "https://sidra.ibge.gov.br/tabela/5456"
    }
  ]
}
```
