CepFacil

Wrapper Ruby para a API do CepFácil

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"

# Autenticando

token = "1234567890"
conn = CepFacil::API.new token

# Obtendo endereços

zip_code = "53416540"
address = conn.get_address(zip_code)

Retorna o endereço (objeto CepFacil::Address) referente àquele CEP

address.cep # => "53417540"

address.type # => "Rua"

address.state # => "PE"

address.city # => "Paulista"

address.neighborhood # => "Artur Lundgren II"

address.street # => "Panelas"

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.valid? # true

Adicionalmente, seu objeto CepFacil::Address possui um método full_format que o descreve por extenso:

address.full_format # => "RUA PANELAS, PAULISTA - PE 53416540, Brasil"

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

Contribuidores

• Adriano Bacha
• Rafael Fidelis

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. Para detalhes veja o arquivo LICENSE.txt