Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/prodis/correios-cep
Find Brazilian addresses by zipcode, directly from Correios database. No HTML parsers.
https://github.com/prodis/correios-cep
cep correios correios-cep prodis ruby zipcode
Last synced: 4 days ago
JSON representation
Find Brazilian addresses by zipcode, directly from Correios database. No HTML parsers.
- Host: GitHub
- URL: https://github.com/prodis/correios-cep
- Owner: prodis
- License: apache-2.0
- Created: 2014-02-11T22:13:06.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2021-09-15T14:03:20.000Z (over 3 years ago)
- Last Synced: 2024-12-13T22:17:41.063Z (11 days ago)
- Topics: cep, correios, correios-cep, prodis, ruby, zipcode
- Language: Ruby
- Homepage:
- Size: 116 KB
- Stars: 168
- Watchers: 16
- Forks: 33
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Correios CEP
[](http://badge.fury.io/rb/correios-cep)
[](https://travis-ci.org/prodis/correios-cep)
[](https://coveralls.io/github/prodis/correios-cep?branch=master)
[](https://codeclimate.com/github/prodis/correios-cep)
[](LICENSE)
Current available solutions to find Brazilian addresses by zipcode use an HTML form from [Correios web site](http://correios.com.br) website to perform it, instead of to use a real API.
The old solution works with an HTTP request to the form, followed by parsing HTML result page. The huge problem here is when the Correios web site development team decides to modify some HTML element in the result page, even a layout update, it will break the parser logic for result.
Correios CEP gem solves this problem, retrieving data directly from Correios database.
## Installing
### Gemfile
```ruby
gem 'correios-cep'
```
### Direct installation
```console
$ gem install correios-cep
```
## Using
```ruby
require 'correios-cep'
# With "get" instance method
finder = Correios::CEP::AddressFinder.new
address = finder.get('54250610')
# With "get" class method
address = Correios::CEP::AddressFinder.get('54250610')
address # =>
{
:address => 'Rua Fernando Amorim',
:neighborhood => 'Cavaleiro',
:city => 'Jaboatão dos Guararapes',
:state => 'PE',
:zipcode => '54250610',
:complement => ''
}
```
## Configurations
All the configurations are set using `Correios::CEP` module.
### Timeout
For default, the timeout for a request to Correios Web Service is **5 seconds**. If Correios Web Service does not respond, a `HTTP::TimeoutError` exception will be raised.
```ruby
Correios::CEP.configure do |config|
config.request_timeout = 3 # It configures timeout to 3 seconds
end
```
### HTTP Proxy
If you need to use an HTTP proxy to HTTP requests, configure HTTP proxy URL.
```ruby
Correios::CEP.configure do |config|
config.proxy_url = 'http://10.20.30.40:8888'
end
```
### Log
From `0.7.0` version, there is no more default logger, and the log level will be the same of the given logger.
```ruby
Correios::CEP.configure do |config|
config.logger = Rails.logger
end
```
### Configuration example
```ruby
Correios::CEP.configure do |config|
config.logger = Rails.logger
config.request_timeout = 3 # seconds
end
```
## Credits
### Author
[Fernando Hamasaki de Amorim (prodis)](https://github.com/prodis)
### Contributors
https://github.com/prodis/correios-cep/graphs/contributors
## Contributing
See the [contributing guide](https://github.com/prodis/correios-cep/blob/master/CONTRIBUTING.md).
## License
Correios CEP gem is released under the Apache 2.0 License. See the [LICENSE](https://github.com/prodis/correios-cep/blob/master/LICENSE) file.