The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WWW-Correios-CEP-1.03
River stage zero No dependents
++
/ WWW::Correios::CEP

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, uf

DESCRIPTION

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 [, $as_html_tree ] )

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 $as_html_tree is passed, the list hahsref is changed to raw object of HTML::TreeBuilder::XPath->findnodes()

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\:\:CEP

Github

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!

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.