A gem ibge-ruby permite você integrar a sua aplicação Ruby on Rails com todos os serviços de localidade fornecidos pelo IBGE de maneira simples e rápida.

Adicione essa linha no Gemfile da sua aplicação:

gem 'ibge-ruby'

E execute:

$ bundle

Ou instale diretamente com o comando:

$ gem install ibge-ruby

Cada link direciona para a documentação do IBGE com a descrição do método, entrada e saída. Ao lado é a referência de como utilizá-lo com a gem.

• Distritos

  • Distritos - IBGE::Distrito.obter_distritos
  • Distritos por identificador - IBGE::Distrito.distritos_por_id(ids)
  • Distritos por UF - IBGE::Distrito.distritos_por_uf(ufs)
  • Distritos por mesorregião - IBGE::Distrito.distritos_por_mesorregiao(mesorregioes)
  • Distritos por microrregião - IBGE::Distrito.distritos_por_microrregiao(microrregioes)
  • Distritos por município - IBGE::Distrito.distritos_por_municipio(municipios)
  • Distritos por região imediata - IBGE::Distrito.distritos_por_regiao_imediata(regioes)
  • Distritos por região intermediária - IBGE::Distrito.distritos_por_regiao_intermediaria(regioes)
  • Distritos por região - IBGE::Distrito.distritos_por_regiao(regioes)

• Mesorregiões

  • Mesorregiões - IBGE::Mesorregiao.obter_mesorregioes
  • Mesorregiões por identificador - IBGE::Mesorregiao.mesorregioes_por_id(ids)
  • Mesorregiões por UF - IBGE::Mesorregiao.mesorregioes_por_uf(ufs)
  • Mesorregiões por região - IBGE::Mesorregiao.mesorregioes_por_regiao(regioes)

• Microrregiões

  • Microrregiões - IBGE::Microrregiao.obter_microrregioes
  • Microrregiões por identificador - IBGE::Microrregiao.microrregioes_por_id(ids)
  • Microrregiões por UF - IBGE::Microrregiao.microrregioes_por_uf(ufs)
  • Microrregiões por mesorregião - IBGE::Microrregiao.microrregioes_por_mesorregiao(mesorregioes)
  • Microrregiões por região - IBGE::Microrregiao.microrregioes_por_masorregiao(masorregioes)

• Municípios

  • Municípios - IBGE::Municipio.obter_municipios
  • Municípios por identificador - IBGE::Municipio.municipios_por_id(ids)
  • Municípios por UF - IBGE::Municipio.municipios_por_uf(ufs)
  • Municípios por mesorregião - IBGE::Municipio.municipios_por_mesorregiao(mesorregioes)
  • Municípios por microrregião - IBGE::Municipio.municipios_por_microrregiao(microrregioes)
  • Municípios por região imediata - IBGE::Municipio.municipios_por_regiao_imediata(regioes)
  • Municípios por região intermediária - IBGE::Municipio.municipios_por_regiao_intermediaria(regioes)
  • Municípios por região - IBGE::Municipio.municipios_por_regiao(regioes)

• Países

  • Países - IBGE::Pais.obter_paises
  • Países por identificador - IBGE::Pais.paises_por_identificador(ids)

• Regiões

  • Regiões - IBGE::Regiao.obter_regioes
  • Regiões por identificador - IBGE::Regiao.regioes_por_identificador(ids)

• Regiões Imediatas

  • Regiões imediatas - IBGE::RegiaoImediata.obter_regioes_imediatas
  • Regiões imediatas por identificador - IBGE::RegiaoImediata.regioes_imediatas_por_id(ids)
  • Regiões imediatas por UF - IBGE::RegiaoImediata.regioes_imediatas_por_uf(ufs)
  • Regiões imediatas por regiões intermediárias - IBGE::RegiaoImediata.regioes_imediatas_por_intermediaria(regioes)
  • Regiões imediatas por região - IBGE::RegiaoImediata.regioes_imediatas_por_regiao(regioes)

• Regiões Intermediárias

  • Regiões intermediárias - IBGE::RegiaoIntermediaria.obter_regioes_intermediarias
  • Regiões intermediárias por identificador - IBGE::RegiaoIntermediaria.regioes_intermediarias_por_id(ids)
  • Regiões intermediárias por UF - IBGE::RegiaoIntermediaria.regioes_intermediarias_por_uf(ufs)
  • Regiões intermediárias por região - IBGE::RegiaoIntermediaria.regioes_intermediarias_por_regiao(regioes)

• Subdistritos

  • Subdistritos - IBGE::Subdistrito.obter_subdistritos
  • Subdistritos por identificador - IBGE::Subdistrito.subdistritos_por_id(ids)
  • Subdistritos por UF - IBGE::Subdistrito.subdistritos_por_uf(ufs)
  • Subdistritos por distrito - IBGE::Subdistrito.subdistritos_por_distrito(distritos)
  • Subdistritos por mesorregião - IBGE::Subdistrito.subdistritos_por_mesorregiao(mesorregioes)
  • Subdistritos por microrregião - IBGE::Subdistrito.subdistritos_por_microrregiao(microrregioes)
  • Subdistritos por município - IBGE::Subdistrito.subdistritos_por_municipio(municipios)
  • Subdistritos por região - IBGE::Subdistrito.subdistritos_por_regiao(regioes)

• UFs

  • UFs - IBGE::UF.obter_ufs
  • UF por identificador - IBGE::UF.ufs_por_identificador(ids)
  • UFs por região - IBGE::UF.ufs_por_regiao(regioes)

1. Nas referências dos serviços, é possível enviar um ou mais parâmetros delimitados pelo caractere | (pipe). Na gem, ao utilizar serviços em que é possível enviar vários parâmetros (quase todos), utilize o formato de array.

❌ Serviço IBGE: 1|2|3

✅ Gem IBGE Ruby: [1, 2, 3] ou ['1', '2', '3'].

_{* Em alguns casos também é possível passar siglas. Verifique a seção Pesquisa por identificador (ID), sigla ou array de IDs/siglas.}

2. No momento, esta gem não oferece suporte aos query parameters orderBy e view. Contudo, no Ruby, é possível simular o orderBy da seguinte forma:

# Sem order by
regioes = IBGE::Regiao.obter_regioes.map(&:nome) #=> ['Norte', 'Nordeste', 'Sudeste', 'Sul', 'Centro-Oeste']

# Comportamento similar ao orderBy com Ruby
regioes = IBGE::Regiao.obter_regioes.sort_by(&:nome).map(&:nome) #=> ['Centro-Oeste', 'Nordeste', 'Norte', 'Sudeste', 'Sul']

Abaixo estão alguns exemplos de utilização da gem. Verifique a documentação para uma referência mais completa.

require 'ibge'

paises = IBGE::Pais.obter_paises
paises.map(&:nome) #=> ['Afeganistão', 'Albânia', 'Argélia', 'Andorra', 'Angola'...]

regioes = IBGE::Regiao.obter_regioes
regioes.map(&:nome) #=> ['Norte', 'Nordeste', 'Sudeste', 'Sul', 'Centro-Oeste']
regioes.first #=> #<IBGE::Regiao:0x0000555f7e83de38 @id=1, @nome="Norte", @sigla="N">

Em qualquer módulo que possua um método que faça referência aos recursos de Região ou UFs, é possível pesquisar pelo ID, sigla ou um array de IDs/siglas.

IBGE::Municipio.municipios_por_regiao('NE') #=> mesma coisa de IBGE::Municipio.municipios_por_regiao(2)
IBGE::Municipio.municipios_por_regiao(['N', 'NE']) #=> mesma coisa de IBGE::Municipio.municipios_por_regiao([1, 2])

IBGE::Distrito.distritos_por_uf('CE') #=> mesma coisa de IBGE::Distrito.distritos_por_uf(23)
IBGE::Distrito.distritos_por_uf(['BA', 'CE]) #=> mesma coisa de IBGE::Distrito.distritos_por_uf([29, 23])

1. Faça um fork
2. Crie uma branch com a funcionalidade (git checkout -b nova_funcionalidade)
3. Faça um commit das suas mudanças (git commit -am "[add] nova funcionalidade")
4. Faça um push para a branch (git push origin nova_funcionalidade)
5. Crie um pull request