Guia de Localidades

Copy Markdown View Source

Este guia fornece exemplos detalhados e explicações sobre como usar os módulos de Localidades do ExIbge para navegar pela hierarquia geográfica do Brasil.

Hierarquia Geográfica

O IBGE organiza o território brasileiro em diversas divisões. O ExIbge fornece módulos para acessar cada nível dessa hierarquia.

Abaixo, apresentamos os principais módulos e como utilizá-los.

Regiões (Region)

O Brasil é dividido em 5 grandes regiões: Norte, Nordeste, Sudeste, Sul e Centro-Oeste.

alias ExIbge.Locality.Region

# Listar todas as regiões
Region.all()
# -> {:ok, [%ExIbge.Geography.Region{id: 3, name: "Sudeste", ...}, ...]}

# Buscar uma região específica pelo ID
Region.find(3)
# -> {:ok, [%ExIbge.Geography.Region{id: 3, name: "Sudeste", ...}]}

Estados (State)

As Unidades da Federação (UFs). Você pode buscar por ID numérico ou sigla (atom).

alias ExIbge.Locality.State

# Listar todos os estados
State.all()

# Buscar Rio de Janeiro pelo ID
State.find(33)

# Buscar São Paulo pela sigla (atom)
State.find(:sp)
# -> {:ok, [%ExIbge.Geography.State{id: 35, sigla: "SP", name: "São Paulo", ...}]}

Municípios (Municipality)

A menor unidade administrativa autônoma.

alias ExIbge.Locality.Municipality

# Buscar município por ID (São Paulo - 3550308)
Municipality.find(3550308)

# Buscar todos os municípios de um estado (usando atom)
Municipality.get_by_state(:sc)

# Buscar todos os municípios de uma região (Sul)
Municipality.get_by_region(4)

Distritos e Subdistritos (District, Subdistrict)

  • Distritos: Subdivisões administrativas dos municípios.
  • Subdistritos: Subdivisões de distritos (comuns em grandes cidades).
alias ExIbge.Locality.District
alias ExIbge.Locality.Subdistrict

# Distritos de um município (ex: Ouro Preto/MG)
District.get_by_municipality(3146107)

# Subdistritos de um distrito
Subdistrict.get_by_district(314610705)

Regiões Metropolitanas e RIDE

  • Regiões Metropolitanas (MetropolitanRegion): Agrupamentos de municípios limítrofes.
  • RIDE (IntegratedDevelopmentRegion): Regiões Integradas de Desenvolvimento (ex: DF e Entorno).
  • Aglomerações Urbanas (UrbanAgglomeration): Áreas urbanas contínuas que não formam necessariamente uma RM.
alias ExIbge.Locality.MetropolitanRegion
alias ExIbge.Locality.IntegratedDevelopmentRegion

# Todas as RMs de um estado
MetropolitanRegion.get_by_state(:rj)

# Todas as RIDEs
IntegratedDevelopmentRegion.all()

Diferença entre Mesorregiões e Microrregiões

Estas são divisões regionais extintas em 2017, substituídas por Regiões Geográficas Intermediárias e Imediatas, mas a API ainda as suporta para fins históricos.

  • Mesorregião (Mesoregion): Subdivisão dos estados que agrupa diversos municípios com características sociais e econômicas comuns.
  • Microrregião (Microregion): Subdivisão das mesorregiões.
alias ExIbge.Locality.Mesoregion
alias ExIbge.Locality.Microregion

Mesoregion.get_by_state(:ba)
Microregion.get_by_mesoregion(2905)

Regiões Intermediárias e Imediatas (Novo Padrão)

Vigentes desde 2017.

  • Região Geográfica Intermediária (IntermediateRegion): Articula regiões imediatas.
  • Região Geográfica Imediata (ImmediateRegion): Estruturada a partir de centros urbanos próximos.
alias ExIbge.Locality.IntermediateRegion
alias ExIbge.Locality.ImmediateRegion

IntermediateRegion.get_by_state(:mg)
ImmediateRegion.get_by_intermediate_region(3101)