The HMS Challenger Collection is available for retrieval by service providers via a URL-based "REST"-like API.

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

To request an API key please use the contact form. Mark the form "API Key Request" and it may take five working days to process your request.

API basics

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.

API response


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)

Return values

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.

Return object:
        success: true,
        result: {
            uniqueID: “O4586”,
            wholeObjectName: “Starfish”,

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.

Return object:
        success: false,
        result: {
            errorCode: 102,
            errorMessage: “Bad element 'badger' for objects”

Fetching data

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.)

For example

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:
        uniqueID: “O4586”,
        title: "Starfish"

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:
        uniqueID: “O4586”,
        station: {
            station: “193”

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.

For example:

In most cases, text searches support wildcards using an asterisk, e.g.

Element-specific search

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

For example

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).

Fetching an object by ID as a JSON object

Returning XML rather than JSON

Returning JSON-P rather than JSON

Returning specific object information rather than everything,imageURL

Fetching all the objects (first batch of 10 objects)

Fetching the next batch of 10 objects

Fetching all the objects (first batch of 50 objects)

Fetching the next batch of 50 objects

Find objects containing the word "crab"

Find objects containing the word "crab" in the name

Find objects created in the 20th century,1999

Include the collection place name from the places authority in object search results,wholeObjectName,