Web Publish/Track API
uTrackMe works by sending a regular HTTP or HTTPS request to your webserver. Your location information is included in the request. uTrackMe Client & uTrackMe Viewer expect other peoples location information in plist format in the response.
Request
The request is sent using the POST method and has the format:
The request starts with:
- nr: [integer] Connection sequence number. Starts with 1 and each subsequent request made by uTrackMe nr is incremented with 1. The count is incremented regardless of the connection result.
uTrackMe Client and uTrackMe Beacon add the device identification and GPS lock status:
- id: [string] The iPhone or iPad UDID (unique device identifier)
- nm: [string] The device name. This is the default name used to identify this iPhone or iPad in the map view.
- lk: [integer] 0 = iPhone or iPad has no location lock; 1 = iPhone or iPad has location lock
... followed by zero or more data points containing the location information. A data point is a comma delimited string with the following format:
- d[]: [string array] String array with location information in the format: "<time>,<latitude>,<longitude>,<accuracy>,<speed>,<course>,<altitude>"
... and it contains the following 7 fields:
- time [integer] - The timestamp in seconds since 1970 (GMT)
- latitude [double] - The latitude
- longitude [double] - The longitude
- accuracy [integer] - Horizontal accuracy in meters
- speed [double] - Speed in meters per second. No value if no speed information is available.
- course [double] - Course in degrees. No value if no course information is available.
- altitude [double] - Altitude in meters. No value if no altitude information is available.
For example POST data of a uTrackMe Viewer request:
For example POST data of a uTrackMe Beacon or Client request when there is no GPS lock:
For example POST data of a uTrackMe Beacon or Client request when there is GPS lock:
If "send entire track" is off uTrackMe sends the last known location but only if it changed since the last successful publish. If it is set to on uTrackMe sends all new data points from the track log since the last successful publish.
Response
The response from the server is in plain text. It must start with the string "OK" and is followed by an array with the location information of all devices in plist format (or XML). String values must be enclosed in quotes. (uTrackMe Beacon ignores the device data; to save bandwidth an empty array can be returned if the User Agent of the request is utmBeacon).
Each device array entry contains the following keys:
- id: [string] - Unique identifier for the device.
- nm: [string] - String used to identify this device in the map view
- tm: [integer] - Time last seen by the server in seconds since 1970 (GMT)
- lk: [integer] - 0 = device has no GPS lock; 1 = device has GPS lock
- ll: [integer] - The last time this device had a GPS lock in seconds since 1970 (GMT)
- st: [string] - (Optional) a server specified string that is shown in uTrackMe under its coordinates. This can be used to convey some sort of status about the device.
- img: [string] - (Optional) url to an png that should be used by uTrackMe as the device icon instead of the default dots. The center of the image marks the spot.
... and the last known location if available:
- d: [string] Location information in the format: "<time>,<latitude>,<longitude>,<accuracy>,<speed>,<course>,<altitude>"
The server can also send a message to the user by adding an array entry with the key "msg":
- msg: [string] - Message shown to the user
For example:
OK
(
{
id = "8000-0017F23404D9";
nm = "Bob";
lk = 1;
ll = 1245241092;
tm = 1245241092;
d = "1245241092,37.361689,-122.040731,100,8,-1,-1";
},
{
id = "8000-0017F23404D5";
nm = "Dave";
lk = 0;
ll = 1245238453;
tm = 1245240002;
},
{
id = "8000-00144653656";
nm = "Jim";
lk = 1;
ll = 1245241092;
tm = 1245241092;
st = "On route to 23th street";
img = "http://www.mydomain.com/jimsicon.png";
},
{
msg = "Welcome to my tracking service."
}
)