(1) API Basics
For the past 160 years, our Curators, Collection Managers, and volunteers have been creating descriptions, classifications and taxonomies to catalogue and map object information within our collections. Over this time, we have amassed a huge amount of data, and metadata (data about data) regarding the 4 million + objects in our care.
Digitisation projects, access initiatives, and rigorous data management have made Collections Online what it is today, and the ongoing work of our staff has resulted in an extensive digital collection available online. Our mission is to make this data accessible, useable and useful for researchers and members of the public who may have an interest in it.
Perhaps you are undertaking a geneological project that requires a broad search query across all our collections, or maybe you want to utilise artworks in our pictorial collection for a machine learning project? We encourage the use of the API web services for creative, personal and academic pursuits through application of our data.
Our data can be directly accessed in a JSON format through the Tāmaki Paenga Hira API, a RESTful/HTTPS-style API service.
By accessing our data through the Tāmaki Paenga Hira API, you can make requests for structured data from our collections to use in your personal research, data experiments, projects, or artworks.
Before you get started on your project, you'll need to read our API Terms and Conditions. This is where you will find important information about your access rights, cultural permissions, and what you can and cannot do with our data.
Keep in touch: we'd love to hear from you how you're using our data, or if you have any questions about our terms of use. Contact us by sending an email, or tag us on social media if you are building something public.
An Application Programming Interface is essentially a set of instructions that tells two pieces of software how to communicate with one other — allowing you to build an app or integrate your website into another, for example.
If you have used Collections Online on our website, then you've already seen the API in action. When you put in keywords and hit enter, your browser makes a request to the API, which delivers the data as search results. With the API, you can bypass the website and send requests directly to the database that runs the website — this is particularly useful if you're a researcher or app developer.
Our API provides responses using the JSON data standard. In order to view the data that the API sends back, you'll need some way to look at JSON-formatted data. Most modern browsers — i.e., Chrome, Safari, and Firefox — have extensions that can do this for you.
In order to use our API, you will need a basic understanding of how HTTP, HyperText Transfer Protocol, requests work. These requests are made from one point to another over a network, and return data in a JSON (JavaScript Object Notation) format, using parameters.
Header parameters are included in the request header, and typically relate to authorisation. As our API is for open use of the public, you do not need to worry about this. Path parameters determine the location of the endpoint, and this will be relevant when determining whether Objects opacobjects or Persons opacpersons will be the endpoint of your choice. Typically path parameters are followed by /.
Finally, path parameters can be followed by query string parameters. Query String parameters are what will specify how results are filtered and displayed in your JSON output. These parameters typically come after ? In the HTTP request.
To begin with, the base url for the API is https://collection-api.aucklandmuseum.com/api/v3/
The most basic form of search API is the empty search, which doesn’t specify any query but simply returns all records. Currently our API has works off two separate datasets: Objects and People. Include the preferred dataset as a path parameter alongside the basic query string ?query= to conduct an empty search query.
With this in mind, we have two separate empty searches:
| dataset | path parameter |
|---|---|
| For Objects | https://collection-api.aucklandmuseum.com/api/v3/opacobjects/?query= |
| For People | https://collection-api.aucklandmuseum.com/api/v3/opacpersons/?query= |
If we wished to specify which department we wanted to search within a collection area, we would use the query search perimeter: view=label&facet=department%3A{department name}.
We could also specify which Collection area we want, as an additional parameter attached to our query string: view=label&facet=collection_area%3A{collection area name} adding a collection area facet to search over within the objects dataset.
Learn more about potential departments and collection areas to include in your search queries in our data structure section, here.
To get started, let's have a look at a vase in our applied arts collection:
https://collection-api.aucklandmuseum.com/api/v3/opacobjects/7481
Here you can see the same object on Collections Online, our online discovery platform that also utilises the Tāmaki Paenga Hira API: https://www.aucklandmuseum.com/collection/object/am_humanhistory-object-7481
Notice the numbers at the end of the URL? 7481 is the ID of the object you're looking at, a unique number that we use to keep track of all of the collection records. Try changing it to other IDs you found from the Tāmaki Paenga Hira API to see these objects’ structured data.
In the json output for our vase, you will notice particular fields referenced with a value, such as media/materials: in this case, our vase is made of glass (or more specifically, hot blown glass).
{
"identifier": "media_materials",
"opacObjectFields": [
{
"value": "glass/inorganic material/AAT Materials"
}
]
},
{
"identifier": "media_materials_description",
"opacObjectFields": [
{
"value": "hot blown glass"
}
]
}Read more about fields usage for specific departments here.
If you wished to search our entire collection for vases, you could search using this query string parameter: ?query={keyword}
eg; https://collection-api.aucklandmuseum.com/api/v3/opacobjects?query=vase
If you wished to search our entire collection for items made our of glass you could include a query string parameter specifying ?query=glass&field=media_materials or ?query=hot%20blown%20glass&field=media_materials_description (notice that the spaces in "hot blown glass" are replaced with %20 in our syntax)
In the same way you can search for an object through Collections Online on our website, you can do this on our API too by adding a query string search /search/?query= onto the base url for our API https://collection-api.aucklandmuseum.com/api/v3/
You might also want to limit your search to a particular API field, such as the title: /search/?query=vase&field=title
Producing the json output for objects with 'vase' in their title, as evidenced below: https://collection-api.aucklandmuseum.com/api/v3/opacobjects?query=vase&field=title
{
"opacObjects": [
{
"opacObjectId": "15453"
},
{
"opacObjectId": "10657"
},
{
"opacObjectId": "9881"
},
{
"opacObjectId": "10654"
},
{
"opacObjectId": "3483"
},
{
"opacObjectId": "16280"
},
{
"opacObjectId": "89108"
},
{
"opacObjectId": "15590"
},
{
"opacObjectId": "91042"
},
{
"opacObjectId": "11928"
},
{
"opacObjectId": "2084"
},
{
"opacObjectId": "12012"
}
],
"totalObjects": 2118
}