Developer Center

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:

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

Collection of Point Elements

The XML data consists of one or more collections of locations. Each collection element contains an optional name attribute (maximum 25 characters) and one or more point elements (locations).

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

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.

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).

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>