Claudio Garcia > WebService-Mappoint-0.30 > WebService::Mappoint

Download:
WebService-Mappoint-0.30.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.3   Source  

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)

syntax highlighting: