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

    https://www.hmschallenger.net/rest/v1

All your URLs should begin with this.

API Key


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.

    ?key=idhjf73jd9437dklf

(This is just an example, not a valid key.)

Be aware that the examples throughout this document do not include the key.

API response


Format


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)
    ?format=jsonp&callback=yourFunction

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.

E.g.
Request:
    /objects/O4586
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.


E.g.
Request:
    /objects/O4586?elements=badger
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


    /{set}/


(Include the trailing slash – it's important.)


For example


    https://www.hmschallenger.net/rest/v1/objects/


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.


E.g.
    /objects/?offset=100&limit=50
(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

E.g.
Request:
    /objects/?elements=uniqueID,wholeObjectName
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.


E.g.
Request:
    /objects/?elements=uniqueID,station.station
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.


Sorting

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:
    /objects/?q=fruit


In most cases, text searches support wildcards using an asterisk, e.g.
    /objects/?q=fruit*


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
    /objects/?q.uniqueID=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
item:
    /{set}/{id}


For example
    https://www.hmschallenger.net//rest/v1/objects/O4586


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

https://www.hmschallenger.net/rest/v1/objects/O4337

Returning XML rather than JSON

https://www.hmschallenger.net/rest/v1/objects/O4337?format=xml

Returning JSON-P rather than JSON

https://www.hmschallenger.net/rest/v1/objects/O4337?format=jsonp&callback=processObject

Returning specific object information rather than everything

https://www.hmschallenger.net/rest/v1/objects/O4337?elements=wholeObjectName,imageURL

Fetching all the objects (first batch of 10 objects)

https://www.hmschallenger.net/rest/v1/objects/

Fetching the next batch of 10 objects

https://www.hmschallenger.net/rest/v1/objects/?offset=10

Fetching all the objects (first batch of 50 objects)

https://www.hmschallenger.net/rest/v1/objects/?limit=50

Fetching the next batch of 50 objects

https://www.hmschallenger.net/rest/v1/objects/?limit=50&offset=50

Find objects containing the word "crab"

https://www.hmschallenger.net/rest/v1/objects/?q=crab

Find objects containing the word "crab" in the name

https://www.hmschallenger.net/rest/v1/objects/?q.wholeObjectName=crab

Find objects created in the 20th century

https://www.hmschallenger.net/rest/v1/objects/?q.fieldCollectionDate.range=1900,1999

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

https://www.hmschallenger.net/rest/v1/objects/?elements=uniqueID,wholeObjectName,collectionPlaces.name