Searching the API - NationalMuseumAustralia/Collection-API GitHub Wiki

On this page:

See also:

Basic query

For basic searching, specify your query terms in the text query string parameter.

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

The names of the searchable fields are listed below.

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"

Retrieving objects by date, place, or party

It is possible to search for objects in the Museum which are related to particular places, people, organisations, or dates.

Note that these places, people, and dates may relate to the collection objects in different ways, including:

  • places where the object was created, or was found, or used
  • people and organisations who created them, or commissioned their creation
  • dates they were created, or dates they were put on display, or dates of events which the objects commemorate.

Although the data you can retrieve using the API does distinguish these different cases, the search fields provided in the API do not always.

People (and organisations) are treated differently if they created the object. The API provides a creator field for the people who created an object, and a separate contributor field for all other people related to the object in any other way.

However, in the simple format, dates and places are treated equally, so creation dates/places are not separated out, instead they are all in the spatial place field or temporal date field, and each value might contain an interactionType flag field containing the value 'Production' (if the date/place is for the object's creation).

{
  "spatial": [
    {
      "id" : "45",
      "type" : "Place",
      "title" : "Melbourne, Victoria, Australia",
      "roleName": "Place designed",
      "interactionType" : "Production",
      "geo" : "-37.8167,144.967"
    },
    {
      "id": "80110",
      "type": "Place",
      "title": "Australia",
      "roleName": "Place depicted"
    }
  ]
}

For example, if you wish to find only objects which were created in a particular year, you will need to search for objects related to that year and also filter the resulting list yourself - by selecting only the records for which the date is a creation date (has interactionType of Production) rather than some other kind of date.

In the JSON-LD format, production places and dates can be found separated in produced_by.

Common search strategies

Objects with media/images

The media details appear in the hasVersion field, but you search in the media field (which contains the media's identifier).

The returned hasVersion field contains one or more files, and each file contains one or more hasVersion child records linking to each version of the file (e.g. thumbnail, preview).

To find every record in the object endpoint that has any media (i.e. has an identifier in the media field):

GET https://data.nma.gov.au/object?media=*

[
  {
    "id": "124027",
    "type": "object",
    "title": "Oak oil stone",
    "hasVersion": [
      {
        "id": "MA67849706",
        "type": "StillImage",
        "identifier": "http://data.nma.gov.au/media/MA67849706#",
        "rights": "https://creativecommons.org/licenses/by-sa/4.0/",
        "rightsTitle": "CC BY-SA 4.0",
        "hasVersion":
        [
          {
            "type": "StillImage",
            "version": "preview image",
            "identifier": "http://collectionsearch.nma.gov.au/nmacs-image-download/piction/dams_data/prodderivW/DAMS_INGEST/JOBS/WM_67828117/nma-acc-20183042-132-wm.jpg"
          },
          {
            "type": "StillImage",
            "version": "thumbnail image",
            "identifier": "http://collectionsearch.nma.gov.au/nmacs-image-download/piction/dams_data/prodderivT/DAMS_INGEST/JOBS/WM_67828117/nma-acc-20183042-132-wm.jpg"
          },
          {
            "type": "StillImage",
            "version": "large image",
            "identifier": "http://collectionsearch.nma.gov.au/nmacs-image-download/piction/dams_data/prodderiv3/WM_67828117/nma-acc-20183042-132-wm_o3.jpg"
          }
        ]
      }
    ],
    ...
  },
  ...
]

To find object records containing the word ‘stone’ that also contain a media identifier:

GET https://data.nma.gov.au/object?text=stone&media=*

Media can be used commercially

To find every record in the object endpoint that has media with rights that allow that media to be used commercially (i.e. a Creative Commons Attribution-ShareAlike licence):

GET https://data.nma.gov.au/object?rights=by-sa

For the full list of media rights and licence types used, see the Copyright section in Getting started.

Works by an artist/creator

The creator field in object records contains the creator's name as well as any specific role such as "painter", "sculptor", etc.

To find objects that were designed by Teddy Tinling, search for every record in the object endpoint containing all the words teddy, tinling, and designer in the creator field. Note that the + (plus sign) represents a space:

GET https://data.nma.gov.au/object?creator=teddy+tinling+designer

To find objects that were made by Teddy Tinling:

GET https://data.nma.gov.au/object?creator=teddy+tinling+maker

To find objects in which Teddy Tinling played any creative role, just search by name:

GET https://data.nma.gov.au/object?creator=teddy+tinling

To find objects in which party 12072 (Teddy Tinling) played any creative role, search in the creator_id field:

GET https://data.nma.gov.au/object?creator_id=12072

Works a person contributed to

The contributor field in object records contains the names of people who contributed to the object somehow without being its 'creator'.

To search for objects in which Pope John Paul II was a contributor, search for every record in the object endpoint containing all the words Pope, John, Paul, II in the contributor field. Note that the + (plus sign) represents a space:

GET https://data.nma.gov.au/object?contributor=Pope+John+Paul+II

As with the creator search field, the contributor field may include the role of the contributor (such as "user" or "owner"), though it's often just "associated person".

Searching by place

The spatial field in object records contains the names of places associated with the object and how those places are associated (such as where it was "collected").

To find objects associated with the Queensland locality Springsure, search for every record in the object endpoint containing the word Springsure in the spatial field:

GET https://data.nma.gov.au/object?spatial=springsure

To find objects collected in Springsure, you can include the word "collected" in your search:

GET https://data.nma.gov.au/object?spatial=collected+Springsure

To find objects associated with the place 1826 (Springsure), search the spatial_id field:

GET https://data.nma.gov.au/object?spatial_id=1826

Searching by date

(Date fields are discussed in more detail below.)

The temporal field in object records contains the dates of events associated with the object and how those events are associated (such as creation, when the object changed hands, or when it was first exhibited publicly).

There is an extra searchable temporal_date field that contains the date encoded as a range of dates, which may cover a single day, or may cover a year or more, depending on the type of event and how precisely the details of the event are known to the Museum.

Typically you would be interested in a particular date, and you would search for objects where your date fell within the objects' date ranges.

{
  "temporal" : [
    {
      "type" : "Event",
      "title" : "1768 - 1771",
      "startDate" : "1768",
      "endDate" : "1771",
      "roleName" : "Date of voyage"
    },
    {
      "type" : "Event",
      "title" : "- 20 February 1923",
      "endDate" : "1923-02-20",
      "roleName" : "Date collected",
      "description" : "Collected before February 1923"
    }
  ]
}

To find objects relating to the year 1769, search for every record in the object endpoint containing 1769 in the temporal_date field:

Note that the results of this query will include records which are missing a start date and whose end date falls after 1769 (i.e. objects which have a date range such as '1923'). To exclude objects which are missing start or end dates, you will need to filter the data you have retrieved to exclude records with no startDate or endDate field within their temporal object.

GET https://data.nma.gov.au/object?temporal_date=1769

To find every record in the object endpoint that is associated with the date 17 July 2000:

GET https://data.nma.gov.au/object?temporal_date=2000-07-18

To find every record in the object endpoint that is associated with any date between 1914 and 1918 (inclusive) (note that the + (plus sign) represents a space):

GET https://data.nma.gov.au/object?temporal_date=[1914+TO+1918]

Modified since a date

(Date fields are discussed in more detail below.)

To find every record in the object endpoint that has been modified by museum staff since (the beginning of) March 2007 (note that the + (plus sign) represents a space, and the year 2999 represents 'no end date'):

GET https://data.nma.gov.au/object?modified_date=[2007-03+TO+2999]

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, along with a textual label for the association, e.g. Date of race, 1768 1771 voyage
spatial Places associated with collection items, incl. their relationship, e.g. Place of race
collection Collection names, e.g. Winifred Hilliard collection no. 3
collection_id Collection identifier, e.g. 5244
acknowledgement e.g. Donated through the Australian Government's Cultural Gifts Program by Wayne and Vicki McGeoch
location Location where the object is displayed in the Museum e.g. Landmarks: People and Places across Australia gallery; use location=* to find all objects which are currently on display.
source Objects which are on loan from another institution will contain Inward loan; otherwise this field is blank.
medium Materials collection items are made of, e.g. wood
unitText The unit of measurement of the object's dimensions, e.g. mm, cm
unitTextWeight The unit of measurement of the object's weight, e.g. g, kg
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
seeAlso URL of a web page which objects are known to be related to. NB you will need to URL-encode the page URL to use it as the value of the seeAlso parameter, e.g. http://www.nma.gov.au/​exhibitions/​expedition_photographs_h_basedow_1903_1928/
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
status_code HTTP status code of record; search for 410 to retrieve a list of deleted records
/narrative text All textual content
title Narrative labels
description Narrative text
modified Dates that records were last modified in the museum catalogue
status_code HTTP status code of record; search for 410 to retrieve a list of deleted records
/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
geo Geo coordinates, e.g. -12.2528,136.892

Date fields

In addition to the free text fields listed above, there are some fields which can be searched as dates, including by specifying a date range.

Date search fields can be specified in the form YYYY-MM-DD. Valid queries can specify just the year, or just the year and month, or a year, month and day. e.g.

  • datestamp=2018-08-13
  • temporal_date=1950

Date search fields can also be specified as ranges. To retrieve resources belonging to a range of dates, format the start and end dates by inserting +TO+ (or equivalently %20TO%20; NB both + and %20 are used in a URL to represent a space) between them, and enclosing the pair in square brackets, e.g. to retrieve records updated from the 13th of August 2018 until the year 2999, use this query: datestamp=[2018-08-13%20TO%202999]

Endpoint Field Meaning
(all) datestamp Date on which the API resource last changed. Generally "harvester" applications using the API to maintain a cache of API data should use the datestamp field to request updates. See Harvesting in bulk from the Collection API for more about using this field
issued_date The date of first publication of the information resource in the web API
modified_date The date at which the web API resource's primary data source was last updated.
/object temporal_date The date of an event in the life of an object; it may be the date the object was created, or acquired, or exhibited, or any other kind of date.

Measurements

The following fields are used to query for objects with particular measurements. Numeric fields can be searched either for an exact value, or more usefully, for a matching range. Ranges are specified by giving a low and a high value separated by +TO+, and surrounded by square brackets. For example, to search for objects exactly 5mm high, use the query /object?height=5&unitText=mm. To search for objects whose height is in the range 5 to 10mm, use the query /object?height=[5+TO+10]&unitText=mm

Endpoint Field Meaning
/object unitText The measurement unit for width, height, length, depth, typically mm
width The width of the object
height The height of the object
length The length of the object
depth The depth of the object
unitTextWeight The measurement unit for weight, typically g, but also kg, lb, oz and tonne
weight The weight of the object

Dimensions can be combined, as in this search for very small dogs (items called dog which are small enough to fit inside a 100mm cube): https://data.nma.gov.au/object?title=dog&length=[0+TO+100]&width=[0+TO+100]&height=[0+TO+100]&unitText=mm

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 https://data.nma.gov.au/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
isPartOf_object_id object ID Child objects (that are part of this object)
hasPart_object_id object ID The parent object (that this object is part of)
related_object_id object ID Objects related to this object (NB the exact nature of the relationship is not specified; it means no more than "see also")
/narrative aggregates_object_id object id Narratives that this object appears in
isAggregatedBy_narrative_id narrative ID Objects that are mentioned in the narrative
isPartOf_narrative_id narrative ID Child narratives (that are part of this narrative)
hasPart_narrative_id narrative ID The parent narrative (that this narrative is part of)
/media media_object_id object id Media (i.e. images) that depict this object