view release on metacpan or  search on metacpan

lib/Google/Directions/Client.pm  view on Meta::CPAN

package Google::Directions::Client;
use Carp;
use Digest::SHA qw/sha256_hex/;
use Encode qw/encode_utf8/;
use Google::Directions::Response;
use JSON qw/decode_json/;
use LWP::UserAgent;
use Moose;
use MooseX::Params::Validate;
use MooseX::WithCache;
use Try::Tiny;
use URL::Encode qw/url_encode/;

with 'MooseX::WithCache' => {
    backend => 'Cache::FastMmap',
    };


=head1 NAME

Google::Directions - Query directions from the google maps directions API

=head1 VERSION

Version 0.09

=cut

our $VERSION = '0.09';

=head1 DESCRIPTION

An interface to Google Maps Directions API V3.

More details about what the API can do can be found on the L<API website|http://code.google.com/apis/maps/documentation/directions/>

=head1 SYNOPSIS

    use Google::Directions::Client;

    my $goog = Google::Directions::Client->new();
    my $response = $goog->directions(
        origin      => '25 Thompson Street, New York, NY, United States',
        destination => '34 Lafayette Street, New York, NY, United States',
        );

=head1 ATTRIBUTES

=over 4

=item I<keep_alive> Enable keep_alive for the user agent.

B<Warning:> This causes occasional errors due to partial content being returned... I'm not sure
what the root cause for this is... :(

=item I<user_agent> Define a custom L<LWP::UserAgent> if you like.

=item I<cache> Define a Cache::FastMmap if you would like to have results cached for better performance

=item I<base_url> Default: C<https://maps.googleapis.com>

=item I<api_path> Default: C</maps/api/directions/json>

=item I<limit_path_length> limit is documented at 2048, but errors occur at 2047.. Default: 2046


=back

=cut

has 'keep_alive'            => ( is => 'ro', isa => 'Int',  required => 1, default => 0              );

has 'user_agent'            => ( 
    is          => 'ro', 
    isa         => 'LWP::UserAgent',
    writer      => '_set_user_agent',
    predicate   => '_has_user_agent',
    );

has 'base_url'              => ( is => 'ro', isa => 'Str', 
    default => 'https://maps.googleapis.com' );

has 'api_path'              => ( is => 'ro', isa => 'Str',
    default => '/maps/api/directions/json' );

has 'limit_path_length'      => ( is => 'ro', isa => 'Int', default => 2046 );

# Create a LWP::UserAgent if necessary
around 'user_agent' => sub {
    my $orig = shift;
    my $self = shift;
    unless( $self->_has_user_agent ){
	if( $self->keep_alive and not $ENV{NO_WARN_KEEPALIVE} ){
	    carp( "Warning - keep_alive gives unreliable results - partial JSON returned\n" .
                "Set the enviroment variable NO_WARN_KEEPALIVE to hide this warning\n" );
	}
	my $ua = LWP::UserAgent->new(
	    'keep_alive' => $self->keep_alive,
	    );
        $self->_set_user_agent( $ua );
    }
    return $self->$orig;
};

=head1 METHODS

=head2 directions 

Returns a L<Google::Directions::Response>

=head3 params

See the API documentation L<here|http://code.google.com/apis/maps/documentation/directions/#RequestParameters> for details

=over 4 

=item I<origin> $string

=item I<destination> $string

=item I<mode> $string (Default: 'driving')

=item I<waypoints> ArrayRef[$string] (optional)

=item I<alternatives> $boolean (Default: 0)

=item I<avoid> ArrayRef[$string] (optional)

=item I<region> $string (optional)

=item I<sensor> $boolean (Default: 0)

=back

=cut

sub directions {
    my ( $self, %params ) = validated_hash(
        \@_,
        origin              => { isa => 'Str' },
        destination         => { isa => 'Str' },
        mode                => { isa => 'Str', default => 'driving' },
        waypoints           => { isa => 'ArrayRef[Str]', optional => 1 },
        alternatives        => { isa => 'Bool', optional => 1 },
        avoid               => { isa => 'ArrayRef[Str]', optional => 1 },
        #units               => { isa => 'Str', default => 'metric' }, # value is always in meters, only affects text, so irrelevant for exact computation
        region              => { isa => 'Str', optional => 1 },
        sensor              => { isa => 'Bool', default => 0 },
    );

    my @query_params;
    foreach( qw/origin destination mode units region/ ){
        if( defined( $params{$_} ) ){
            push( @query_params, sprintf( "%s=%s",
                $_, url_encode( $params{$_} ) ) );
        }
    }