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.
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 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:
bibo
- The Bibliographic Ontologyblt
- British Library Termsdc
- Dublin Core Metadata Initiativedcterms
- Dublin Core Termsecrm
- Erlangen CRMdbp-ont
- DBPedia Ontologydwc
- Darwin Core Ontologygeo-ont
- Geonames Ontologygeo-pos
- Geopos Ontologyrda-carrier
- RDA Carrierrda-content
- RDA Contentrda-media
- RDA Mediardf
- Resource Description Frameworkrdfs
- RDF Schema Vocabularytc
- TDWG Biodiversity Information Standardstn
- TDWG Biodiversity Information Standardstrank
- TDWG Biodiversity Information Standardstsp
- TDWG Biodiversity Information StandardsAuckland 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:
am
- Auckland Museum Base Ontology http://collections.aucklandmuseum.com/ontology/core/
am-geopos
- Auckland Museum Geopos Ontology http://collections.aucklandmuseum.com/ontology/geopos/
All of the Auckland Museums’ collections data can be broadly classified under the following categories
Read on for more information about each category.
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:
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:
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:
rdf:type
: ecrm:E21_Person
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.
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:
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:
/swagger
/search
/id
/id/media
/sparql
are available on the API.
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:
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 |
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
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,
/search
endpoint is used to search for informationcollectionsonline
is the name of the search index we want to perform the search over_search
is the operation we want to perform on the search indexq
query parameterThe 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 thesize
parameter is set to10
by default. API consumers are expected to use pagination to page through the complete result set.
For example, adding the query parameterssize=5&from=10
returns document 11 to 15 from the search results.
Each object contains:
type
that specifies the rdf:type
of the associated subject_id
that represents the identifier of the subject, within a given namespace_source
that is the actual indexed document. This contains other objects with information about the subject
like dc_contributor
, dc_date
, place
, references
, classification
etc.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.
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.
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
.
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.
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:
handle
part is made of wood and has type: http://api.aucklandmuseum.com/id/thesauri/material/AAT.11914
blade
part is made of steel and has type: http://api.aucklandmuseum.com/id/thesauri/material/AAT.133751
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 aPOST
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!