NAME

WebService::StreetMapLink - An API for generating links to online map services

SYNOPSIS

    use WebService::StreetMapLink;

    my $map =
        WebService::StreetMapLink->new
            ( country => 'usa',
              address => '100 Some Street',
              city    => 'Testville',
              state   => 'MN',
              postal_code => '12345',
            );

    my $uri = $map->uri;

DESCRIPTION

This class defines an API for classes which generate links to various online map services like MapQuest or Multimap. It also provides a constructor which will dispatch to an appropriate subclass based on the country being mapped.

METHODS

new()

This method constructs a new object of some WebService::StreetMapLink subclass.

This method accepts the following parameters:

• country

  This parameter determined which subclass will be used. If more than one subclass is available for the country, then one will be chosen more or less at random. You can provide a "subclass" parameter to override the default choice.

  This parameter is required.

• address

• city

• state

  The state or province. Subclasses should be designed to handle either the full name or a standard abbreviation.

• postal_code

  The postal or zip code.

• subclass

  This can be a full class name like My::Map or just an identifier for an existing WebService::StreetMapLink subclass, like MapQuest.

Subclasses may require certain parameters, and may also accept additional parameters besides those listed.

If the parameter given are not sufficient to generate a map URI for the given country, then this method will simply return false.

uri()

This method returns a string containing the URI of the map link.

uri_object()

This method returns a URI object representing the map link.

service_name()

The name of the service being used for the map, like 'Google' or 'MapQuest'.

SUBCLASSING

Creating a subclass that implements map links is quite simple. The subclass needs to provide a few methods. See the subclasses distributed with this module for examples.

All subclasses must call WebService::StreetMapLink->RegisterSubclass() when loaded. This method accepts one optional argument, the subclass's priority. If not provided, this defaults to 100 (lowest priority).

Countries()

This class method should return an array of country names which the subclass can handle.

new()

This method will receive the same parameters as are given to WebService::StreetMapLink->new, and should return a new object of the given subclass.

If the parameters it receives aren't sufficient to create a map link, it should simply call a bare return.

_scheme(), _host(), _path(), _query()

These methods are used when constructing a URI object. By default, these methods simply look at the "scheme", "host", "path", and "query" keys of the object. The _scheme() method will default to "http".

You are free to override any of these methods in your subclass.

service_name()

This will default to the unique part of your subclass, but you can override this to return any string.

LEGAL BITS

Please check with each service provider regarding their terms of service. Some of them may impose certain conditions on how they can be linked to. The author(s) of these modules are not responsible for any violations of a provider's terms of service committed when using URIs generated by these modules.

SEE ALSO

WebService::StreetMapLink::Google, WebService::StreetMapLink::MapQuest, WebService::StreetMapLink::Multimap, WebService::StreetMapLink::Streetdirectory, WebService::StreetMapLink::Catcha

AUTHOR

David Rolsky, <autarch@urth.org>

BUGS

Please report any bugs or feature requests to bug-webservice-streetmaplink@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT & LICENSE

Copyright 2004-2007 David Rolsky, All Rights Reserved.

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.