WebService::Geograph::API - Perl interface to the Geograph.co.uk API

WebService-Geograph-API documentation Contained in the WebService-Geograph-API distribution.

Index

Code Index:

NAME

Top

WebService::Geograph::API - Perl interface to the Geograph.co.uk API

SYNOPSIS

Top

  use WebService::Geograph::API;

  my $api = new WebService::Geograph::API ( { 'key' => 'your_api_key_here'} ) ;

  my $rv = $api->lookup ( 'csv', { 'i'     => 12345,
                                   'll'    => 1,
                                   'thumb' => 1,
                                 }) ;

  my $data = $rd->{results} ;

DESCRIPTION

Top

This module provides a simple interface to using the geograph.co.uk API service.

The actual core class, WebService::Geograph::API is a subclass of LWP::UserAgent so all the usual parameters apply.

METHODS

new

The following constructing method creates a new WebService::Geograph::API object and returns it. It accepts a single parameter, key, which is the API key for the service. You must obtain a valid key otherwise you will not be able to use the API.

Obtaining a key is free. See : http://www.geograph.org.uk/help/api#api for more information.

	my $api = new WebService::Geograph::API ( { 'key' => 'your_api_key_here'} ) ;
lookup

Creates a new WebService::Geograph::Request object and executes it.

	my $rv = $api->lookup ( 'csv', { 'i' => 12345, 'll' => 1, } ) ;

	or

	my $rv = $api->lookup ( 'search ', { q = 'W12 8JL' } ) ;

Valid modes at the moment include csv for exporting CSV and search for creating custom searches and obtaining their 'i' number. A very good and detailed overview of the various parameters they support can be find on the API page located at : http://www.geograph.org.uk/help/api#api

This method creates and returns a new WebService::Geograph::Response object. The object is a standard HTTP::Response object with some additional fields. If no errors occur, the results of the query will be located inside results ;

	my $data = $rv->{results} ;
execute_request

Internal method that executes a request and blesses the response into a WebService::Geograph::Response object.

create_results_node

Intenal method which assigns the actual data returned from the API within the response objects 'results' key.

SUPPORT

Top

Please feel free to send any bug reports and suggestions to my email listed below.

For more information and useless facts on my life, you can also check my blog:

  http://idaru.blogspot.com/

AUTHOR

Top

    Spiros Denaxas
    CPAN ID: SDEN
    Lokku Ltd ( http://www.nestoria.co.uk )
    s [dot] denaxas [@] gmail [dot]com

COPYRIGHT

Top

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

Top

WebService::Geograph::Request, WebService::Geograph::Response, http://www.geograph.co.uk, http://www.geograph.org.uk/help/api#api

WebService-Geograph-API documentation Contained in the WebService-Geograph-API distribution. 
package WebService::Geograph::API;

use strict;
use warnings ;

use WebService::Geograph::Request ;
use WebService::Geograph::Response ;

use LWP::UserAgent ;
use Data::Dumper ;

our @ISA = qw ( LWP::UserAgent ) ;
our $VERSION = '0.05' ;


sub new {
	my $class = shift ;
	my $rh_options = shift ;
	
	unless (defined ($rh_options->{key}) and ($rh_options->{key})) {
		warn "You must obtain a valid key before using the Geograph API service.\n" .
		     "Visit http://www.geograph.org.uk/help/api for more information.\n" ;
		return undef ;
	}	
	
	# Please do not change the following parameter. 
	# It does not provide geograph.co.uk with any personal information
	# but helps them track usage of this module.
		
	my %options = ( 'agent' => 'WebService::Geograph::API' ) ;
	my $self = new LWP::UserAgent ( %options );
	$self->{key} = $rh_options->{key} ;
	
	bless $self, $class ;
	return $self ;	

}

sub lookup {
	my ($self, $mode, $args) = (@_) ;
	
	return unless ((defined $mode) && (defined $args)) ;
	return unless ref $args eq 'HASH' ;
	
	$args->{key} = $self->{key} ;
	
	my $request = new WebService::Geograph::Request (  $mode , $args  ) ;	
	if (defined $request) {
		$self->execute_request($request) ;
		} else {
			return ;
		}
}

sub execute_request {
	my ($self, $request) = (@_) ;	
  my $url = $request->encode_args() ;
	
  my $response = $self->get($url) ;
	bless $response, 'WebService::Geograph::Response' ;
	
	unless ($response->{_rc} = 200) {
	  $response->set_fail(0, "API returned a non-200 status code: ($response->{_rc})") ;
		return $response ;
  }
	
	$self->create_results_node($request, $response) ;
	
}

sub create_results_node {
	my ($self, $request, $response) = (@_) ;
	
	if ($request->{mode} eq 'csv') {
		 if (defined $response->{_content}) {
				my $csv_data = $response->{_content} ;
				$response->set_success($csv_data) ;
				return $response ;	
		  }
	}
	
	elsif ($request->{mode} eq 'search') {
		if (defined $response->{_previous}->{_headers}->{location}) {
			my $location = $response->{_previous}->{_headers}->{location} ;
			$response->set_success($location) ;
			return $response ;			
		}
}
		
	
	
	
	
}


#################### main pod documentation end ###################

1;