Developer Center
MSN Direct Send to GPS API
This page describes how any
website or application may be enabled to deliver location data through the MSN®
Direct wireless network to a compatible navigation device. For successful 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 inputs:
|
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 MSN Direct Send to GPS API will then handle the following steps:
- Present the user with a welcome message, explaining the feature and providing a link to learn more about compatible devices.
- Windows Live ID authentication is required. Any existing
Windows Live ID ticket will be validated. If valid, redirect
invisibly to next step. If not valid the user will be directed through Windows Live ID
login, then redirected to step 3.
- If the user has a compatible navigation device associated with their account, their service is
active, and they have not reached their daily quota (MSN Direct will only
deliver 20 locations per day for a user identified by a Windows Live ID), show
a coverage map of their Primary Region and confirm that region is where the
device is currently located. The user may accept the Primary Region or pick a different region in which to send the
messages (the messages will be sent in the Primary Region as well).
- 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.
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:
|
Error Code
|
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.
|
|
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.
|
Point of Interest Data
The
data consists of one or more collections.
Each collection contains an optional name attribute (25 characters
maximum) and one or more point elements. Each point contains a name attribute,
and the following child elements are also supported:
|
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
|
|
<daysOfOperation>
|
No
|
255 characters
|
|
<category>
|
No
|
255 characters
|
|
<subCategory>
|
No
|
255 characters
|
|
<startDateTime>
|
No
|
255 characters
|
|
<endDateTime>
|
No
|
255 characters
|
|
<routeID>
|
No
|
Integer
There is no enforced limit on the number of routes in a collection.
|
|
<routeSequenceNum>
|
No
|
Integer
|
|
<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)
Decimal value
|
|
<numericField2>
|
No
|
12 characters (±XXX.YYYYYYY)
Decimal value
|
|
<numericField3>
|
No
|
12 characters (±XXX.YYYYYYY)
Decimal value
|
|
<numericField4>
|
No
|
12 characters (±XXX.YYYYYYY)
Decimal value
|
|
<numericField5>
|
No
|
12 characters (±XXX.YYYYYYY)
Decimal value
|
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 document does not exceed 30,000 bytes.
Please note that navigation device user interfaces may not display of all optional elements.
You can download the Send to GPS XSD schema here. A violation of these constraints results in an 'Incorrect XML' error (handled as described above).
If additional element names are required for your application or if you would
like to learn about the elements displayed by MSN Direct compatible devices, please contact the MSN Direct team at
msndsend@microsoft.com.
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>
|
|
