Skip to content

Getting started

Jump to bottom
Fiona Wood edited this page Jun 12, 2018 · 59 revisions

Collection API

The National Museum of Australia's Collection API gives access to over 80,000 object records in the Museum's collection including 20,000 images that are either in the Public Domain or available for use under a Creative Commons licence. Most of these objects can also be viewed on Collection Explorer.

Beta release

This API is in active development for a public release in 2018. We'd love you to try it out, but please note that it may change without notice during the current Beta release (see Known Issues below).

Warning

The API contains names and images of deceased Aboriginal and Torres Strait Islander people. Some older records contain images and terms that are now considered inappropriate and do not reflect the views of the National Museum.

Copyright

The Museum does not own copyright for all digital images or media in the API. Each record contains details of the media rights or media access licence available:

Code Rights or licence Media usage
Public Domain Public Domain Media may be used for any purpose (including commercially), no attribution is necessary
CC BY-SA 4.0 Creative Commons commercial use Media may be used for any purpose (including commercially), with attribution and any changes re-distributed under the same licence
CC BY-NC-SA 4.0 Creative Commons non-commercial use Media may only be used non-commercially, with attribution and any changes re-distributed under the same licence
All Rights Reserved All Rights Reserved Media may not be used without permission of the copyright holder

If no media rights or licence is specified, then the copyright is All Rights Reserved and the media may not be used without permission of the copyright holder.

Basic API usage

Collection API explorer

The best way to learn about our Collection API is to play with the Collection API Explorer. It shows you the available search options and builds an API URL for you.

[Collection API Explorer] (http://nma.conaltuohy.com/apiexplorer.html)

Access

You can use the API directly in your application or web browser without authentication:

http://nma.conaltuohy.com/object?title=bark

(If your browser asks you to save a file, you may need to install an extension so you can view the API response directly in your browser, for example JSONView for Chrome | Firefox | Safari.)

Rate limiting

The API is usable without authentication in small to medium applications - up to 1 request per second. Contact us if you need an API key for higher performance.

API endpoints

Museum content
  • /object - the museum catalogue plus images/media
  • /narrative - narratives by Museum staff about featured topics
Details of related entities
  • /party - people and organisations associated with collection items
  • /place - locations associated with collection items
  • /collection - sub-collections within the museum catalogue
  • /media - images and other media associated with collection items

Note: Museum content records (from /object and /narrative) include enough details for the basic display of collection items and their images, creators, names, places, etc. If you need more details you can make extra calls to the other endpoints.

Responses

Data formats

Each API endpoint provides two data formats:

Simple JSON
  • Default data format
  • A simple data structure using fields from common vocabularies: Dublin Core, FOAF, OAI-ORE, and schema.org
  • Use HTTP request header: Accept: application/json
  • For debugging use query parameter: ?format=simple
Linked Art JSON-LD
  • A special version of JSON for Linked Data
  • A rich data structure following the Linked Art profile of the museum-based CIDOC-CRM
  • Use HTTP request header: Accept: application/ld+json
  • For debugging use query parameter: ?format=json-ld

Data object samples

Object

GET http://nma.conaltuohy.com/object/14693

{
  "id": "14693",
  "type": "object",
  "additionalType": "Glass plate negatives",
  "title": "Glass plate negative - Bush scene, Bathurst Island, Northern Territory. The stringy-bark has had its bark removed for the purpose of constructing a canoe, photographed by Herbert Basedow, 1911",
  "collection": {
    "id": "2066",
    "type": "collection",
    "title": "Dr Herbert Basedow collection"
  },
  "identifier": "1985.0060.3696",
  "medium": [
    "Photographic emulsion",
    "Glass"
  ],
  "extent": {
    "type": "Measurement",
    "length": "120",
    "width": "164",
    "unitText": "mm"
  },
  "description": "Reproduced by Basedow in 'Notes on the Natives of Bathurst Island, North Australia', \"Journal of the Royal Anthropological Institute\",  vol. XLIII, 1913, plate XII/1. Caption reads: 'Forest scene on Bathurst Island. From the stringy-barked eucalyptus on the left side of the picture, the bark has been removed for the purpose of making a canoe. Another tree, which has been similarly treated, is seen in the background, near the centre of the picture. In the foreground note a tall specimen of the zamia-palm (Cycas media).'",
  "physicalDescription": "Black and white glass plate negative. Caption: Bush scene. The stringy-bark (Eucalyptus tetradonta) has had its bark removed for the purpose of constructing a canoe, as has the tree in the centre background. Note the zamia (Cycas media) in the foreground.",
  "creator": [
    {
      "id": "81115",
      "type": "Person",
      "title": "Dr Herbert Basedow",
      "roleName": "Photographer",
      "interactionType": "Production"
    }
  ],
  "spatial": [
    {
      "id": "80110",
      "type": "Place",
      "title": "Australia",
      "roleName": "Place designed",
      "interactionType": "Production",
      "location": "-25.2744,133.775"
    }
  ],
  "temporal": [
    {
      "type": "Event",
      "title": "1911",
      "roleName": "Date photographed",
      "interactionType": "Production"
    }
  ],
  "hasVersion": [
    {
      "id": "MA22994856",
      "type": "StillImage",
      "identifier": "http://nma.conaltuohy.com/media/MA22994856#",
      "rights": "https://creativecommons.org/publicdomain/mark/1.0/",
      "rightsTitle": "Public Domain",
      "hasVersion": [
        {
          "type": "StillImage",
          "version": "large image",
          "identifier": "http://collectionsearch.nma.gov.au/nmacs-image-download/piction/dams_data/prodderiv3/Working%20Masters/nma.img-ci20082027-096-wm-vs2_o3.jpg"
        },
        {
          "type": "StillImage",
          "identifier": "http://collectionsearch.nma.gov.au/nmacs-image-download/piction/dams_data/prodderiv2/Working%20Masters/nma.img-ci20082027-096-wm-vs2_o2.jpg"
        },
        {
          "type": "StillImage",
          "version": "preview image",
          "identifier": "http://collectionsearch.nma.gov.au/nmacs-image-download/piction/dams_data/prodderivW/PH2027/Collection/Working%20Masters/nma_22994856.jpg"
        },
        {
          "type": "StillImage",
          "version": "thumbnail image",
          "identifier": "http://collectionsearch.nma.gov.au/nmacs-image-download/piction/dams_data/prodderivT/PH2027/Collection/Working%20Masters/nma_22994856.jpg"
        }
      ]
    },
    {
      "id": "MA22993676",
      "type": "StillImage",
      "identifier": "http://nma.conaltuohy.com/media/MA22993676#",
      "rights": "https://creativecommons.org/publicdomain/mark/1.0/",
      "rightsTitle": "Public Domain",
      "hasVersion": [
        {
          "type": "StillImage",
          "version": "large image",
          "identifier": "http://collectionsearch.nma.gov.au/nmacs-image-download/piction/dams_data/prodderiv3/Working%20Masters/nma.img-ci20082027-096-wm-vs1_o3.jpg"
        },
        {
          "type": "StillImage",
          "identifier": "http://collectionsearch.nma.gov.au/nmacs-image-download/piction/dams_data/prodderiv2/Working%20Masters/nma.img-ci20082027-096-wm-vs1_o2.jpg"
        },
        {
          "type": "StillImage",
          "version": "preview image",
          "identifier": "http://collectionsearch.nma.gov.au/nmacs-image-download/piction/dams_data/prodderivW/PH2027/Collection/Working%20Masters/nma_22993676.jpg"
        },
        {
          "type": "StillImage",
          "version": "thumbnail image",
          "identifier": "http://collectionsearch.nma.gov.au/nmacs-image-download/piction/dams_data/prodderivT/PH2027/Collection/Working%20Masters/nma_22993676.jpg"
        }
      ]
    }
  ],
  "_meta": {
    "modified": "2018-04-03",
    "issued": "2008-10-14",
    "hasFormat": "http://collectionsearch.nma.gov.au/object/14693"
  }
}

Narrative

GET http://nma.conaltuohy.com/narrative/2462

{
  "id": "2462",
  "type": "narrative",
  "title": "Bark Paintings",
  "isPartOf": [
    {
      "id": "2429",
      "type": "narrative",
      "title": "Mediums"
    }
  ],
  "aggregates": [
    {
      "id": "146615",
      "type": "object",
      "title": "Bark painting titled Kingfisher and Mangrove Tree"
    },
    {
      "id": "147352",
      "type": "object",
      "title": "Bark painting depicting double Wandjinas."
    }
  ],
  "_meta": {
    "modified": "2018-03-21",
    "hasFormat": "http://collectionsearch.nma.gov.au/set/2462"
  }
}

Party

GET http://nma.conaltuohy.com/party/12473

{
  "id": "12473",
  "type": "party",
  "name": "Mildred M. Turner",
  "givenName": "Mildred",
  "middleName": "Mary",
  "familyName": "Turner",
  "alternativeNames": [
    "Mildred Mary Raymond"
  ],
  "gender": "female"
}

Place

GET http://nma.conaltuohy.com/place/1489

{
  "id": "1489",
  "type": "place",
  "title": "Yirrkala, East Arnhem Land, Northern Territory, Australia",
  "location": "-12.2528,136.892"
}

Collection

GET http://nma.conaltuohy.com/collection/2066

{
  "id": "2066",
  "type": "collection",
  "title": "Dr Herbert Basedow collection"
}

Common fields

Simple JSON
Field Type Description Example
id int Persistent internal ID 12345
type string The entity type object, party
title string The entity label Bark canoe
_meta object Metadata record attributes {modified:"2018-04-20"}

Searching

Specify your query terms in the text query string parameter.

GET http://nma.conaltuohy.com/object?text=bark

[
  {
    "id": "21218",
    "type": "object",
    "additionalType": "Bark paintings",
    "title": "Bark painting",
    "collection": "Dr Howard Morphy collection no. 3",
    "identifier": "1985.0269.0015",
    ...
  },
  {
    "id": "18390",
    "type": "object",
    "additionalType": "Bark paintings",
    "title": "Bark painting",
    "collection": "Dr Helen M Wurm collection no. 2",
    "identifier": "1985.0112.0005",
    ...
  }
]

Basic query syntax

Query type Example
Keyword ?text=bark
Phrase ?text="bark painting"
All words (and) ?text=bark painting
Any words (or) ?text=bark&text=wood
Wildcards ?text=paint*
?modified=2018-04-*
Field search ?title=bark&collection="Ruth Oldfield"

Searchable fields

Endpoint Field Searches over...
/object text All textual content
title Collection item labels
description All descriptions, incl. physical and significance (see below)
additionalType Collection item types, e.g. rug, toy
creator Names of people or organisations who helped produce collection items, incl. their role, e.g. Designer
contributor Associated people or organisations, incl. their relationship, e.g. Collector
temporal Dates associated with collection items, incl. their relationship, e.g. Date of race
spatial Places associated with collection items, incl. their relationship, e.g. Place of race
collection Collection names, e.g. MacKenzie collection
medium Materials collection items are made of, e.g. wood
rights Rights or licences for re-use of images/media, e.g. CC BY-NC-SA 4.0
identifier Accession numbers, e.g. 1984.0010.0721
media IRIs of attached media (search * to discover items with media attached)
modified Dates when records were last modified in the museum catalogue
issued Dates when records were released on to the Museum's Collection Explorer website
contentDescription Descriptions of collection items
physicalDescription Physical descriptions of collection items
educationalSignificance Contextual descriptions explaining why collection items were collected
significanceStatement Statements on the significance of collections and the items in them
/narrative text All textual content
title Narrative labels
description Narrative text
modified Dates that records were last modified in the museum catalogue
/party text All textual content
name Names of people or organisations
gender Person's gender
/place text All textual content
title Names of locations, e.g. Victoria, Australia
location Geo coordinates, e.g. -12.2528,136.892

Reverse-searchable fields

These fields only search over record IDs to discover known-related records. For example, if you have a person's party ID 12473, you can search for that ID in the creator_id field to find all collection items that this person created.

GET http://nma.conaltuohy.com/object?creator_id=12473
Endpoint Field Use a.. To retrieve...
/object creator_id party ID Collection items created by this party
contributor_id party ID Collection items that this party is associated with
spatial_id place ID Collection items produced in, or associated with, this place
collection_id collection ID Collection items in this collection
media_id media ID Collection items that this media represents
/narrative aggregates_id object id Narratives that this object appears in
narrative_isPartOf_id narrative ID Child narratives (that are part of this narrative)
narrative_hasPart_id narrative ID The parent narrative (that this narrative is part of)

Results count

The number of results found for your query appears in an HTTP response header Result-Count:

GET http://nma.conaltuohy.com/object?text=bark

Result-Count: 2091

Pagination

You can retrieve large result sets in chunks by making multiple requests to retrieve each 'page'. Use the offset and limit query string parameters.

Notes:

  • offset starts from 0
  • limit defaults to 50, and has a maximum value of 100
  • the query response includes an HTTP header Link containing a pre-built link to follow to retrieve the next page of results:
GET http://nma.conaltuohy.com/object?text=bark&offset=40&limit=10

Result-Count: 2091
Link: <object?text=bark&offset=50&limit=10>; rel=next

Sorting

Search query results are presented in relevance order (the closest matches appear first).

You can choose a different order by adding a sort query string parameter with the field to sort on (see below) and in which direction: asc-ending or desc-ending. Use a space before the direction (as either + or %20).

GET http://nma.conaltuohy.com/object?text=bark&sort=title_sort+asc

Note: If a record is missing a value for the field you choose to sort on, then it is removed from the results during re-sorting.

Endpoint Sort field Sorts on...
/object [none] Query relevance (default)
title_sort Collection item labels
modified_sort Dates when records were last modified in the museum catalogue
/narrative [none] Query relevance (default)
title_sort Narrative labels
modified_sort Dates that records were last modified in the museum catalogue
/place [none] Query relevance (default)
title_sort Names of locations, e.g. Victoria, Australia
/collection [none] Query relevance (default)
title_sort Collection names

Beta release known issues

Missing metadata

We are in the process of releasing records to the API. The Beta release currently has 30,000 of the 80,000 object records in the museum catalogue. This means narratives may contain links to objects that do not appear in the API yet (so will return an HTTP 404 Not Found error).

Entity Missing fields Unsearchable
Object Simple format: gallery location, media mime type, media dimensions Gallery location, media details
Place Linked Art & Simple formats: individual fields for each ancestor place -

Object metadata fields currently not included

  • Parent/child relationship
  • Related object
  • Web project code
  • Web link and note
  • Access restriction reason
  • Feature item flag
  • Acknowledgement flag
  • Inward loan flag
  • Free to read flag
  • NB: Piction image resolution is not available

Home

Getting started

Searching the API

Harvesting in Bulk

Clone this wiki locally