The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Net-Mappoint-0.30
++
/ Net::Mappoint

NAME

Net::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 Net::Mappoint;
     use MIME::Base64;

     my $render = new Net::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

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

The following classes exist:

        Net::Mappoint::Common
        Net::Mappoint::Find
        Net::Mappoint::Render
        Net::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.

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

For parsing the results from Mappoint, the Net::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 Net::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 Net::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 Net::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 Net::Mappoint::Render();

Class and Object methods

Methods that all classes offer (except the Net::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. Net::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 Net::Mappoint::Result class offers a show-method for showing the response from Mappoint in a clear way. The contructor will build a tree of Net::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 Net::Mappoint;
        use MIME::Base64;

        my $render = new Net::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 Net::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)