Auckland Museum API

Version: 2

This document demonstrates use of the Auckland Museum API with the help of an example.

Note:
We have removed the need for an API key to access this version of the API, making the API LOD (Linked Open Data) compatible. If you have previously registered and obtained a key, that key is now obsolete.


Table of Contents


Linked Open Data

Auckland Museum has embraced the Linked Open Data concept in order to facilitate collaboration and sharing of their rich collections data.
Linked data describes a method of publishing structured data so that it can be interlinked and become more useful through semantic queries. It builds upon standard Web technologies such as HTTP, RDF and URIs, but rather than using them to serve web pages for human readers, it extends them to share information in a way that can be read automatically by computers. This enables data from different sources to be connected and queried.

We recommend you watch the video Linked Open Data - What is it? to understand what Linked Open data is about.


Ontologies

Ontologies are a core concept of Linked Open Data. Several ontologies are used to represent data from the various collections within Auckland Museum. Here are some of the ontologies that are currently in use:

Auckland Museum has developed its own ontologies to represent data that either cannot be represented by an existing ontology or to temporarily represent data in a simple manner until it is mapped to one of the standard ontologies. These are:


Data Overview

All of the Auckland Museums’ collections data can be broadly classified under the following categories

Read on for more information about each category.

Natural Sciences

rdf:type: ecrm:E20_Biological_Object

Auckland Museum protects and cares for approximately 1.5 million natural science specimens in collections that have been built over 150 years. The focus of the collections is northern New Zealand, but they also contain material from the rest of the country, the South West Pacific and other parts of the world.

This API provides data from the following natural sciences collections:

Human History

rdf:type: ecrm:E22_Man-Made_Object

Auckland Museum is kaitiaki for nearly 200,000 human history objects, in collections that have been developed and cared for over 150 years.

This API provides data from the following human history collections:

Documentary Heritage

rdf:type: ecrm:E84_Information_Carrier

The Documentary Heritage collection is an authoritative source of images depicting New Zealand and Pacific culture and history, including photographs, prints, drawings, posters and paintings. The photograph collection in particular is a major New Zealand collection.

This API provides data from the following documentary heritage collections:

People

rdf:type: ecrm:E21_Person

Cenotaph

rdf:type: am:MilitaryPerson

The Online Cenotaph is a biographical database that pulls together information relating to individual service people from a huge range of sources such as embarkation, military service and other government records, newspapers and families. It will eventually provide a page for every person who has served our country during times of international and national conflict.

Associated collections

To support the above collections Auckland Museum uses a system of controlled terms to categories and index objects in the collection. These terms include details of geographic locations, media and materials, and field collection sites.

This API provides data from the following associated collections:


Using the API

The API is available at http://api.aucklandmuseum.com.
A more technical Swagger specification of the API is available at http://api.aucklandmuseum.com/swagger

The following resources:

are available on the API.

API Workflow

The first step for most users of the API will be to search for interesting subjects via the /search endpoint.
The search results contain quite a lot of useful information that provides a general idea of what every subject is.

Once you have a bunch of subjects you’re interesting in, use the /id endpoint to get more details about each one of those subjects.

If a subject has one or more visual representations (for example, there is an image associated with the subject), the response from the /id endpoint will contain a predicate ecrm:P138_has_representation that points to the URI’s of those representations.

You can use the /id endpoint again to find more details about each representation (details like rdf:type of the representation or any copyright associated with it).

The /id/media endpoint is capable of returning visual media representations, provided you supply the media URI and an optional rendering query parameter.

These steps can be easily summarised as follows:

Created with Raphaël 2.1.2UserUserAPIAPIsearch query on /searchreturn search resultsNeed more details?get subject information using /idreturn subject informationNeed media?get media related to subject using /id/mediareturn media

Rate Limiting

The following rate limits apply to the API

Resource Requests per second Requests per day
/search, /id 10 1000
/id/media 10 1000
/sparql 5 100

SPARQL

The Auckland Museum API provides a SPARQL endpoint (/sparql) that allows users to execute SPARQL queries against the museums data.

Note
In order to prevent abuse, the maximum query execution time for any SPARQL query made against this endpoint is 10 seconds


Example: Sir Edmund Hillary’s Ice Axe

This example shows usage of the API to get information about and related to Sir Edmund Hillary’s ice axe.

Let’s start with a simple search.
The Auckland Museum API provides a /search endpoint which can be used to perform sophisticated search queries to find various types of information.

Note:
The /search endpoint is backed by a Elastic search server and mirrors the Elastic search API documented here

We perform a very simple keyword search for the keywords edmund hillary ice axe as follows:

curl 'http://api.aucklandmuseum.com/search/collectionsonline/_search?q=ice%20axe%20edmund%20hillary'

Here,

The response is some application/json that contains the search results.

Let’s see what the results say:
"total": 1806 indicates that there are 1806 indexed documents that match the search criteria. These are returned as objects under hits.

Note:
Although there are 1806 documents that match the search criteria, the top 10 most relevant matches are actually returned. This is because the size parameter is set to 10 by default. API consumers are expected to use pagination to page through the complete result set.
For example, adding the query parameters size=5&from=10 returns document 11 to 15 from the search results.

Each object contains:

The _id of the most relevant document is http://api.aucklandmuseum.com/id/humanhistory/object/671988. This is also the URI of the subject and is fully resolvable.

Id

The /id endpoint is used to get details about a subject within the Auckland Museum Collections.

Simply use the URI of the subject you’re interested in, like so:
curl "http://api.aucklandmuseum.com/id/humanhistory/object/671988"

The API can return a response in the following formats, depending on the Accept header set in the request:

Format Accept Header
HTML (default - browser friendly) text/html
JSON application/json
JSON-LD application/ld+json

Consider the following piece of JSON in our response, if we set the Accept header to application/json :

"ecrm:P138_has_representation": [
{
  "type": "uri",
  "value": "http://api.aucklandmuseum.com/id/media/v/232518"
},
{
  "type": "uri",
  "value": "http://api.aucklandmuseum.com/id/media/v/9760"
},
{
  "type": "uri",
  "value": "http://api.aucklandmuseum.com/id/media/v/9759"
}

This implies that our subject has 3 different representations (or media) associated with it.

What more information can we find about the media? Just use the /id endpoint again:
curl http://api.aucklandmuseum.com/id/media/v/232518 -H 'Accept: application/json'

The response indicates that http://api.aucklandmuseum.com/id/media/v/232518 is actually of rdf:type ecrm:E38_Image. There is a copyright associated with the image via ecrm:P75_possesses.

So we know it’s supposed to be an image and we know it has certain copyright information associated with it, but where is the image itself?

Let’s use the /id/media endpoint to find out.

Media

The /id/media endpoint is used to obtain media (images and pdf documents) that’s associated with subjects.

In our example, we’re looking for the image whose URI is http://api.aucklandmuseum.com/id/media/v/232518.
This URI is fully resolvable and by default, will return the original image.

The API provides the same image in multiple sizes, depending on the query parameter rendering.

The following table summarises the renderings available for the various media rdf:type’s.

rdf:type rendering note
ecrm:E38_Image original.jpg The original jpeg
ecrm:E38_Image thumbnail.jpg jpeg image with a fixed width of 70px
ecrm:E38_Image preview.jpg jpeg image with a fixed height of 100px
ecrm:E38_Image standard.jpg jpeg image with a fixed with of 440px and a fixed height of 440px
ecrm:E31_Document original.pdf The original PDF
ecrm:E31_Document original.jpg JPEG of the first page of the PDF

Getting the image with the URI and a rendering is simple. Just use the URI along with an appropriate value for the query parameter rendering and an appropriate Accept header:

curl "http://api.aucklandmuseum.com/id/media/v/232518?rendering=thumbnail.jpg" -H "Accept: image/*"

The response is the thumbnail version of the original image with content type image/jpeg.


Other Information

Recall that there were a total of 1806 search results for our original keyword search. We just explored the most relevant search result but there are so many others that might be of interest.


Example: Items made of wood

Let’s see the response from the /id endpoint for the subject of our earlier example:
Sir Edmund Hillary’s ice axe - http://api.aucklandmuseum.com/id/humanhistory/object/671988

Specifically, lets look at ecrm:P45_consists_of within the response.

The ecrm ontology contains the following scope note for this predicate:

Scope note: This property identifies the instances of E57 Materials of which an instance of E18 Physical Thing is composed. All physical things consist of physical materials. P45 consists of (is incorporated in) allows the different Materials to be recorded. P45 consists of (is incorporated in) refers here to observed Material as opposed to the consumed raw material. A Material, such as a theoretical alloy, may not have any physical instances. silver cup 232 (E22) consists of silver (E57)

From the values of ecrm:P45_consists_of for our ice axe, we see that:

Let’s say, we want to find out all other subjects that are made of the same material as the handle, i.e. http://api.aucklandmuseum.com/id/thesauri/material/AAT.11914

The way we got to our node of interest is

http://api.aucklandmuseum.com/id/humanhistory/object/671988 -> ecrm:P45_consists_of -> http://api.aucklandmuseum.com/id/humanhistory/object/671988/material/1

http://api.aucklandmuseum.com/id/humanhistory/object/671988/material/1 -> ecrm:P2_has_type -> http://api.aucklandmuseum.com/id/thesauri/material/AAT.11914

So we need to find all other subjects that reach the http://api.aucklandmuseum.com/id/thesauri/material/AAT.11914 node in the same way.

The following SPARQL query would be perfect for this.

PREFIX ecrm:<http://erlangen-crm.org/current/>
SELECT ?subject WHERE {
  ?subject ecrm:P45_consists_of/ecrm:P2_has_type <http://api.aucklandmuseum.com/id/thesauri/material/AAT.11914>
}
LIMIT 10

The query can be executed against the /sparql endpoint, like so:

curl -X POST -H "Accept: application/sparql-results+json" -H "Content-Type: application/x-www-form-urlencoded" -d 'query=PREFIX ecrm:<http://erlangen-crm.org/current/>     SELECT ?subject WHERE {       ?subject ecrm:P45_consists_of/ecrm:P2_has_type <http://api.aucklandmuseum.com/id/thesauri/material/AAT.11914>     }     LIMIT 10' "http://api.aucklandmuseum.com/sparql"

Note:
The query is sent as a POST and is URL Encoded

The results are interesting. There are indeed 10 (perhaps more) subjects that satisfy the query criteria. How many subjects are there in total? The following count query should answer that:

PREFIX ecrm:<http://erlangen-crm.org/current/>
SELECT (count(?subject) as ?count) WHERE {
  ?subject ecrm:P45_consists_of/ecrm:P2_has_type <http://api.aucklandmuseum.com/id/thesauri/material/AAT.11914>
}

So we just found all these other subject’s that are at least in part, made of the same material as our original ice axe!