NAME
WWW::Correios::CEP - Perl extension for extract address from CEP (zip code) number
SYNOPSIS
use WWW::Correios::CEP;
my $cep = WWW::Correios::CEP->new();
my $address = $cep->find( $cep );
print $address->{street}; # neighborhood, location, ufDESCRIPTION
This module fetches CEP information (Brazilian ZIP codes) directly from the Correios website, Brazil's official post office company.
Good to know
Also, check if the returned CEP matches the informed CEP, some addresses can changed from time to time, for example, 49039-050 is now 49009-010 (today is 2020-07-04). Correios still return the address street name, but some providers may not accept it anymore (eg: payment gateways)
Correios API is sometimes unstable, please have a fallback!
METHODS
new
Creates a new instance of WWW::Correios::CEP. Accepts the following arguments:
timeout
when to give up connecting to the Correios website. Defaults to 30 seconds.
user_agent
User Agent string. Default to "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)"
post_url
Where to post the query. Defaults to Correios' current location (we hope!)
post_content
What to post in the query. Defaults to Correios' standard options (we hope!)
lwp_options
Extra options to pass to LWP::UserAgent.
find( $cep [, $all_result_raw ] )
Recieves the CEP string and tries to get address data. Returns a hashref with the following keys:
street
neighborhood
location
uf
status
If there is more than one address, it returns a list of hashrefs in list context, or just the first hashref in scalar context, together with an "address_count" key with the total returned addresses.
If $all_result_raw is passed, return a list of all results from correios
SEE ALSO
WWW::Correios::SRO
BUGS AND LIMITATIONS
You may reports on github:
https://github.com/renatocron/WWW--Correios--CEP/issues
SUPPORT
Perldoc
You can find documentation for this module with the perldoc command.
perldoc WWW\:\:Correios\:\:CEPGithub
If you want to contribute with the code, you can fork this module on github:
https://github.com/renatocron/WWW--Correios--CEP
AUTHOR
Renato CRON, <rentocron@cpan.org>
ACKNOWLEDGEMENTS
2011 - Special thanks to Gabriel "gabiru" Andrade for providing a better solution for finding addresses!
2014 - Thanks to Garu, for removing legacy test code and improving docs!
2020- Nov 14, Correios now have a json result, and now this module is here just for retrocompatibility, html parsing is not required anymore.
COPYRIGHT AND LICENSE
Copyright (C) 2011-2014 by RenatoCRON
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.
See http://dev.perl.org/licenses/ for more information.