This page describes how any website or application may be enabled to deliver location data to a compatible navigation device, either through the MSN® Direct wireless network or through a USB connection. For successful wireless delivery, the target device must have active MSN Direct service and be associated with a valid Windows Live ID.

The use of this API is subject to MSN Direct TERMS OF USE.

To send a point of interest (POI) through MSN Direct wireless network, make an HTTP POST request to http://www.msndirect.com/Send/POI.aspx with the following input:

Input Description
collection XML document containing collections of points of interest. Schema described below with example XML.
returnURL [optional] A URL to which the browser will be redirected when the process is complete, posting error codes defined herein. The usage of this parameter is recommended when the HTTP POST is targeted to open in a new browser instance.
As MSN Direct hides the final confirmation page, redirecting URL page is required to show the confirmation for sending the locations to the navigation device. The confirmation message needs to be relevant to the posted error code.
 

The MSN Direct Send to GPS API will then present the user with the choice of sending the data wirelessly with MSN Direct or via USB, and redirect to the appropriate page flow accordingly.

Sending wirelessly with MSN Direct

The MSN Direct Send to GPS API will then handle the following steps:

  1. Windows Live ID authentication is required for sending locations wirelessly. Any existing Windows Live ID ticket will be validated. If valid, the user will continue to step 2. If not valid, the user will be directed through Windows Live ID login, then redirected to step 2.

  2. MSN Direct will deliver up to 20 locations per day wirelessly for a user identified by a Windows Live ID. If the user has a compatible navigation device associated with their MSN Direct account, their service is active, and they have not reached their daily limit, a coverage map is shown for their home region and the user may confirm whether this is where they are currently located. The user may also pick a different region in which to send the locations (this is often useful when traveling).

  3. After region confirmation, messages are queued for delivery. If a return URL was specified, the browser is redirected there and an error code of SUCCESS is posted to that URL (details below). If no return URL was specified, an end page is shown.

Sending with USB

Currently, sending locations via USB is supported on most Garmin GPS navigators, including even those without support for other MSN Direct services. The Garmin Communicator Plugin must be installed in the user's browser. The number of locations delivered to the navigation device via USB is not subject to a daily limit as with wireless delivery.

Collection of Point Elements

The collection parameter of one or more XML collections of locations. Each collection element contains an optional name attribute (maximum 25 characters) and one or more point elements (locations). The collection data is UTF-8 encoded.

Collection Attribute Required Maximum length
<name> No 25 characters that indicate the name of a route or collection of point elements.
 

Independent points of interest

When the name attribute is not present, the point elements in the collection are independent. MSN Direct will iterate through the collection and send all the point elements until an invalid one is detected. If this occurs, a ONE_OR_MORE_POIS_UNDELIVERABLE error is returned, and the remaining points in the collection are not sent.

Routes and collections of points of interest

The presence of the name attribute in the XML collection indicates that the point elements belong to a either a route (when ordered) or a collection of locations. All the points in the XML collection must be valid for an error code of SUCCESS to be returned. Please note that not all navigation devices support the grouping of point elements as collections of locations.

Routes

A point element belongs to a route if the routeID attribute is present.

When the collection element contains a route, all point elements in the collection must have the same routeID value. MSN Direct will not send any points in the route if a collection contains both route points and single points, or route points with different routeID values.

The routeSequenceNum attribute indicates the sequence of points in a route. The value of the routeSequenceNum attribute in a route must be sequential, starting with 1. MSN Direct will not send any points in the route if the route contains multiple points with same routeSequenceNum or if routeSequenceNum values are not sequential.

The last point element in a route is the endpoint, or the final destination of the route. The route endpoint point element is identified by having a routeEndPointSequenceNum value which is nonzero. For all other points in the route, the routeEndPointSequenceNum element must either not be present or have a value of 0. MSN Direct will not send any points in a route if it does not contain an endpoint element or if the first point is an endpoint. If a route contains multiple endpoints, all points after the first endpoint are ignored.

Please note that not all navigation devices support the grouping of point elements as routes.

Point of Interest Data

Attribute/Element Required Maximum length
<name> Yes 30 characters; extra characters are truncated
<latitude> Yes

12 characters (±XXX.YYYYYYY)
Minimum decimal value = -90
Maximum decimal value = 90
<longitude> Yes

12 characters (±XXX.YYYYYYY)
Minimum decimal value = -180
Maximum decimal value = 180
<address> No 85 characters; extra characters are truncated
<phone> No 20 characters; extra characters are truncated
<description> No 255 characters
<notes> No 255 characters
<hoursOfOperation> No 255 characters
<hoursOfOperation> No 255 characters
<daysOfOperation> No 255 characters
<category> No 255 characters
<subCategory> No 255 characters
<startDateTime> No 255 characters
<endDateTime> No 255 characters
<routeID> No Integer
<routeSequenceNum> No

Integer
Minimum value = 1
Maximum value = 20
The points in a route need to be in sequential order.
<routeEndPointSequenceNum> No Integer; a value different than 0 marks the last point in the route.
<textField1> No 255 characters
<textField2> No 255 characters
<textField3> No 255 characters
<textField4> No 255 characters
<textField5> No 255 characters
<numericField1> No

12 characters (±XXX.YYYYYYY)
<numericField1> No

12 characters (±XXX.YYYYYYY)
<numericField1> No

12 characters (±XXX.YYYYYYY)
<numericField1> No

12 characters (±XXX.YYYYYYY)
<numericField2> No

12 characters (±XXX.YYYYYYY)
<numericField3> No

12 characters (±XXX.YYYYYYY)
<numericField4> No

12 characters (±XXX.YYYYYYY)
<numericField5> No

12 characters (±XXX.YYYYYYY)
 

Point of Interest optional elements

As many of the listed optional elements may be added for each point as desired, as long as the total length of metadata (all point elements excluding lat/long) does not exceed 1024 characters per point and the length of the entire XML does not exceed 25,000 bytes.

Please note that navigation devices may not display all optional elements.

SPECIAL CHARACTERS

The attribute values in the XML collection must use entity escape codes for special characters as listed below:

Ampersand&&amp;
Single Quote'&apos;
Double Quote"&quot;
Greater Than>&gt;
Less Than<&lt;

ERROR HANDLING

If an error occurs or the input is invalid, MSN Direct will show a page with a Go Back link to the return URL (if provided). If there is an action the user can take on the MSN Direct website to resolve the error, a link to that process will be shown. This link will open in a new window.

When the user clicks Go Back, an error code will be posted to the return URL. The possible error codes that may be returned from MSN Direct are:

The Send to GPS XSD schema is available for download here. A violation of these constraints results in an 'Incorrect XML' error (handled as described above).

Input Description
SUCCESS Operation successful. All locations were sent without any failure.
USER_NOT_SUBSCRIBED No subscription exists in the MSN Direct system which is associated with the Windows Live ID.
SUBSCRIPTION_EXPIRED The MSN Direct subscription associated associated with the current Windows Live ID expired.
NO_SUPPORTED_DEVICES None of the devices associated to the MSN Direct account corresponding to this Windows Live ID support the Send to GPS service.
NOT_ALL_DEVICES_SUPPORTED At least one device associated with the MSN Direct account corresponding to this Windows Live ID does not support the Send to GPS service. Locations were still sent to the devices that do support the service.
MESSAGE_QUOTA_EXCEEDED The user has reached the quota of 20 locations per day per Windows Live ID.
INCORRECT_XML The XML data received is not valid, or does not confirm to the XSD schema. None of the locations were delivered.
ONE_OR_MORE_POIS_UNDELIVERABLE At least one location was not delivered, due to a required field being empty or POI metadata exceeding 1024 characters.
FAILURE The operation failed for a reason other than those listed above.
 

EXAMPLE

        
            <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
            <html xmlns="http://www.w3.org/1999/xhtml">
                <head>
                <title>MSN Direct Send to GPS Example</title>
                </head>
                <body>
                <form method="post" action="http://www.msndirect.com/Send/POI.aspx" >
                    <textarea name="collection" id="dataString" rows="10" cols="80">
                    <collections>
                       <collection name='Seattle Pizza Places'>
                           <point name='Unconventional Pizza'>
                               <address>725 Pike St, Seattle, WA</address>
                                    <phone>(206) 625-0102</phone>
                                    <latitude>47.61172</latitude>
                                    <longitude>-122.33310</longitude>
                                    <notes>pizza at seattle, wa</notes>
                               </point>
                               <point name='Unconventional Pizza'>
                               <address>725 Pike St, Seattle, WA</address>
                                    <phone>(206) 625-0102</phone>
                                    <latitude>47.23472</latitude>
                                    <longitude>-122.21210</longitude>
                                    <notes>pizza at seattle, wa</notes>
                               </point>
                           </collection>
                       </collections>
                   </textarea>
                   <br />
            <!-- optional return url -->
                   <input name="returnURL" value="http://localhost/yourReturnUrl/">
                   <br />
                   <input type="submit" value="Send Points Of Interest to Your MSN Direct Device">
                   </form>
               </body>
            </html>