ibge-ruby 1.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4c489ef9667211b1e342b3518e11003253410eb2b613e44c02ff7772d5222ab4
+  data.tar.gz: e031efd350860c4643af376f296e43589584abb8378ce0ff2a7709c93f7fdbd1
+SHA512:
+  metadata.gz: 4a163369d05c8b59b8e458dd84195540229e516d3240b8236e85b802a837b60dc92c4cb308dd3b2311832a8d211875c46a883420dee35ede5314cb94455fd26c
+  data.tar.gz: 6e33b495084523a3203ffd6152ad074ac9f40874dee02565e9dcc05563627c5dd971de8721321a2316a3d230436db2a040ff56f235723457cb5d2e3e8d575b60

data/.gitignore

@@ -0,0 +1,2 @@
+coverage
+.byebug_history

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format documentation
+--require spec_helper

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,79 @@
+PATH
+  remote: .
+  specs:
+    ibge-ruby (1.0.0)
+      rest-client (~> 2.0.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    crack (0.4.5)
+      rexml
+    diff-lcs (1.5.0)
+    docile (1.4.0)
+    domain_name (0.5.20190701)
+      unf (>= 0.0.5, < 1.0.0)
+    hashdiff (1.0.1)
+    http-cookie (1.0.4)
+      domain_name (~> 0.5)
+    method_source (1.0.0)
+    mime-types (3.4.1)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2022.0105)
+    netrc (0.11.0)
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    public_suffix (4.0.6)
+    rest-client (2.0.2)
+      http-cookie (>= 1.0.2, < 2.0)
+      mime-types (>= 1.16, < 4.0)
+      netrc (~> 0.8)
+    rexml (3.2.5)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.3)
+    simplecov (0.21.2)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.3)
+    unf (0.1.4)
+      unf_ext
+    unf_ext (0.0.8)
+    vcr (3.0.3)
+    webmock (3.14.0)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  byebug (~> 11.1.3)
+  ibge-ruby!
+  pry (~> 0.14.1)
+  rspec (~> 3.10.0)
+  simplecov (~> 0.18)
+  vcr (~> 3.0)
+  webmock (~> 3.14.0)
+
+BUNDLED WITH
+   2.2.21

data/README.md

@@ -0,0 +1,155 @@
+# IBGE Ruby
+
+[![Gem Version](https://badge.fury.io/rb/ibge-ruby.svg)](http://badge.fury.io/rb/ibge-ruby)
+
+A gem ibge-ruby permite você integrar a sua aplicação Ruby on Rails com todos os [serviços de localidade](https://servicodados.ibge.gov.br/api/docs/localidades) fornecidos pelo IBGE de maneira simples e rápida.
+
+## Instalação
+
+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
+
+## Métodos
+
+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](https://servicodados.ibge.gov.br/api/docs/localidades#api-Distritos-distritosGet) - `IBGE::Distrito.obter_distritos`
+  * [Distritos por identificador](https://servicodados.ibge.gov.br/api/docs/localidades#api-Distritos-distritosIdGet) - `IBGE::Distrito.distritos_por_id(ids)`
+  * [Distritos por UF](https://servicodados.ibge.gov.br/api/docs/localidades#api-Distritos-estadosUFDistritosGet) - `IBGE::Distrito.distritos_por_uf(ufs)`
+  * [Distritos por mesorregião](https://servicodados.ibge.gov.br/api/docs/localidades#api-Distritos-mesorregioesMesorregiaoDistritosGet) - `IBGE::Distrito.distritos_por_mesorregiao(mesorregioes)`
+  * [Distritos por microrregião](https://servicodados.ibge.gov.br/api/docs/localidades#api-Distritos-microrregioesMicrorregiaoDistritosGet) - `IBGE::Distrito.distritos_por_microrregiao(microrregioes)`
+  * [Distritos por município](https://servicodados.ibge.gov.br/api/docs/localidades#api-Distritos-municipiosMunicipioDistritosGet) - `IBGE::Distrito.distritos_por_municipio(municipios)`
+  * [Distritos por região imediata](https://servicodados.ibge.gov.br/api/docs/localidades#api-Distritos-regioesImediatasRegiaoImediataDistritosGet) - `IBGE::Distrito.distritos_por_regiao_imediata(regioes)`
+  * [Distritos por região intermediária](https://servicodados.ibge.gov.br/api/docs/localidades#api-Distritos-regioesIntermediariasRegiaoIntermediariaDistritosGet) - `IBGE::Distrito.distritos_por_regiao_intermediaria(regioes)`
+  * [Distritos por região](https://servicodados.ibge.gov.br/api/docs/localidades#api-Distritos-regioesMacrorregiaoDistritosGet) - `IBGE::Distrito.distritos_por_regiao(regioes)`
+
+* __Mesorregiões__
+  * [Mesorregiões](https://servicodados.ibge.gov.br/api/docs/localidades#api-Mesorregioes-mesorregioesGet) - `IBGE::Mesorregiao.obter_mesorregioes`
+  * [Mesorregiões por identificador](https://servicodados.ibge.gov.br/api/docs/localidades#api-Mesorregioes-mesorregioesMesorregiaoGet) - `IBGE::Mesorregiao.mesorregioes_por_id(ids)`
+  * [Mesorregiões por UF](https://servicodados.ibge.gov.br/api/docs/localidades#api-Mesorregioes-estadosUFMesorregioesGet) - `IBGE::Mesorregiao.mesorregioes_por_uf(ufs)`
+  * [Mesorregiões por região](https://servicodados.ibge.gov.br/api/docs/localidades#api-Mesorregioes-regioesMacrorregiaoMesorregioesGet) - `IBGE::Mesorregiao.mesorregioes_por_regiao(regioes)` 
+  
+* __Microrregiões__
+  * [Microrregiões](https://servicodados.ibge.gov.br/api/docs/localidades#api-Microrregioes-microrregioesGet) - `IBGE::Microrregiao.obter_microrregioes`
+  * [Microrregiões por identificador](https://servicodados.ibge.gov.br/api/docs/localidades#api-Microrregioes-microrregioesMicrorregiaoGet) - `IBGE::Microrregiao.microrregioes_por_id(ids)`
+  * [Microrregiões por UF](https://servicodados.ibge.gov.br/api/docs/localidades#api-Microrregioes-estadosUFMicrorregioesGet) - `IBGE::Microrregiao.microrregioes_por_uf(ufs)`
+  * [Microrregiões por mesorregião](https://servicodados.ibge.gov.br/api/docs/localidades#api-Microrregioes-mesorregioesMesorregiaoMicrorregioesGet) - `IBGE::Microrregiao.microrregioes_por_mesorregiao(mesorregioes)`
+  * [Microrregiões por região](https://servicodados.ibge.gov.br/api/docs/localidades#api-Microrregioes-regioesMacrorregiaoMicrorregioesGet) - `IBGE::Microrregiao.microrregioes_por_masorregiao(masorregioes)`
+
+* __Municípios__
+  * [Municípios](https://servicodados.ibge.gov.br/api/docs/localidades#api-Municipios-municipiosGet) - `IBGE::Municipio.obter_municipios`
+  * [Municípios por identificador](https://servicodados.ibge.gov.br/api/docs/localidades#api-Municipios-municipiosMunicipioGet) - `IBGE::Municipio.municipios_por_id(ids)`
+  * [Municípios por UF](https://servicodados.ibge.gov.br/api/docs/localidades#api-Municipios-estadosUFMunicipiosGet) - `IBGE::Municipio.municipios_por_uf(ufs)`
+  * [Municípios por mesorregião](https://servicodados.ibge.gov.br/api/docs/localidades#api-Municipios-mesorregioesMesorregiaoMunicipiosGet) - `IBGE::Municipio.municipios_por_mesorregiao(mesorregioes)`
+  * [Municípios por microrregião](https://servicodados.ibge.gov.br/api/docs/localidades#api-Municipios-microrregioesMicrorregiaoMunicipiosGet) - `IBGE::Municipio.municipios_por_microrregiao(microrregioes)`
+  * [Municípios por região imediata](https://servicodados.ibge.gov.br/api/docs/localidades#api-Municipios-regioesImediatasRegiaoImediataMunicipiosGet) - `IBGE::Municipio.municipios_por_regiao_imediata(regioes)`
+  * [Municípios por região intermediária](https://servicodados.ibge.gov.br/api/docs/localidades#api-Municipios-regioesIntermediariasRegiaoIntermediariaMunicipiosGet) - `IBGE::Municipio.municipios_por_regiao_intermediaria(regioes)`
+  * [Municípios por região](https://servicodados.ibge.gov.br/api/docs/localidades#api-Municipios-regioesMacrorregiaoMunicipiosGet) - `IBGE::Municipio.municipios_por_regiao(regioes)`
+  
+* __Países__
+  * [Países](https://servicodados.ibge.gov.br/api/docs/localidades#api-Paises-paisesGet) - `IBGE::Pais.obter_paises`
+  * [Países por identificador](https://servicodados.ibge.gov.br/api/docs/localidades#api-Paises-paisesPaisGet) - `IBGE::Pais.paises_por_identificador(ids)`
+  
+* __Regiões__
+  * [Regiões](https://servicodados.ibge.gov.br/api/docs/localidades#api-Regioes-regioesGet) - `IBGE::Regiao.obter_regioes`
+  * [Regiões por identificador](https://servicodados.ibge.gov.br/api/docs/localidades#api-Regioes-regioesMacrorregiaoGet) - `IBGE::Regiao.regioes_por_identificador(ids)`
+  
+* __Regiões Imediatas__
+  * [Regiões imediatas](https://servicodados.ibge.gov.br/api/docs/localidades#api-RegioesImediatas-regioesImediatasGet) - `IBGE::RegiaoImediata.obter_regioes_imediatas`
+  * [Regiões imediatas por identificador](https://servicodados.ibge.gov.br/api/docs/localidades#api-RegioesImediatas-regioesImediatasRegiaoImediataGet) - `IBGE::RegiaoImediata.regioes_imediatas_por_id(ids)`
+  * [Regiões imediatas por UF](https://servicodados.ibge.gov.br/api/docs/localidades#api-RegioesImediatas-estadosUFRegioesImediatasGet) - `IBGE::RegiaoImediata.regioes_imediatas_por_uf(ufs)`
+  * [Regiões imediatas por regiões intermediárias](https://servicodados.ibge.gov.br/api/docs/localidades#api-RegioesImediatas-regioesIntermediariasRegiaoIntermediariaRegioesImediatasGet) - `IBGE::RegiaoImediata.regioes_imediatas_por_intermediaria(regioes)`
+  * [Regiões imediatas por região](https://servicodados.ibge.gov.br/api/docs/localidades#api-RegioesImediatas-regioesMacrorregiaoRegioesImediatasGet) - `IBGE::RegiaoImediata.regioes_imediatas_por_regiao(regioes)`
+  
+* __Regiões Intermediárias__
+  * [Regiões intermediárias](https://servicodados.ibge.gov.br/api/docs/localidades#api-RegioesIntermediarias-regioesIntermediariasGet) - `IBGE::RegiaoIntermediaria.obter_regioes_intermediarias`
+  * [Regiões intermediárias por identificador](https://servicodados.ibge.gov.br/api/docs/localidades#api-RegioesIntermediarias-regioesIntermediariasRegiaoIntermediariaGet) - `IBGE::RegiaoIntermediaria.regioes_intermediarias_por_id(ids)`
+  * [Regiões intermediárias por UF](https://servicodados.ibge.gov.br/api/docs/localidades#api-RegioesIntermediarias-estadosUFRegioesIntermediariasGet) - `IBGE::RegiaoIntermediaria.regioes_intermediarias_por_uf(ufs)`
+  * [Regiões intermediárias por região](https://servicodados.ibge.gov.br/api/docs/localidades#api-RegioesIntermediarias-regioesMacrorregiaoRegioesIntermediariasGet) - `IBGE::RegiaoIntermediaria.regioes_intermediarias_por_regiao(regioes)`
+  
+* __Subdistritos__
+  * [Subdistritos](https://servicodados.ibge.gov.br/api/docs/localidades#api-Subdistritos-subdistritosGet) - `IBGE::Subdistrito.obter_subdistritos`
+  * [Subdistritos por identificador](https://servicodados.ibge.gov.br/api/docs/localidades#api-Subdistritos-subdistritosIdGet) - `IBGE::Subdistrito.subdistritos_por_id(ids)`
+  * [Subdistritos por UF](https://servicodados.ibge.gov.br/api/docs/localidades#api-Subdistritos-estadosUFSubdistritosGet) - `IBGE::Subdistrito.subdistritos_por_uf(ufs)`
+  * [Subdistritos por distrito](https://servicodados.ibge.gov.br/api/docs/localidades#api-Subdistritos-distritosDistritoSubdistritosGet) - `IBGE::Subdistrito.subdistritos_por_distrito(distritos)`
+  * [Subdistritos por mesorregião](https://servicodados.ibge.gov.br/api/docs/localidades#api-Subdistritos-mesorregioesMesorregiaoSubdistritosGet) - `IBGE::Subdistrito.subdistritos_por_mesorregiao(mesorregioes)`
+  * [Subdistritos por microrregião](https://servicodados.ibge.gov.br/api/docs/localidades#api-Subdistritos-microrregioesMicrorregiaoSubdistritosGet) - `IBGE::Subdistrito.subdistritos_por_microrregiao(microrregioes)`
+  * [Subdistritos por município](https://servicodados.ibge.gov.br/api/docs/localidades#api-Subdistritos-municipiosMunicipioSubdistritosGet) - `IBGE::Subdistrito.subdistritos_por_municipio(municipios)`
+  * [Subdistritos por região](https://servicodados.ibge.gov.br/api/docs/localidades#api-Subdistritos-regioesMacrorregiaoSubdistritosGet) - `IBGE::Subdistrito.subdistritos_por_regiao(regioes)`
+  
+* __UFs__
+  * [UFs](https://servicodados.ibge.gov.br/api/docs/localidades#api-UFs-estadosGet) - `IBGE::UF.obter_ufs`
+  * [UF por identificador](https://servicodados.ibge.gov.br/api/docs/localidades#api-UFs-estadosUFGet) - `IBGE::UF.ufs_por_identificador(ids)`
+  * [UFs por região](https://servicodados.ibge.gov.br/api/docs/localidades#api-UFs-regioesMacrorregiaoEstadosGet) - `IBGE::UF.ufs_por_regiao(regioes)`
+
+### Observações
+
+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']`.
+
+<sub>* Em alguns casos também é possível passar siglas. Verifique a seção Pesquisa por identificador (ID), sigla ou array de IDs/siglas.</sub>
+
+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:
+
+```ruby
+# 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']
+```
+
+## Utilização
+
+Abaixo estão alguns exemplos de utilização da gem. Verifique a [documentação](https://www.rubydoc.info/gems/ibge-ruby/main) para uma referência mais completa.
+
+### Países
+
+```ruby
+require 'ibge'
+
+paises = IBGE::Pais.obter_paises
+paises.map(&:nome) #=> ['Afeganistão', 'Albânia', 'Argélia', 'Andorra', 'Angola'...]
+```
+
+### Regiões
+
+```ruby
+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">
+```
+
+### Pesquisa por identificador (ID), sigla ou array de IDs/siglas
+
+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.
+
+```ruby
+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])
+```
+
+## Contribuindo
+
+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

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/ibge-ruby.gemspec

@@ -0,0 +1,28 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ibge/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'ibge-ruby'
+  spec.version       = IBGE::VERSION
+  spec.summary       = 'Wrapper do serviço do IBGE para Ruby.'
+  spec.authors       = ["Andréa Alencar"]
+  spec.email         = 'andreaflether@gmail.com'
+  spec.homepage      = 'https://github.com/andreaflether/ibge-ruby'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(/^spec\//)
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'pry', '~> 0.14.1'
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'byebug', '~> 11.1.3'
+
+  spec.add_development_dependency 'simplecov', '~> 0.18'
+  spec.add_development_dependency 'webmock', '~> 3.14.0'
+  spec.add_development_dependency 'rspec', '~> 3.10.0'
+  spec.add_development_dependency 'vcr', '~> 3.0'
+
+  spec.add_dependency 'rest-client', '~> 2.0.2'
+end

data/lib/ibge/distrito.rb

@@ -0,0 +1,179 @@
+module IBGE
+  class Distrito
+    attr_accessor :id, :nome, :municipio
+
+    def initialize(options = {})
+      @id        = options['id']
+      @nome      = options['nome']
+      @municipio = Municipio.new(options['municipio'])
+    end
+
+    # Obtém o conjunto de distritos do Brasil.
+    #
+    # @return [Array<Distrito>]
+    #
+    # @example
+    #           distritos = IBGE::Distrito.obter_distritos
+    #           distritos.first.nome #=> "Abadia de Goiás"
+    def self.obter_distritos
+      resposta = RestClient.get("#{BASE_URL}/distritos")
+      
+      tratar_retorno(resposta)
+    end
+    
+    # Obtém o conjunto de distritos do Brasil a partir dos respectivos identificadores.
+    # Pode ser informado um único ID ou um array de IDs.
+    #
+    # @param ids [String, Integer, Array] Um ou mais identificadores de distritos.
+    # @return [Array<Distrito>]
+    #
+    # @example
+    #           distritos = IBGE::Distrito.distritos_por_id(230440005)
+    #           distritos.first.nome #=> "Fortaleza"
+    #
+    #           distritos = IBGE::Distrito.distritos_por_id([230440005, 230370905])
+    def self.distritos_por_id(ids)
+      ids      = IBGE.formatar(ids)
+      resposta = RestClient.get("#{BASE_URL}/distritos/#{ids}")
+    
+      tratar_retorno(resposta)
+    end
+
+    # Obtém o conjunto de distritos do Brasil a partir dos identificadores das Unidades da Federação.
+    # Pode ser informada a sigla, identificador (ID) ou um array de siglas/identificadores. 
+    # 
+    # @param ufs [String, Integer, Array]
+    # @return [Array<Distrito>]
+    #
+    # @example
+    #           distritos = IBGE::Distrito.distritos_por_uf('CE')
+    #           distritos.last.nome #=> "Quatiguaba"
+    #
+    #           IBGE::Distrito.distritos_por_uf(['BA', 'CE'])
+    #           IBGE::Distrito.distritos_por_uf(23) 
+    def self.distritos_por_uf(ufs)
+      ufs      = IBGE.formatar(ufs)
+      resposta = RestClient.get("#{BASE_URL}/estados/#{ufs}/distritos")
+    
+      tratar_retorno(resposta)
+    end
+
+    # Obtém o conjunto de distritos do Brasil a partir dos identificadores das regiões.
+    # Pode ser informada a sigla, identificador (ID) ou um array de siglas/identificadores.
+    #
+    # @param regioes [String, Integer, Array]
+    # @return [Array<Distrito>]
+    #
+    # @example
+    #           distritos = IBGE::Distrito.distritos_por_regiao('NE')
+    #           distritos.last.nome #=> "Zé Doca"
+    #
+    #           IBGE::Distrito.distritos_por_regiao(['NE', 'N'])
+    #           IBGE::Distrito.distritos_por_regiao([1, 2])
+    def self.distritos_por_regiao(regioes)
+      regioes  = IBGE.formatar(regioes)
+      resposta = RestClient.get("#{BASE_URL}/regioes/#{regioes}/distritos")
+      
+      tratar_retorno(resposta)
+    end
+
+    # Obtém o conjunto de distritos do Brasil a partir dos identificadores dos municípios.
+    # Pode ser informado um único ID ou um array de IDs.
+    #
+    # @param municipios [String, Integer, Array]
+    # @return [Array<Distrito>]
+    #
+    # @example
+    #           distritos = IBGE::Distrito.distritos_por_municipio('2307254')
+    #           distritos.first.nome #=> "Jijoca de Jericoacoara"
+    #
+    #           distritos = IBGE::Distrito.distritos_por_regiao(["2307254", "2302206"])
+    def self.distritos_por_municipio(municipios)
+      municipios = IBGE.formatar(municipios) 
+      resposta   = RestClient.get("#{BASE_URL}/municipios/#{municipios}/distritos")
+      
+      tratar_retorno(resposta)
+    end
+
+    # Obtém o conjunto de distritos do Brasil a partir dos identificadores das regiões imediatas.
+    # Pode ser informado um único ID ou um array de IDs.
+    #
+    # @param regioes [String, Integer, Array] Um ou mais identificadores de regiões imediatas.
+    # @return [Array<Distrito>]
+    #
+    # @example
+    #           distritos = IBGE::Distrito.distritos_por_regiao_imediata(230001)
+    #           distritos.first.nome #=> "Aquiraz"
+    #
+    #           distritos = IBGE::Distrito.distritos_por_regiao_imediata([230001, 230002])
+    def self.distritos_por_regiao_imediata(regioes)
+      regioes  = IBGE.formatar(regioes)
+      resposta = RestClient.get("#{BASE_URL}/regioes-imediatas/#{regioes}/distritos")
+    
+      tratar_retorno(resposta)
+    end
+
+    # Obtém o conjunto de distritos do Brasil a partir dos identificadores das regiões intermediárias.
+    # Pode ser informado um único ID ou um array de IDs.
+    #
+    # @param regioes [String, Integer, Array] Um ou mais identificadores de regiões intermediárias.
+    # @return [Array<Distrito>]
+    #
+    # @example
+    #           distritos = IBGE::Distrito.distritos_por_regiao_intermediaria(2301)
+    #           distritos.first.nome #=> "Acarape"
+    #
+    #           distritos = IBGE::Distrito.distritos_por_regiao_intermediaria([2301, 2302])
+    def self.distritos_por_regiao_intermediaria(regioes)
+      regioes  = IBGE.formatar(regioes)
+      resposta = RestClient.get("#{BASE_URL}/regioes-intermediarias/#{regioes}/distritos")
+    
+      tratar_retorno(resposta)
+    end
+
+    # Obtém o conjunto de distritos do Brasil a partir dos identificadores das mesorregiões.
+    # Pode ser informado um único ID ou um array de IDs.
+    #
+    # @param mesorregioes [String, Integer, Array] Um ou mais identificadores de mesorregiões.
+    # @return [Array<Distrito>]
+    #
+    # @example
+    #           distritos = IBGE::Distrito.distritos_por_mesorregiao(2303)
+    #           distritos.first.nome #=> "Aquiraz"
+    #
+    #           distritos = IBGE::Distrito.distritos_por_mesorregiao([2303, 2304])
+    def self.distritos_por_mesorregiao(mesorregioes)
+      mesorregioes = IBGE.formatar(mesorregioes)
+      resposta     = RestClient.get("#{BASE_URL}/mesorregioes/#{mesorregioes}/distritos")
+    
+      tratar_retorno(resposta)
+    end
+
+    # Obtém o conjunto de distritos do Brasil a partir dos identificadores das microrregiões.
+    # Pode ser informado um único ID ou um array de IDs.
+    #
+    # @param microrregioes [String, Integer, Array] Um ou mais identificadores de microrregiões.
+    # @return [Array<Distrito>]
+    #
+    # @example
+    #           distritos = IBGE::Distrito.distritos_por_microrregiao(23016)
+    #           distritos.last.nome #=> "Senador Carlos Jereissati"
+    #
+    #           distritos = IBGE::Distrito.distritos_por_microrregiao([23016, 23017])
+    def self.distritos_por_microrregiao(microrregioes)
+      microrregioes = IBGE.formatar(microrregioes)
+      resposta      = RestClient.get("#{BASE_URL}/microrregioes/#{microrregioes}/distritos")
+    
+      tratar_retorno(resposta)
+    end
+
+    private
+
+    def self.tratar_retorno(resposta)
+      distritos = JSON.parse(resposta.body)
+
+      distritos.map { |distrito| Distrito.new(distrito) }
+    end
+  end
+end
+

data/lib/ibge/mesorregiao.rb

@@ -0,0 +1,92 @@
+module IBGE
+  class Mesorregiao
+    attr_accessor :id, :nome, :uf
+
+    def initialize(options = {})
+      @id   = options['id']
+      @nome = options['nome']
+      @uf   = IBGE::UF.new(options['UF'])
+    end
+
+    # Obtém o conjunto de mesorregiões do Brasil.
+    #
+    # @return [Array<Mesorregiao>]
+    #
+    # @example
+    #           mesorregioes = IBGE::Mesorregiao.obter_mesorregioes
+    #           mesorregioes.first.nome #=> "Madeira-Guaporé"
+    def self.obter_mesorregioes
+      resposta = RestClient.get("#{BASE_URL}/mesorregioes")
+
+      tratar_retorno(resposta)
+    end
+
+    # Obtém o conjunto de mesorregiões do Brasil a partir dos identificadores das Unidades da Federação.
+    # Pode ser informada a sigla, identificador (ID) ou um array de siglas/identificadores. 
+    # 
+    # @param ufs [String, Integer, Array]
+    # @return [Array<Mesorregiao>]
+    #
+    # @example
+    #           mesorregioes = IBGE::Mesorregiao.mesorregioes_por_uf('CE')
+    #           mesorregioes.first.nome #=> "Noroeste Cearense"
+    #
+    #           IBGE::Mesorregiao.mesorregioes_por_uf(['BA', 'CE'])
+    #           IBGE::Mesorregiao.mesorregioes_por_uf(23) 
+    def self.mesorregioes_por_uf(ufs)
+      ufs      = IBGE.formatar(ufs)
+      resposta = RestClient.get("#{BASE_URL}/estados/#{ufs}/mesorregioes")
+
+      tratar_retorno(resposta)
+    end
+
+    # Obtém o conjunto de mesorregiões do Brasil a partir dos respectivos identificadores.
+    # Pode ser informado um único ID ou um array de IDs.
+    #
+    # @param ids [String, Integer, Array]
+    # @return [Mesorregiao, Array<Mesorregiao>]
+    #
+    # @example
+    #           mesorregiao = IBGE::Mesorregiao.mesorregioes_por_id(2303)
+    #           mesorregiao.nome #=> "Metropolitana de Fortaleza"
+    #
+    #           mesorregioes = IBGE::Mesorregiao.mesorregioes_por_id([2303, 2304])
+    def self.mesorregioes_por_id(ids)
+      ids      = IBGE.formatar(ids)
+      resposta = RestClient.get("#{BASE_URL}/mesorregioes/#{ids}")
+      
+      tratar_retorno(resposta)
+    end
+
+    # Obtém o conjunto de mesorregiões do Brasil a partir dos identificadores das regiões.
+    # Pode ser informada a sigla, identificador (ID) ou um array de siglas/identificadores.
+    #
+    # @param regioes [String, Integer, Array]
+    # @return [Array<Mesorregiao>]
+    #
+    # @example
+    #           mesorregioes = IBGE::Mesorregiao.mesorregioes_por_regiao('NE')
+    #           mesorregioes.first.nome #=> "Norte Maranhense"
+    #
+    #           IBGE::Mesorregiao.mesorregioes_por_regiao(['NE', 'N'])
+    #           IBGE::Mesorregiao.mesorregioes_por_regiao([1, 2])
+    def self.mesorregioes_por_regiao(regioes)
+      regioes  = IBGE.formatar(regioes)
+      resposta = RestClient.get("#{BASE_URL}/regioes/#{regioes}/mesorregioes")
+
+      tratar_retorno(resposta)
+    end
+
+    private
+
+    def self.tratar_retorno(resposta)
+      mesorregioes = JSON.parse(resposta.body)
+
+      if mesorregioes.is_a?(Array) 
+        mesorregioes.map { |mesorregiao| Mesorregiao.new(mesorregiao) }
+      else
+        Mesorregiao.new(mesorregioes)
+      end 
+    end
+  end
+end

data/lib/ibge/microrregiao.rb

@@ -0,0 +1,110 @@
+module IBGE
+  class Microrregiao
+    attr_accessor :id, :nome, :mesorregiao
+
+    def initialize(options = {})
+      @id          = options['id']
+      @nome        = options['nome']
+      @mesorregiao = Mesorregiao.new(options['mesorregiao'])
+    end
+
+    # Obtém o conjunto de microrregiões do Brasil.
+    #
+    # @return [Array<Microrregiao>]
+    #
+    # @example
+    #           microrregioes = IBGE::Microrregiao.obter_microrregioes
+    #           microrregioes.first.nome #=> "Porto Velho"
+    def self.obter_microrregioes
+      resposta = RestClient.get("#{BASE_URL}/microrregioes")
+
+      tratar_retorno(resposta)
+    end
+    
+    # Obtém o conjunto de microrregiões do Brasil a partir dos respectivos identificadores.
+    # Pode ser informado um único ID ou um array de IDs.
+    #
+    # @param ids [String, Integer, Array] Um ou mais identificadores de microrregiões.
+    # @return [Microrregiao, Array<Microrregiao>]
+    #
+    # @example
+    #           microrregiao = IBGE::Microrregiao.microrregioes_por_id(23015)
+    #           microrregiao.nome #=> "Cascavel"
+    #
+    #           microrregioes = IBGE::Microrregiao.microrregioes_por_id([23015, 23016])
+    def self.microrregioes_por_id(ids)
+      ids      = IBGE.formatar(ids)
+      resposta = RestClient.get("#{BASE_URL}/microrregioes/#{ids}")
+
+      tratar_retorno(resposta)
+    end
+
+    # Obtém o conjunto de microrregiões do Brasil a partir dos identificadores das Unidades da Federação.
+    # Pode ser informada a sigla, identificador (ID) ou um array de siglas/identificadores. 
+    # 
+    # @param ufs [String, Integer, Array]
+    # @return [Array<Microrregiao>]
+    #
+    # @example
+    #           microrregioes = IBGE::Microrregiao.microrregioes_por_uf('CE')
+    #           microrregioes.first.nome #=> "Litoral de Camocim e Acaraú"
+    #
+    #           IBGE::Microrregiao.microrregioes_por_uf(['BA', 'CE'])
+    #           IBGE::Microrregiao.microrregioes_por_uf(23) 
+    def self.microrregioes_por_uf(ufs)
+      ufs      = IBGE.formatar(ufs)
+      resposta = RestClient.get("#{BASE_URL}/estados/#{ufs}/microrregioes")
+
+      tratar_retorno(resposta)
+    end
+
+    # Obtém o conjunto de microrregiões do Brasil a partir dos identificadores das regiões.
+    # Pode ser informada a sigla, identificador (ID) ou um array de siglas/identificadores.
+    #
+    # @param regioes [String, Integer, Array]
+    # @return [Array<Microrregiao>]
+    #
+    # @example
+    #           microrregioes = IBGE::Microrregiao.microrregioes_por_regiao('NE')
+    #           microrregioes.first.nome #=> "Litoral Ocidental Maranhense"
+    #
+    #           IBGE::Microrregiao.microrregioes_por_regiao(['NE', 'N'])
+    #           IBGE::Microrregiao.microrregioes_por_regiao([1, 2])
+    def self.microrregioes_por_regiao(regioes)
+      regioes  = IBGE.formatar(regioes)
+      resposta = RestClient.get("#{BASE_URL}/regioes/#{regioes}/microrregioes")
+
+      tratar_retorno(resposta)
+    end
+
+    # Obtém o conjunto de microrregiões do Brasil a partir dos identificadores das mesorregiões.
+    # Pode ser informado um único ID ou um array de IDs.
+    #
+    # @param ids [String, Integer, Array] Um ou mais identificadores de mesorregiões.
+    # @return [Microrregiao, Array<Microrregiao>]
+    #
+    # @example
+    #           microrregioes = IBGE::Microrregiao.microrregioes_por_mesorregiao(2303)
+    #           microrregioes.first.nome #=> "Fortaleza"
+    #
+    #           microrregioes = IBGE::Microrregiao.microrregioes_por_mesorregiao([2303, 2304])
+    def self.microrregioes_por_mesorregiao(mesorregioes)
+      mesorregioes = IBGE.formatar(mesorregioes)
+      resposta     = RestClient.get("#{BASE_URL}/mesorregioes/#{mesorregioes}/microrregioes")
+      
+      tratar_retorno(resposta)
+    end
+
+    private
+
+    def self.tratar_retorno(resposta)
+      microrregioes = JSON.parse(resposta.body)
+
+      if microrregioes.is_a?(Array) 
+        microrregioes.map { |microrregiao| Microrregiao.new(microrregiao) }
+      else
+        Microrregiao.new(microrregioes)
+      end 
+    end
+  end
+end