CepFacil
Ruby wrapper para o serviço em cepfacil.com.br
Instalação
NOTA: Esse projeto encontra-se na versão 1.x, cuja API difere completamente das versões 0.x. Se você está procurando a versão mais antiga, veja a branch 0x, que se mantém intacta.
No Gemfile
:
gem "cep_facil"
Ou via RubyGems, diretamente:
$ gem install cep_facil
Uso
Obtendo um endereço pelo CEP
Para usar a API do CepFácil, você precisa obter um token do serviço. Você obtém esse token gratuitamente em cepfacil.com.br
require "cep_facil"
cep = "53417-540"
token = "1234567890"
address = CepFacil::API.new(cep, token)
### Acesso rápido via método de classe
address = CepFacil::API.get(cep, token) # Hash Notation => CepFacil::API.get(cep: cep, token: token)
# Argumentos como Hashes
address = CepFacil::API.new(cep: cep, token: token, format: "texto")
Retorna o endereço referente àquele CEP
O retorno é um objeto CepFacil::API
que contem os seguintes métodos (propriedades) :
address.cep # => "53417540"
address.type # => "Rua"
address.state # => "PE"
address.city # => "Paulista"
address.neighborhood # => "Artur Lundgren II"
address.street # => "Panelas"
# Também é possivel acessar utilizando metodos em português
address.tipo # => "Avenida"
address.rua # => "Francisco Navarro"
address.cidade # => "Varginha"
address.bairro # => "Centro"
address.estado # => "MG"
address.uf # => "MG"
Embora isso deva parecer óbvio, informo que essas propriedades são todas READONLY.
Você pode checar se o endereço retornado é válido utilizando o método valid?
:
address = CepFacil::API.new "53020-140", token
address.valid? # true
Adicionalmente, seu objeto CepFacil::API
possui um método full_format
e seu alias (full_address
) que o descreve por extenso:
address.full_format # => "Rua Panelas, Paulista - PE, Brasil"
address.full_address # => Avenida Francisco Navarro, Varginha - MG, Brasil" # Alias
Você pode passar o CEP como uma string qualquer, letras, caracteres especiais (pontos, hífens) são removidos automaticamente.
"12345-678"
"123.45.678"
"123-456.78"
"12345678"
12345678 # Não recomendado, prefira utilizar Strings
Integração com a gem Geocoder
A gem Geocoder é ótima para uso e manipulação de dados geográficos em projetos Ruby. Para integrá-la com o CepFacil, faça assim:
geocoded_by address.full_format
Autor
- Rodrigo Alves Vieira - [email protected] - http://www.rodrigoalvesvieira.com
Contribuidores
- Adriano Bacha - [email protected]
- Rafael Fidelis - [email protected] | http://defidelis.com
Agradecimentos
Obrigado pelas pessoas que oferecem o serviço CepFácil, sem o qual esse projeto não seria possível.
Obrigado também aos Contribuidores desse projeto.
Licença
CepFacil é liberado sob a licença do MIT com atribuições a Rodrigo Alves Vieira.