As of Monday, May 6th, the following elements changes will go into effect:
Battery State will be sent along with most message types, not every message will have it, but most of them will. It has two states. Examples:
<batteryState>GOOD</batteryState>
<batteryState>LOW</batteryState>
ModelID will also appear in the XML. Values:
<modelId>SPOT3</modelId>
<modelId>SPOT2</modelId>
<modelId>SPOT-2-IS</modelId>
<modelId>SPOT</modelId>
<modelId>SPOTCONNECT</modelId>
<modelId>SPOTDC</modelId>
<modelId>HUG</modelId>
Three new message types as well.
<messageType>NEWMOVEMENT</messageType>
<messageType>UNLIMITED-TRACK</messageType>
<messageType>EXTREME-TRACK</messageType>
The SPOT shared page is built upon an XML data stream that is enabled when a new shared page is created. The glId in the following url is the FEED_ID you will need below. (Please note the glId/FEED_ID in the examples below is non-functional, it is for example purposes only)
The default content type returned by the API is JSON. Some browsers apparently display it as XML even though the API returns it as JSON. If you want to ensure your content type, append the appropriate switch (.xml or .json).
-- The API will only return data from the point where the feed was created, up to a maximum of 7 days. --
Available API usage calls:
Default content-type returned is JSON, adding .xml before any further query string parameters will return XML
https://api.findmespot.com/spot-main-web/consumer/rest-api/2.0/public/feed/FEED_ID_HERE/message.xml
Last 50 Messages in XML format:
https://api.findmespot.com/spot-main-web/consumer/rest-api/2.0/public/feed/FEED_ID_HERE/message.xml
Paging in increments of 50 in XML format (Note: No ?start= results in newest 50 by default):
https://api.findmespot.com/spot-main-web/consumer/rest-api/2.0/public/feed/FEED_ID_HERE/message.xml?start=51
https://api.findmespot.com/spot-main-web/consumer/rest-api/2.0/public/feed/FEED_ID_HERE/message.xml?start=101
Last 50 Messages in JSON format (both are the same request):
The following message types are available via the current feed:
- OK
- TRACK
- HELP
- HELP-CANCEL
- CUSTOM
- POI
The XML returned via an api.findmespot.com feed will look like this:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<feedMessageResponse>
<count>10</count>
<feed>
<id>03XHH0sPyTiYUsYD2TVJ4q7CzEH89HBhG</id>
<name>OneAtATime</name>
<description>OneAtATime</description>
<status>ACTIVE</status>
<usage>0</usage>
<daysRange>7</daysRange>
<detailedMessageShown>true</detailedMessageShown>
</feed>
<totalCount>10</totalCount>
<activityCount>0</activityCount>
<messages>
<message clientUnixTime="0">
<id>4937065</id>
<messengerId>0-8356068</messengerId>
<messengerName>Spot2</messengerName>
<unixTime>1364909292</unixTime>
<messageType>HELP-CANCEL</messageType>
<latitude>-99999.0</latitude>
<longitude>-99999.0</longitude>
<modelId>SPOT2</modelId>
<showCustomMsg>Y</showCustomMsg>
<dateTime>2013-04-02T06:28:12-0700</dateTime>
<hidden>0</hidden>
<messageContent>The help message has been cancelled</messageContent>
</message>
<message clientUnixTime="0">
<id>4937064</id>
<messengerId>0-8356068</messengerId>
<messengerName>Spot2</messengerName>
<unixTime>1364909283</unixTime>
<messageType>HELP</messageType>
<latitude>45.42249</latitude>
<longitude>-111.68832</longitude>
<modelId>SPOT2</modelId>
<showCustomMsg>Y</showCustomMsg>
<dateTime>2013-04-02T06:28:03-0700</dateTime>
<hidden>0</hidden>
<messageContent>This is the default HELP message. Please update.</messageContent>
</message>
<message clientUnixTime="0">
<id>4937060</id>
<messengerId>0-8356068</messengerId>
<messengerName>Spot2</messengerName>
<unixTime>1364908774</unixTime>
<messageType>CUSTOM</messageType>
<latitude>45.42249</latitude>
<longitude>-111.68832</longitude>
<modelId>SPOT2</modelId>
<showCustomMsg>Y</showCustomMsg>
<dateTime>2013-04-02T06:19:34-0700</dateTime>
<hidden>0</hidden>
<messageContent>This is a custom message</messageContent>
</message>
<message clientUnixTime="0">
<id>4937059</id>
<messengerId>0-8356068</messengerId>
<messengerName>Spot2</messengerName>
<unixTime>1364908765</unixTime>
<messageType>OK</messageType>
<latitude>45.42249</latitude>
<longitude>-111.68832</longitude>
<modelId>SPOT2</modelId>
<showCustomMsg>Y</showCustomMsg>
<dateTime>2013-04-02T06:19:25-0700</dateTime>
<hidden>0</hidden>
<messageContent>This is the default SPOT Check-in/OK message. Please update.</messageContent>
</message>
<message clientUnixTime="0">
<id>4937057</id>
<messengerId>0-8356068</messengerId>
<messengerName>Spot2</messengerName>
<unixTime>1364908512</unixTime>
<messageType>TRACK</messageType>
<latitude>45.42249</latitude>
<longitude>-111.68832</longitude>
<modelId>SPOT2</modelId>
<showCustomMsg>Y</showCustomMsg>
<dateTime>2013-04-02T06:15:12-0700</dateTime>
<hidden>0</hidden>
</message>
</messages>
</feedMessageResponse>
</response>
The XML document will contain 0 or more messages. Only the messengers and message types enabled by the customer will be available in this data stream. Also note that the XML data is cached by our servers. In addition, viewing limits are imposed on all shared page links and abuse of this feature may cause the viewing limits to come into effect. This web service has request limits - Currently it restricts 500 requests,per FeedID in a 15 minute interval. Please contact SPOT API Support if your service plans to make more than 500 requests in a 15 minute interval or please plan to cache the data in your side using a client side proxy.
Appendix A - User side proxy
If the User is using the Shared page XML feed to show the locations in their own website then they can use a caching proxy to significantly reduce the number of requests the SPOT shared service receives. The basic algorithm would be to save the XML feed retrieved from the SPOT service in the local file system. Serve the saved XML data if the time of request falls within 5 minutes of the time of saving the feed. The following sample PHP program can do this:
<?php
// Set this to your link Id
$linkId = "FEED_ID_HERE";
// Set this to a directory that has write permissions
// for this script
$cacheDir = "./cache/";
$cachetime = 5 * 60; // 5 minutes
// Do not change anything below this line
// unless you are absolutely sure
$feedUrl="https://api.findmespot.com/spot-main-web/consumer/rest-api/2.0/public/feed/FEED_ID_HERE/message.xml";
$cachefile = $cacheDir .$linkId.".xml";
header("Content-type: text/xml");
// Send from the cache if $cachetime is not exceeded
if (file_exists($cachefile) && (time() - $cachetime
< filemtime($cachefile)))
{
include($cachefile);
echo "<!-- Cached ".date("jS F Y H:i", filemtime($cachefile))." -->\n";
exit;
}
$contents = file_get_contents($feedUrl . $linkId);
// show the contents of the XML file
echo $contents;
// write it to the cache
$fp = fopen($cachefile, "w");
fwrite($fp, $contents);
fclose($fp);
?>