NAME

WWW::Correios::CEP - Perl extension for extract address from CEP (zip code) number

SYNOPSIS

        use WWW::Correios::CEP;

        my $cepper = new WWW::Correios::CEP();

        my $address = $cepper->find( $cep );
        # returns hashref like { street => '', neighborhood => '', location => '', uf => 'SP', cep => '', status => '' }

note: if you call "find" before "test" and require_tests is true, tests will be called

DESCRIPTION

This is the documentation for WWW::Correios::CEP

METHODS

List of methods

new WWW::Correios::CEP( { ... } );

Create an instance of WWW::Correios::CEP and configures it

Parameters: require_tests with_tests user_agent post_url post_content

You can see details on "Full Sample" below

$cepper->find( $cep )

Recive and CEP and try to get it address returning an hash ref with street, neighborhood, location, uf, cep and status.

If you call this method on an array scope, it returns an array with each address, if not, address_count key is added to the hash.

$cepper->tests( )

This method make tests on some address for test if WWW::Correios::CEP still ok, you may want keep this, these tests use some time, but it depends on your connection speed/correios site speed.

Retuns 1 if all tests are ok, if false, you may want to call dump_tests to see the changes

$cepper->dump_tests( )

prints on STDOUT results of each test

$cepper->setTests( $array_ref_of_hash )

You can change tests after new too, but you need to call $cepper->tests() if it already called.

$array_ref_of_hash should be an array ref with hashs like "with_tests" bellow

$cepper->getTests( )

return current tests array

INTERNALS

_parseHTML

parse "html" of correios sites

_extractAddress

internal function called on "tests" and "find" methods

Full Sample

        my $cepper = new WWW::Correios::CEP(
                # this is default, you can disable it with a explicit false value,
                require_tests => 1,
                # theses tests may fail if the Correios page have changed.
                # Nevertheless, to not break this class when address/cep changes, you can set a your tests here
                with_tests => [
                        { street => 'Rua Realidade dos Nordestinos', neighborhood => 'Cidade Nova Heliópolis',
                                location => 'São Paulo'     , uf => 'SP', cep => '04236000' },
                        { street => 'Rua Rio Piracicaba'           , neighborhood => 'I.A.P.I.'              ,
                                location => 'Osasco'        , uf => 'SP', cep => '06236040' },
                        { street => 'Rua Hugo Baldessarini'        , neighborhood => 'Vista Alegre'          ,
                                location => 'Rio de Janeiro', uf => 'RJ', cep => '21236040' },
                        { street => 'Avenida Urucará'              , neighborhood => 'Cachoeirinha'          ,
                                location => 'Manaus'        , uf => 'AM', cep => '69065180' }
                ],
                # if you want to change user agent, that defaults to Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)
                user_agent => 'IECA',

                # if you want to change POST url
                post_url => 'http://www.buscacep.correios.com.br/servicos/dnec/consultaLogradouroAction.do',
                
                # if you want to change post content, remenber that "cep number" will be concat on end of this string
                post_content => 'StartRow=1&EndRow=10&TipoConsulta=relaxation&Metodo=listaLogradouro&relaxation='
        );

        eval{$cepper->tests()};
        if($@){
                # you can use $@ if you want just error message
                $cepper->dump_tests;
        }else{
                my $address = $cepper->find( $cep );

                # returns hashref like { street => '', neighborhood => '', location => '', uf => 'SP', cep => '', status => '', address_count => 0 }

                # you can also call find like it:
                my @address = $cepper->find( $cep );

        }

SEE ALSO

WWW::Correios::SRO

AUTHOR

Renato CRON, <rentocron@cpan.org> Special thanks to Gabriel Andrade, <gabiru</lt> http://search.cpan.org/~gabiru/

COPYRIGHT AND LICENSE

Copyright (C) 2011 by Renato

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.

cpanm WWW::Correios::CEP

perl -MCPAN -e shell
install WWW::Correios::CEP