The REST API endpoint can accept query parameters over HTTP and return data as an JSON-encoded object in the body of the HTTP response. The API also supports JSON-P and XML encodings.
The most recent version of the REST API is version 1.0.
Request an API key
The REST API endpoint is hosted at the following URL
All your URLs should begin with this.
Before you can use the API, you will need an API key. An API key is an alphanumeric string intended for use by you.
You will need to supply this key as a URL parameter, e.g.
(This is just an example, not a valid key.)
Be aware that the examples throughout this document do not include the key.
By default, the API return values are returned as a JSON-encoded object in the body of the HTTP response. The API also supports JSON-P and XML encodings.
Use the format URL parameter to explicitly request a particular format:
?format=json (the default if omitted)
The response object always includes the following members:
- success - a boolean value indicating if the API call has worked.
- result - an object, the return value of the API call. The structure of the value will depend on the particular call.
If the success member is false, the result will be an object containing the following members:
- errorCode - an integer, a unique code for each kind of error the API can generate.
- errorMessage - a string, a description of the error.
errorMessage: “Bad element 'badger' for objects”
Fetching all the items in a set
The URL to fetch all the items in a set is
(Include the trailing slash – it's important.)
will fetch all the collection objects in the database. Note that items are returned in batches.
The response object's result member will be an object with the following
- found - an integer, the total number of items in the set.
- items - an array, the list of items in the batch. Each item is an object whose elements depend on the type of item.
Traversing the set
Set items are returned in batches (of 10 by default). You can control the batch size, and the starting point in the set, using the following URL parameters, both of which are optional:
- offset - an integer, the zero-based index into the set of the first item to be returned. The default is 0 (i.e. start at first item).
- limit - an integer, the maximum number of items to be returned. The default is 10.
(Note the / before the ? - it's important.)
Limiting the item data returned
By default, the API will include all the available elements for each item returned. You may only be interested in certain elements, in which case you can use the elements URL parameter:
- elements - a comma-separated list of elements to be returned for each item
Item in response:
Including elements from related items
Items in one set may be related to items in another set. For example, objects can have a station. When specifying the elements to return, you can pull in data from across such a relationship by using the dot notation.
Item in response:
This mechanism helps you avoid making multiple API requests to gather data from multiple sets. You can use the link element directly in your list of elements (elements=station), in which case the API will return all the elements from the linked item.
By default, objects are sorted by "wholeObjectName". Currently, the API does not support other sort orders.
Querying sets (searching)
You can filter sets by including query parameters in your request URL. The response object and traversal logic is the same as for a plain set request, except of course that you'll only be seeing the matching subset.
Free text search
The URL parameter q will perform a free text search across all the elements in the set and return only matching items.
In most cases, text searches support wildcards using an asterisk, e.g.
For each set there are a range of query elements which let you search into specific data. To use a query element, include it in your request URL with a prefix of "q.".
E.g. to search for the object with unique ID O4586
Some query elements support multiple operators which control how the query is interpreted. For example, the object wholeObjectName query element supports both "exact" searching (for exact matches) and "text" searching (free text and potentially partial matches). The operator is appended to the query
element in your request:
/objects/q.wholeObjectName.exact=Diatomaceous ooze deposit
The full set of operators is as follows.
- text - perform a free text search into the element. For example, "york" would match "new york"
- exact - return only items where the value is found exactly. For example, "york" would match "York" but not "New York"
- range - return only items where the value is within the range specified (as a comma-separated pair). You can also give just a single value, in which case it's treated as a lower bound. To specify only an upper bound, prefix your value with a comma (i.e. supply only the second half of the comma-separated pair).
The default operator for a query element (i.e. if you don't specify one explicitly)
is usually "text".
Fetching an item by unique ID
As well as querying a set to retrieve an item by its ID (using the uniqueID query element as in previous examples), you can use a plain URL to fetch the
IDs are not case sensitive in this usage; however we'd recommend you always use the correct case. As with set requests and queries, you can also use the elements URL parameter to control what item elements are returned.
If no item exists in the database for the given ID, or the ID corresponds to an item that's in a different set, a 404 Not Found response is returned. The body of the response is an HTML page, so don't attempt to parse it. If the ID does exist, the result member of the response object will be the item, returned as an object.
Examples and common recipes
Note: you'll need to append your API key to all of these examples (add &key=yourkey to the end).