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.

$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 => '' }

        }

SEE ALSO

WWW::Correios::SRO

AUTHOR

Renato CRON, <rentocron@cpan.org>

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.