/ 
WebService-Mappoint-0.30
River stage zero No dependents
/ WebService::Mappoint

NAME

WebService::Mappoint - Client SOAP implementation for Mappoint, Microsoft's geographic maps web service, based on SOAP::Lite.

SYNOPSIS

Map fetch example for use with Mappoint 3.0 service.

use WebService::Mappoint;
use MIME::Base64;

my $render = new WebService::Mappoint::Render();
my $map;

$map = $render->GetMap(
          specification => [ 
            DataSourceName => 'MapPoint.EU',
            Options => [
                          Format => [
                                       Height => 320,
                                       Width => 320 
                                    ],
                       ],
            Views => [
                        'MapView:ViewByScale' => 
                           [
                              CenterPoint =>
                                [ Latitude => 37.7632, 
                                  Longitude => -122.439702 ],
                              MapScale => 100000000
                           ],
                     ],	
            Pushpins => [ 
              Pushpin => 
                [  
                  IconName => '176',
                  IconDataSource => 'MapPoint.Icons',
                  PinID => 'san_francisco',
                  Label => 'San Francisco',
                  ReturnsHotArea => 'false',
                  LatLong => [ Latitude => 37.7632, 
                               Longitude => -122.439702 ],
                ]
           ]			    
         ] );

my $image = decode_base64($map->result->{MapImage}{MimeData}{Bits});
open( GIF, ">san_francisco.gif" );
print( GIF $image );

Example mappoint.ini file (in /etc or c:\ depending on OS)

[general]
xmlns=http://s.mappoint.net/mappoint-30/

[credentials]
user=MyUserID
password=MyUserPassword

[proxy]
common=http://findv3.mappoint.net/Find-30/Common.asmx
find=http://findv3.mappoint.net/Find-30/FindService.asmx
route=http://routev3.mappoint.net/Route-30/RouteService.asmx
render=http://renderv3.mappoint.net/Render-30/RenderService.asmx

[UserInfoHeader]
DefaultDistanceUnit=km

[Culture]
Name=nl
LCID=19

[Debug]
;proxy=http://localhost/cgi-bin/soaptest.cgi
;readable=1

SOAP::Mappoint supports both 3.0 and 2.0 servers. See subsection Mappoint 2.0 Example below for an equivalent 2.0 example.

DESCRIPTION

Overview

WebService::Mappoint provides an easy to use interface to Microsoft's Mappoint maps web service.

The following classes exist:

WebService::Mappoint::Common
WebService::Mappoint::Find
WebService::Mappoint::Render
WebService::Mappoint::Route

These classes reflect the remote SOAP classes as decribed at

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/mpn30m/html/mpn30intMPNET.asp

and http://msdn.microsoft.com/library/default.asp?url=/library/en-us/mpn20/html/mpdevHeaders.asp?frame=true

and

http://findv3.mappoint.net/Find-30/Common.asmx
http://findv3.mappoint.net/Find-30/FindService.asmx
http://routev3.mappoint.net/Route-30/RouteService.asmx
http://renderv3.mappoint.net/Render-30/RenderService.asmx

http://find.staging.mappoint.net/Find-20/Common.asmx?WDSL
http://find.staging.mappoint.net/Find-20/FindService.asmx?op=FindNearby
http://render.staging.mappoint.net/Render-20/RenderService.asmx?WDSL
http://route.staging.mappoint.net/Route-20/RouteService.asmx?WDSL

The Mappoint classes rely on SOAP::Lite, which is required. The Mappoint classes offer an easier API to the Mappoint services than using SOAP::Lite by itself.

WebService::Mappoint is the base class for the other classes and should not be used solely.

For parsing the results from Mappoint, the WebService::Mappoint::Result class can be used.

Here is an example of creating an imagemap out of the response of GetMap method

    my $map = $render->GetMap(....);
    my $result = new WebService::Mappoint::Result($map);
    my $hot_areas = $result->get_first('HotAreas');

    if( defined $hot_areas ) {

	foreach my $hotarea_elm ( @{$hot_areas->subitems} ) {

	    my $hotarea = $hotarea_elm->attr;

            foreach my $type (qw(IconRectangle LabelRectangle)) {
               my $rect = $hotarea->{$type};
                  $tag .= sprintf('<area shape="rect" coords="%d,%d,%d,%d" href="%s">',
                                $rect->{left},
				$rect->{top},
				$rect->{right},
				$rect->{bottom},
				$hotarea->{PinID} . '.html' );
            }
        }
	$tag .= '</map>';
    }

The ini-file is required and is read at the moment the class WebService::Mappoint is loaded.

Constructor and intialisation

Constructors for all classes (Common, Find, Render and Route) can take an optional parameter to indicate an alternate ini-file to use. This allows coexistance of 3.0 and 2.0 code within the same application, to ease transition. If no parameter is passed, the default ini-file is used (/etc/mappoint.ini or c:\mappoint.ini depending on OS). This feature also allows for placement of ini-files in paths different than the default one. Example:

# produces a render object which will use the servers described
# in /etc/mappoint30.ini
my $render30 = new WebService::Mappoint::Render('/etc/mappoint30.ini');

# produces a render object which will use the servers described
# in the default file ( /etc/mappoint.ini ).
my $render = new WebService::Mappoint::Render();

Class and Object methods

Methods that all classes offer (except the WebService::Mappoint::Result related classes):

$object->set_CustomLogEntry($value)
$object->set_CultureName($value)
$object->set_CultureLCID($value)
$object->set_DefaultDistanceUnit($value)
$object->set_ContectGeoID($value)
$object->set_ContectGeoISO2($value)

The first method deals with the CustomerInfo header, the others deal with the UserInfoHeader.

Other methods are the same as in the description on the earlier mentiond links. However, the parameters are given in a different way. See example in SYNOPSIS.

Note that an anonymous hash is used for attribute of an element and an anonymous array is used for (underlying) elements. These nested data structures are used both to specify Mappoint requests and to present response data.

There is one instance of the 3.0 API in which this nested-structure approach is not enough for fully describing a request. This instance is the MapView class used for GetMap requests. In 3.0 MapView is an abstract class, so a subclass of it needs to be specified via an attribute tag in the request's XML. WebService::Mappoint simplifies this by allowing a subclass name to be specified via a colon separated notation, as follows (see SYNOPSIS example for context):

Views => [
        'MapView:ViewByScale' => 
           [
              CenterPoint =>
                [ Latitude => 37.7632, 
                  Longitude => -122.439702 ],
              MapScale => 100000000
           ],
         ]

The WebService::Mappoint::Result class offers a show-method for showing the response from Mappoint in a clear way. The contructor will build a tree of WebService::Mappoint::ResultElement objects, which have a name, attributes and sub elements. With the get_first($name) method you can get a subtree of an element with name $name. See also the example above for building the image map.

Mappoint 2.0 Example

use WebService::Mappoint;
use MIME::Base64;

my $render = new WebService::Mappoint::Render;

my $map = $render->GetMap(
	view => [
		MapView => [
			CenterPoint => {
				Latitude => 52.1309,
				Longitude => 5.42743
			},
			Scale => 2000000
		],
	],
	options => [
		Format => [
			Width => 500,
			Height => 500
		],
		GeoDataSource => [
			Name => 'MapPoint.EU'
		]
	]
);

my $image = decode_base64($map->result->{MapImage}{Image}{Bits});
open(GIF, ">/tmp/image.gif");
print(GIF $image);

Example mappoint.ini file (in /etc or c:\ depending on OS) with Mappoint 2.0 servers.

[credentials]
user=MyUserid
password=MyPassword

[proxy]
common=http://find.staging.mappoint.net/Find-20/Common.asmx
find=http://find.staging.mappoint.net/Find-20/FindService.asmx
render=http://render.staging.mappoint.net/Render-20/RenderService.asmx
route=http://route.staging.mappoint.net/Route-20/RouteService.asmx

[UserInfoHeader]
DefaultDistanceUnit=km

[Culture]
Name=nl
LCID=19

[Debug]
;proxy=http://localhost/cgi-bin/soaptest.cgi
;readable=1

Sample code for generating Image map from Mappoint 2.0 responses.

my $map = $render->GetMap(....);
my $result = new WebService::Mappoint::Result($map);
my $active_area = $result->get_first('ActiveArea');

foreach my $hotarea_elm (@{$active_area->subitems}) {
    my $hotarea = $hotarea_elm->attr;

	foreach my $type (qw(IconRectangle LabelRectangle)) {
		my $rect = $hotarea->{$type};
		$tag .= sprintf('<area shape="rect" coords="%d,%d,%d,%d" href="%s">',
			$rect->{left},
			$rect->{top},
			$rect->{right},
			$rect->{bottom},
			$hotarea->{PinID} . '.html'
		);
	}
}
$tag .= '</map>';

ENVIRONMENT

DIAGNOSTICS

BUGS

Probably ;-)

FILES

mappoint.ini

The mappoint.ini file supports also a [Debug] section, where a proxy can be defined you want to use for test purposes. You can also force a readable(1) so that the xml output is more readable in trace mode (when you do +trace=>'all').

[Debug]
proxy=http://localhost/cgi-bin/soaptest.cgi
readable=1

SEE ALSO

AUTHOR(S)

Herald van der Breggen (herald at breggen. xs4all. nl) Claudio Garcia (claudio.garcia at stanfordalumni. org)