Getting started - NationalMuseumAustralia/Collection-API GitHub Wiki

On this page:

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.

It is a RESTful API based on a Solr database and returns JSON formatted results.

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

Data

The metadata records in the API are copyright to the Museum, but are made available as Open Data under a Creative Commons Attribution-NonCommercial (CC BY-NC 4.0) licence. This includes the labels, descriptions, etc. but not the media (see the next section). The metadata records may be used for any purpose (including commercially), with attribution to the National Museum of Australia.

Media

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 media's copyright is All Rights Reserved and the media may not be used without permission of the copyright holder.

Feedback and inquiries

We welcome your feedback and questions. You can join our user forum on GitHub, or email [email protected]

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

Access

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

https://data.nma.gov.au/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.

Using an API key

The API can be accessed using an API key:

  • Rate limiting is not applied when using an API key
  • An ‘internal’ API key allows access to certain information restricted to public users

Register for an API key

There are two ways to use an API key:

  1. Include the key as the value of an apikey HTTP request header (recommended)
GET https://data.nma.gov.au/object/14693
apikey: XXXXXX
  1. Include the key as a parameter in the request URI. This is a convenience for testing requests using a browser, we do not recommend using the apikey query parameter in production.
https://data.nma.gov.au/object/14693&apikey=XXXXX

API endpoints

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.

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

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 https://data.nma.gov.au/object/14693

{
  "data": [
    {
      "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": [
        {
          "type": "Material",
          "title": "Glass"
        },
        {
          "type": "Material",
          "title": "Photographic emulsion"
        }
      ],
      "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",
          "geo": "-25,133"
        },
        {
          "id": "80110",
          "type": "Place",
          "title": "Australia",
          "roleName": "Place depicted"
        }
      ],
      "temporal": [
        {
          "type": "Event",
          "title": "1911",
          "startDate": "1911",
          "endDate": "1911",
          "roleName": "Date photographed",
          "interactionType": "Production"
        },
        {
          "type": "Event",
          "title": "1911",
          "startDate": "1911",
          "endDate": "1911",
          "roleName": "Date photographed"
        }
      ],
      "hasVersion": [
        {
          "id": "MA22994856",
          "type": "StillImage",
          "identifier": "http://data.nma.gov.au/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",
              "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://data.nma.gov.au/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",
              "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-06-07",
        "issued": "2008-10-14",
        "hasFormat": "http://collectionsearch.nma.gov.au/object/14693",
        "copyright": "Copyright National Museum of Australia / CC BY-NC",
        "licence": "https://creativecommons.org/licenses/by-nc/4.0/"
      }
    }
  ]
}

Narrative

GET https://data.nma.gov.au/narrative/2462

{
  "data": [
    {
      "id": "2462",
      "type": "narrative",
      "additionalType": [
        "Collection Explorer publish",
        "collection (object grouping)"
      ],
      "title": "Bark Paintings",
      "isPartOf": [
        {
          "id": "2429",
          "type": "narrative",
          "title": "Mediums"
        }
      ],
      "aggregates": [
        {
          "id": "147360",
          "type": "object",
          "title": "Djangawu Ritual Story, by Roy Dadaynga Marika.",
          "_meta": {
            "hasFormat": "http://collectionsearch.nma.gov.au/object/147360"
          }
        },
        {
          "id": "145787",
          "type": "object",
          "title": "Djilaybunyamurr, a painting by Jonny Bulun Bulun",
          "_meta": {
            "hasFormat": "http://collectionsearch.nma.gov.au/object/145787"
          }
        }
      ],
      "_meta": {
        "modified": "2018-03-21",
        "copyright": "Copyright National Museum of Australia / CC BY-NC",
        "licence": "https://creativecommons.org/licenses/by-nc/4.0/"
      }
    }
  ]
}

Party

GET https://data.nma.gov.au/party/12473

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

Place

GET https://data.nma.gov.au/place/1489

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

Collection

GET https://data.nma.gov.au/collection/2066

{
  "data": [
    {
      "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 https://data.nma.gov.au/object?text=bark

{
  "data": [
    {
      "id": "20761",
      "type": "object",
      "additionalType": [
        "Bark paintings"
      ],
      "title": "Bark painting",
      "collection": {
        "id": "2214",
        "type": "Collection",
        "title": "J Davidson collection no. 3"
      },
      "identifier": "1985.0259.0134",
      …
      "_meta": {
        "modified": "2018-07-09",
        "issued": "2013-06-19",
        "hasFormat": "http://collectionsearch.nma.gov.au/object/20761",
        "copyright": "Copyright National Museum of Australia / CC BY-NC",
        "licence": "https://creativecommons.org/licenses/by-nc/4.0/"
      }
    },
    {
      "id": "50889",
      "type": "object",
      "additionalType": [
        "Baskets"
      ],
      "title": "Basket made of a malleable bark or paper bark",
      "collection": {
        "id": "1254",
        "type": "Collection",
        "title": "Reverend and Mrs Fenn collection no. 2"
      },
      "identifier": "1992.0039.0025",
      …
      "_meta": {
        "modified": "2018-06-18",
        "issued": "2007-02-01",
        "hasFormat": "http://collectionsearch.nma.gov.au/object/50889",
        "copyright": "Copyright National Museum of Australia / CC BY-NC",
        "licence": "https://creativecommons.org/licenses/by-nc/4.0/"
      }
    }
  ],
  "meta": {
    "results": 2410
  },
  "links": {
    "next": "object?text=bark&offset=50"
  }
}

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"

How to search the API

Find out more details on searching on the page: Searching the API

The page includes:

  • Common search strategies
  • A list of the searchable fields

Results count

The number of results found for your query appears in an HTTP response header Result-Count and in the meta field in the JSON response.

GET https://data.nma.gov.au/object?text=bark

Result-Count: 2410

{
  "data": [
     …
  ],
  "meta": {
    "results": 2410
  },
  "links": {
    "next": "object?text=bark&offset=50"
  }
}

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 https://data.nma.gov.au/object?text=bark&offset=40&limit=10

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

See Harvesting in bulk from the Collection API for more about retrieving multiple pages of data.

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 https://data.nma.gov.au/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
⚠️ **GitHub.com Fallback** ⚠️