Dmytro Gorbunov > Geo-Cloudmade > Geo::Cloudmade

Download:
Geo-Cloudmade-0.8.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  1
View/Report Bugs
Module Version: 0.8   Source  

NAME ^

Geo::Cloudmade - An extended interface to Cloudmade's Geo API (geocoding, routing, drawing tiles)

DESCRIPTION ^

  L<Cloudmade|http://cloudmade.com/> is a provider of free map of the world using data
  collected by L<OpenStreetMaps|http://www.openstreetmap.org/> project.

  This module implements an OO wrapper around Cloudmade's Geo API.

  The following capabilities are implemented:
   - geocoding and geosearching
   - routing
   - obtaining tiles

  Please note that some features of the HTTP API aren't wrapped yet by this module.
  If you have any questions or/and suggestions feel free to drop me a mail or create a ticked in rt.cpan.org.

SYNOPSIS ^

  use Geo::Cloudmade;
  
  #use api key for access to service
  my $geo = Geo::Cloudmade->new('BC9A493B41014CAABB98F0471D759707');
  
  #find coordinates of geo object
  my @arr = $geo->find("Potsdamer Platz,Berlin,Germany", {results=>5, skip=>0});

  print $geo->error(), "\n" unless @arr;

  print "Number of results: ", scalar (@arr), "\n";
  foreach (@arr) {
    print $_->name,":\n", $_->centroid->lat, "/", $_->centroid->long, "\n"
  }

  # finding closest POI (Point of Interest)
  # for list all available objects please look at http://developers.cloudmade.com/projects/show/geocoding-http-api
  @arr = $geo->find_closest('library', [59.12, 81.1]);
  print "No closest variants\n" unless @arr;

  # reverse geocoding
  my ($reverse)  = $geo->find_closest('address', [52.4870,13.4248]);
  if (defined $reverse) {
    print join ' ', $reverse->properties('addr:housenumber', 'addr:street', 'addr:postcode', 'addr:city'), "\n";
  } else { print "No results, sorry\n" }

  #calculate route
  my $route = $geo->get_route([47.25976, 9.58423], [47.66117, 9.99882], { type=>'car', method=>'shortest' } );
  print "Distance: ", $route->total_distance, "\n";
  print "Start: ", $route->start, "\n";
  print "End: ", $route->end, "\n";

  print "Route instructions:\n";
  print join (',', @$_), "\n" foreach (@{$route->instructions});

  #get tile
  my $tile = $geo->get_tile([47.26117, 9.59882], {zoom=>10, tile_size=>256});
  open (my $fh, '>', 'test.png') or die "Cannot open file $!\n";
  binmode $fh;
  print $fh $tile;

CONSTRUCTOR ^

new API-KEY

 Usage                :   my $geo = Geo::Cloudmade->new('your-ip-key');
 Function       :   Constructs and returns a new Geo::Cloudmade object
 Returns        :   a Geo::Cloudmade object
 API-KEY        :   api key provided by Cloudmade. For request api key please visit http://developers.cloudmade.com/projects>

OBJECT METHODS ^

find QUERY, PARAMS

 Usage   :    my @arr = $geo->find("Potsdamer Platz,Berlin,Germany", {results=>5, skip=>0});
 Function:    Returns geo objects (bound box and\or location) by query or nothing
 Returns :    Array of Geo::Cloudmade::Result objects or one Geo::Cloudmade::Results if scalar value was expected
 QUERY   :    Query in format POI, House Number, Street, City, County like "Potsdamer Platz, Berlin, Germany".
              Also near is supported in queries, e.g. "hotel near Potsdamer Platz, Berlin, Germany"
 PARAMS  :   Hash for control ouptut. Valid elements are bbox, results, skip, bbox_only, return_geometry, return_location
             For more info about parameters please look at http://developers.cloudmade.com/wiki/geocoding-http-api/Documentation

find_closest OBJECT POINT PARAMS

  Usage: @arr = $geo->find_closest('library', [59.12, 81.1]);
  Function: Find closest object(s).
  Returns array of Geo::Cloudmade::Result objects like find method
  OBJECT - point of interest, list of supported objects located at http://developers.cloudmade.com/projects/show/geocoding-http-api
  POINT  - reference of array of [$lattitude, $longtitude]
  PARAMS - optional parameters like return_geometry and return_location

get_route START_POINT END_POINT PARAMS

  Allowed parameters:
     type => 'car' // 'foot' // 'bicycle'
     method => 'shortest' // fastest' - only for route type 'car', default is 'shortest'
     lang => iso 2 characters code for language for the route instructions, default is en.
             Possible values are: de, en, es, fr, hu, it, nl, ro, ru, se, vi, zh.
     units => (measure units for distance calculation) 'km' // 'miles' (default 'km')

  Usage:
           my $route = $geo->get_route(
                  [47.25976, 9.58423], [47.66117, 9.99882],
                  { type=>'car', method=>'shortest' } );

  Returns:   Geo::Cloudmade::Route object from server or undef if communication with server was unsuccessful.
  Function:  Calculates route from START to END and returns Geo::Cloudmade::Route object
  See also:  Cloudmade's documentation about API for routing.
             http://developers.cloudmade.com/wiki/routing-http-api/Documentation

get_tile CENTER PARAMS

  Returns raw png data of specified map point
  CENTER  array reference to latitude and longtitude
  PARAMS  optional parameters. Allowed parameters are zoom, stile, size
          For more info please look at official documentation from Cloudmade

Geo::Cloudmade::Route ^

  Geo::Cloudmade::Route represents responce of routing request in decoded JSON.
  More details available here http://developers.cloudmade.com/wiki/routing-http-api/Response_structure .

  The following helper functions were added:
    - total_distance - distance in meters. (Probably it should be in requested units, see parameters of get_route)
    - start          - name of the start point of the route,
    - end            - name of the end point of the route,
    - valid          - returns 1 if status is 0 (OK)
    - status_message - text description in case of error
    - instructions   - array of detailed instructions, 
                       see more details in http://developers.cloudmade.com/wiki/routing-http-api/Response_structure 

SEE ALSO ^

 Official documentation about services from Cloudmade http://developers.cloudmade.com/projects
 You can find more specific info about:
   - geocoding and geosearching in http://developers.cloudmade.com/projects/show/geocoding-http-api
   - routing in http://developers.cloudmade.com/projects/show/routing-http-api
   - obtaining tiles in http://developers.cloudmade.com/projects/tiles/documents

AUTHOR ^

Dmytro Gorbunov, <dmitro.gorbunov@gmail.com>

COPYRIGHT AND LICENSE ^

Copyright (C) 2010 by Dmytro Gorbunov

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.9 or, at your option, any later version of Perl 5 you may have available.

syntax highlighting: