Address-PostCode-Australia

 view release on metacpan or  search on metacpan

MANIFEST  view on Meta::CPAN

Changes
lib/Address/PostCode/Australia.pm
lib/Address/PostCode/Australia/Place.pm
lib/Address/PostCode/Australia/Params.pm
Makefile.PL
LICENSE
MANIFEST
MANIFEST.SKIP
README
t/00-load.t
t/01-address-postcode-australia.t
t/02-address-postcode-australia-place.t
t/manifest.t
t/pod.t
t/meta-json.t
t/meta-yml.t
META.yml                                 Module YAML meta-data (added by MakeMaker)
META.json                                Module JSON meta-data (added by MakeMaker)

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

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;

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

    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 {
    my ($self, $params) = @_;

    my $keys     = { postcode => 0, location => 0, state => 0 };
    my $url      = _get_url($keys, $params);
    my $response = $self->get($url, { 'auth-key' => $self->auth_key });
    my $contents = from_json($response->{'content'});

    my $places = [];
    if (ref($contents->{'localities'}->{'locality'}) eq 'ARRAY') {
        foreach my $location (@{$contents->{'localities'}->{'locality'}}) {
            push @$places, Address::PostCode::Australia::Place->new($location);
        }
    }

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

#
#
# PRIVATE METHODS

sub _get_url {
    my ($keys, $values) = @_;

    validate($keys, $values);

    my $url = $BASE_URL;
    if (exists $values->{'postcode'}) {
        $url .= sprintf("?q=%d", $values->{'postcode'});
    }
    elsif (exists $values->{'location'}) {
        $url .= sprintf("?q=%s", $values->{'location'});
    }
    else {
        die "ERROR: Missing required key postcode/location.\n";
    }

    if (exists $values->{'state'}) {
        $url .= sprintf("&state=%s", $values->{'state'});
    }

    return $url;
}

=head1 AUTHOR

Mohammad S Anwar, C<< <mohammad.anwar at yahoo.com> >>

=head1 REPOSITORY

L<https://github.com/manwar/Address-PostCode-Australia>

=head1 BUGS

Please report any bugs or feature requests to C<bug-address-postcode-australia at rt.cpan.org>,
or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Address-PostCode-Australia>.
I will be notified, and then you'll automatically be notified of progress on your
bug as I make changes.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Address::PostCode::Australia

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

};

sub check_str {
    my ($str) = @_;

    die "ERROR: Invalid STR data type [$str]"
        if (defined $str && $str =~ /^\d+$/);
};

our $FIELDS = {
    'postcode' => { check => sub { check_num(@_) }, type => 'd' },
    'location' => { check => sub { check_str(@_) }, type => 's' },
    'state'    => { check => sub { check_str(@_) }, type => 's' },
};

sub validate {
    my ($fields, $values) = @_;

    die "ERROR: Missing params list." unless (defined $values);

    die "ERROR: Parameters have to be hash ref" unless (ref($values) eq 'HASH');

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

=head1 AUTHOR

Mohammad S Anwar, C<< <mohammad.anwar at yahoo.com> >>

=head1 REPOSITORY

L<https://github.com/manwar/Address-PostCode-Australia>

=head1 BUGS

Please report any bugs or feature requests to C<bug-address-postcode-australia at rt.cpan.org>,
or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Address-PostCode-Australia>.
I will be notified, and then you'll automatically be notified of progress on your
bug as I make changes.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Address::PostCode::Australia::Params

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

use Data::Dumper;

use Moo;
use namespace::autoclean;

has 'id'        => (is => 'ro');
has 'category'  => (is => 'ro');
has 'location'  => (is => 'ro');
has 'latitude'  => (is => 'ro');
has 'longitude' => (is => 'ro');
has 'postcode'  => (is => 'ro');
has 'state'     => (is => 'ro');

=head1 DESCRIPTION

It holds the place detailed information as provided by API response. It  provides
simple interface to fetch individual information on request.

=head1 METHODS

=head2 id()

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

Returns the place location.

=head2 latitude()

Returns the place latitude.

=head2 longitude()

Returns the place longitude.

=head2 postcode()

Returns the place postcode.

=head2 state()

Returns the place state.

=head1 AUTHOR

Mohammad S Anwar, C<< <mohammad.anwar at yahoo.com> >>

=head1 REPOSITORY

L<https://github.com/manwar/Address-PostCode-Australia>

=head1 BUGS

Please report any bugs or feature requests to C<bug-address-postcode-australia at rt.cpan.org>,
or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Address-PostCode-Australia>.
I will be notified, and then you'll automatically be notified of progress on your
bug as I make changes.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Address::PostCode::Australia::Place

t/01-address-postcode-australia.t  view on Meta::CPAN

eval { $address->details(1234); };
like($@, qr/ERROR: Parameters have to be hash ref/);

eval { $address->details('XYZ12345'); };
like($@, qr/ERROR: Parameters have to be hash ref/);

eval { $address->details('12345XYZ'); };
like($@, qr/ERROR: Parameters have to be hash ref/);

eval { $address->details({}); };
like($@, qr/ERROR: Missing required key postcode\/location/);