GPS Data Web Service API

Conventions

Additional Type Hinting

The data objects hold additional clues about the nature of their contents, expressed in the object's property names.

• Links to other resources are named url, or end in _url. This indicates a (relative) URL to another resource.
• UNIX timestamps are stored in properties named ts or ending in _ts.
• A property representing the time of day, and formatted as hh:mm:ss, end in _t.
• A property representing a date only, formatted as YYYY-MM-DD, ends in _dt.
• A property representing a set of days in the week ends in _wd. This is an integer resulting from adding, for each day in the set, two raised to the power of weekday number, where Sunday=1, Monday=2, Tuesday=3, and so on. Note that therefore this number can be any even number from 0-254.

Factory URLs

When creating new data objects, a POST request is performed at a so-called "factory URL". Usually, a URL at which you can retrieve a list of data objects is also a factory URL.

As an example, you can get a list of all your zones by making a GET request on gateway.zones_url. Making a POST request (containing, in this case, a data object that looks like a zone) will create a new zone data object.

Persistent URL Parameters

All URL parameters that begin with an underscore are persisted across links that are returned from the web service. If you add any of them to a request once, the value will be in any URLs that you follow. This allows a small bit of state to be carried across requests.

_format

Our service can return XML, JSON or HTML at the same URL, deciding the content type based on the standard HTTP Accept header. If, however, it is simpler for your programming model to tack on a URL parameter rather than using HTTP headers, this parameter has the highest priority in deciding the content type to return.

_tz

This string indicates which Time Zone should be used when making requests that involve dividing data by day. Because your data is stored in a format independent of time zones, it can be viewed according to any of the supported time zones dynamically.

_token

The authentication string generated by our server that you can use to authenticate requests. This is the only parameter that is not persisted if your client sends the "token" cookie. (see Authenticating your HTTP requests)

Data Object Naming

The data object descriptions use the following convention:

non_editable

This is a non-editable property of an object. You can read to your heart's content, but it will be ignored completely if you try to update it.

editable

This is an editable property of the object. You can update it when you GET the resource, make changes to the property (see Data Formats), and PUT the changed resource back to the URL you got it from.

related_url

This is a link that you can follow to some other data object. You know this because of type hinting. By the way: all "url" or "*_url" parameters are relative to the URL at which you retrieved this data object. So, you will have to resolve the URL.

list_of_data

This is an array of objects, and each object has the format described below:

item_url

A link to another resource, often the URL to access this "child object" directly (e.g., not as a member of the list).

some_prop

A property of this object, non-editable

other_prop

An editable property of the object. To make a change, you'll have to call HTTP PUT at the URL of this object (possibly item_url).

note

Sometimes not all information about an object is included when it is given as a list embedded in another object. In that case, there may be more information about the object when you GET it at its address (item_url).