WebService::Mappoint - Client SOAP implementation for Mappoint, Microsoft's geographic maps web service, based on SOAP::Lite.
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.
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.
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();
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.
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>';
Probably ;-)
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
Herald van der Breggen (herald at breggen. xs4all. nl) Claudio Garcia (claudio.garcia at stanfordalumni. org)
To install WebService::Mappoint, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WebService::Mappoint
CPAN shell
perl -MCPAN -e shell install WebService::Mappoint
For more information on module installation, please visit the detailed CPAN module installation guide.