view release on metacpan or  search on metacpan

lib/Address/PostCode/Australia.pm  view on Meta::CPAN

package Address::PostCode::Australia;

$Address::PostCode::Australia::VERSION   = '0.12';
$Address::PostCode::Australia::AUTHORITY = 'cpan:MANWAR';

=head1 NAME

Address::PostCode::Australia - Interface to the Australia PostCode.

=head1 VERSION

Version 0.12

=cut

use 5.006;
use JSON;
use Data::Dumper;
use Address::PostCode::UserAgent;
use Address::PostCode::Australia::Place;
use Address::PostCode::Australia::Params qw(validate);

use Moo;
use namespace::autoclean;
extends 'Address::PostCode::UserAgent';

our $BASE_URL = 'https://auspost.com.au/api/postcode/search.json';
has 'auth_key' => (is => 'ro', required => 1);

=head1 DESCRIPTION

Interface to the API provided by L<AusPost|http://auspost.com.au>.

To use the API, you would need auth key, which you can get it L<here|https://developers.auspost.com.au/apis/pacpcs-registration>.

More details can be found L<here|https://developers.auspost.com.au/apis/pac/reference/postcode-search>.

=head1 SYNOPSIS

    use strict; use warnings;
    use Address::PostCode::Australia;

    my $auth_key = 'Your Auth Key';
    my $postcode = 3002;
    my $address  = Address::PostCode::Australia->new({ auth_key => $auth_key });
    my $places   = $address->details({ postcode => $postcode });

    print "Location: ", $places->[0]->location, "\n";
    print "State   : ", $places->[0]->state,    "\n";

=head1 CONSTRUCTOR

The only parameter requires is the auth key.

    use strict; use warnings;
    use Address::PostCode::Australia;

    my $auth_key = 'Your Auth Key';
    my $address  = Address::PostCode::Australia->new({ auth_key => $auth_key });

=head2 details(\%params)

It returns ref  to list of objects of type L<Address::PostCode::Australia::Place>
on success. The parameters requires are list below:

    +----------+----------------------------------------------------------------+
    | Name     | Description                                                    |
    +----------+----------------------------------------------------------------+
    | postcode | Mandatory parameter unless location is passed.                 |
    |          |                                                                |
    | location | Mandatory paramerer unless postcode is passed.                 |
    |          |                                                                |
    | state    | Optional parameter.                                            |
    +----------+----------------------------------------------------------------+

=cut

sub details {