Stories Organisations Projects About Login

The Victorian Collections API

Version History

version release date description
1.0 18 July 2013 original release
2.0 1 June 2015 new functionality & request/response formats; requirement for api key specification

Please note: This version 2 release of the Victorian Collections API is a public beta meaning it might have one or two bugs here and there. If you have any problems, do please let us know.

We're yet to add a couple of features (mainly stuff around search and sorting). We will update this document as soon as we have done this, and we'll make sure we inform any developers who have received an API key.

It is our intention that aspects of the API already documented here will not change in this version 2 release. Some methods described here may receive some additional arguments but we're going to do our best to not break your code by otherwise renaming, removing or altering existing methods, arguments and request/response formats.

So please - apply for a key and begin experimenting. We're really looking forward to seeing what you come up with!

The Victorian Collections API provides programmatic access to all publically available collector and collection item record data on the website. It enables developers to reuse Victorian Collections data within their websites/applications, in accordance with our terms and conditions.

The API is a REST api that consists of a set of methods that return structured collection records and collector data from the website. The API is read-only. The only supported HTTP Verb is GET (ie: retrieve or search). POST, PUT, DELETE etc are not supported.

Api Key

A developer must obtain a personal key before they can begin using the Victorian Collections API. The API key helps us to track usage and limit abuse of the API. The key must be supplied with each API request (see authentication).

To apply for an API key, please Contact us and supply details on how you intend to use the Victorian Collections API.

Requests

All API methods have the same URL format:

https://victoriancollections.net.au/api/v2/{method}

Method arguments

The methods provided by the API take a range of arguments specific to that method (see methods). Arguments are specified within the query string.

Authentication

All requests must be authenticated by inclusion of a valid API key. Requests that do not include a valid API Key will fail with an error. The best way to include the API key is by providing it within the request header using the header field api_key.

GET https://victoriancollections.net.au/api/v2/{method}...
api_key: {your-api-key}

Alternatively the api_key may be specified within the query string:

GET https://victoriancollections.net.au/api/v2/{method}?api_key={your-api-key}...

Responses

Encoding

Responses are returned as JSON by default. You may request an XML response by issuing your HTTP GET request with an accept header value of text/xml.

GET https://victoriancollections.net.au/api/v2
Accept: text/xml

Alternatively the response encoding may be requested within the query string using the parameter/value accept=xml

GET https://victoriancollections.net.au/api/v2/{method}?accept=xml...

Successful Requests

A successful request will return a response with:

  • a status element containing the value ok
  • a result element containing the data returned by the request
e.g. (JSON)

{ "status":"ok", "result":{ ... } }

e.g. (XML)

<response>
   <status>ok</status>
    result>
      ...
   </result>
</response>

The structure of the result element will depend on the method called.

Failed Requests

A failed request will return a response with:

  • a status element containing the value error
  • a result element containing the error message
{ "status":"error", "result":{ "errorMessage": "ERROR_MESSAGE" } }

Methods

The following methods are available. Arguments for these methods are optional unless otherwise indicated.

GET /itemIds/

Return a list of ids for the collection items matching the given criteria.

Arguments

argument type description
offsetintegerthe index of the full result set to start the request results; default 0
filterstring, multiple argsquery filters
limitintegerhow many results to return; default 20, maximum 100
modifiedFromISO 8601 UTC DateTimelimit results to collection items last modified after this date/time
modifiedToISO 8601 UTC DateTimelimit results to collection items last modified before this date/time
collectorIdstringThe id[1] or key[2] of a collector whose items you wish to retrieve; if omitted, items from all collectors will be searched

1. The collector's 'id' is the 12 byte hexadecimal string that forms the unique record identifier for that collector.

2. The collector's 'key' is a url-friendly version of the collector's name. It forms part of the URL for that collector's page on Victorian Collections.

Query filters

The filter argument enables you to specify filters to include or exclude results. Multiple filters can be specified using a single 'filter' argument with comma-seperated filters, or by using multiple filter arguments.

filter purpose
hasImage:true exclude items without images
hasImage:false exclude items with images

Example

Request

GET https://victoriancollections.net.au/api/v2/itemIds?filter=hasImage:true&limit=2&collectorId=52f0757a9821f40464f73cc3
api_key: {your-api-key}

Response
{
  "status": "ok",
  "result": {
    "totalResultCount": 4,
    "offset": 0,
    "resultLimit": 2,
    "resultCount": 2,
    "resultSet": [
      "56e75e1c2162f11d3c6c4a90",
      "56e8d2562162f11d3cc069c4"
    ]
  }
}

GET /items/

Return a list of records for the items matching the given criteria.

Arguments

argument type description
offsetintegerthe index of the full result set to start the request results; default 0
include string, multiple args see requesting additional item fields
filterstring, multiple argsquery filters
limitintegerhow many results to return; default 20, maximum 100
modifiedFromISO 8601 UTC DateTimelimit results to collection items last modified after this date/time
modifiedToISO 8601 UTC DateTimelimit results to collection items last modified before this date/time
collectorIdstringThe id[1] or key[2] of a collector whose items you wish to retrieve; if omitted, items from all collectors will be searched
Notes

1. The collector's 'id' is the 12 byte hexadecimal string that forms the unique record identifier for that collector.

2. The collector's 'key' is a url-friendly version of the collector's name. It forms part of the URL for that collector's page on Victorian Collections.

Query filters

The filter argument enables you to specify filters to include or exclude results. Multiple filters can be specified using a single 'filter' argument with comma-seperated filters, or by using multiple filter arguments.

filter purpose
hasImage:true exclude items without images
hasImage:false exclude items with images

Example

Request

GET https://victoriancollections.net.au/api/v2/items?filter=hasImage:true&limit=2&collectorId=52f0757a9821f40464f73cc3&format=dc
api_key: {your-api-key}

Response
{
  "status": "ok",
  "result": {
    "totalResultCount": 4,
    "offset": 0,
    "resultLimit": 2,
    "resultCount": 2,
    "resultSet": [
      {
        "dc:title": "The Hospital South of the Yarra A history of Alfred Hospital Melbourne from foundation to the nineteen-forties",
        "dc:creator": [
          "Ann M Mitchell"
        ],
        "dc:contributors": [
          "Ann M Mitchell"
        ],
        "dc:coverage": "",
        "dc:description": "Small Book 299 Pages Red Cover; Inscriptions and Markings: The Hospital South of the Yarra, Ann M Mitchell",
        "dc:identifier": "56e75e1c2162f11d3c6c4a90",
        "dc:rights": "You may download, display, print or reproduce this image in an unaltered form and with acknowledgement to Alfred Health including The Alfred, Caulfield Hospital and Sandringham Hospital for personal, educational and private research use. If you wish to use it for any other purposes you must obtain permission from Alfred Health including The Alfred, Caulfield Hospital and Sandringham Hospital.",
        "dc:subject": [
          "the alfred",
          "history",
          "1871",
          "1940's",
          "medical",
          "patients",
          "health",
          "hospital"
        ],
        "dc:language": "English en-au",
        "deleted": false,
        "id": "56e75e1c2162f11d3c6c4a90",
        "collectorId": "52f0757a9821f40464f73cc3",
        "dateModified": "2017-03-02T23:12:21.689Z",
        "itemPageUrl": "http://localhost:10917/items/56e75e1c2162f11d3c6c4a90",
        "thumb": "/media/collectors/52f0757a9821f40464f73cc3/items/56e75e1c2162f11d3c6c4a90/56e7614f2162f11d3c6defe5/item-130x0.jpg",
        "registration": "1"
      },
      {
        "dc:title": "The wounded warrior and rehabilitation: including the history of no. 11 Army General Hospital - Caulfield Rehabilitation Hospital ",
        "dc:creator": [],
        "dc:contributors": [],
        "dc:coverage": "",
        "dc:description": "Paper back edition of The wounded warrior and rehabilitation: including the history of no. 11 Army General Hospital - Caulfield Rehabilitation Hospital Published by The Alfred Healthcare Group [Caulfield general Medical Centre] 1966 by Bruce Ford former Medical Director of Caulfield Hospital; Inscriptions and Markings: Unmarked",
        "dc:identifier": "56e8d2562162f11d3cc069c4",
        "dc:rights": "You may download, display, print or reproduce this image in an unaltered form and with acknowledgement to Alfred Health including The Alfred, Caulfield Hospital and Sandringham Hospital for personal, educational and private research use. If you wish to use it for any other purposes you must obtain permission from Alfred Health including The Alfred, Caulfield Hospital and Sandringham Hospital.",
        "dc:subject": [
          "history",
          "hospital",
          "caulfield",
          "no 11 army general hospital",
          "repatriation hospital caulfield",
          "convalescent hospital caulfield",
          "caulfield general medical centre",
          "southern memorial hospital [later renamed royal southern memorial hospital]",
          "artificial limb factory [rehabtech]"
        ],
        "dc:language": "English en-au",
        "deleted": false,
        "id": "56e8d2562162f11d3cc069c4",
        "collectorId": "52f0757a9821f40464f73cc3",
        "dateModified": "2017-03-02T23:12:22.283Z",
        "itemPageUrl": "http://localhost:10917/items/56e8d2562162f11d3cc069c4",
        "thumb": "/media/collectors/52f0757a9821f40464f73cc3/items/56e8d2562162f11d3cc069c4/56ef01452162f122f8675c45/item-130x0.jpg",
        "registration": "1001"
      }
    ]
  }
}

GET /items/{itemId}

Return the item record with the given id, a 12 byte hexadecimal string.

Arguments

argument type description
include string, multiple args see requesting additional item fields

Example

Request

GET https://victoriancollections.net.au/api/v2/items/56e75e1c2162f11d3c6c4a90?format=dc
api_key: {your-api-key}

Response
{
  "status": "ok",
  "result": {
    "dc:title": "The Hospital South of the Yarra A history of Alfred Hospital Melbourne from foundation to the nineteen-forties",
    "dc:creator": [
      "Ann M Mitchell"
    ],
    "dc:contributors": [
      "Ann M Mitchell"
    ],
    "dc:coverage": "",
    "dc:description": "Small Book 299 Pages Red Cover; Inscriptions and Markings: The Hospital South of the Yarra, Ann M Mitchell",
    "dc:identifier": "56e75e1c2162f11d3c6c4a90",
    "dc:rights": "You may download, display, print or reproduce this image in an unaltered form and with acknowledgement to Alfred Health including The Alfred, Caulfield Hospital and Sandringham Hospital for personal, educational and private research use. If you wish to use it for any other purposes you must obtain permission from Alfred Health including The Alfred, Caulfield Hospital and Sandringham Hospital.",
    "dc:subject": [
      "the alfred",
      "history",
      "1871",
      "1940's",
      "medical",
      "patients",
      "health",
      "hospital"
    ],
    "dc:language": "English en-au",
    "deleted": false,
    "id": "56e75e1c2162f11d3c6c4a90",
    "collectorId": "52f0757a9821f40464f73cc3",
    "dateModified": "2017-03-02T23:12:21.689Z",
    "itemPageUrl": "http://localhost:10917/items/56e75e1c2162f11d3c6c4a90",
    "thumb": "/media/collectors/52f0757a9821f40464f73cc3/items/56e75e1c2162f11d3c6c4a90/56e7614f2162f11d3c6defe5/item-130x0.jpg",
    "registration": "1"
  }
}

GET /collectorIds/

Return a list of ids for the collectors matching the given criteria.

Arguments

argument type description
offsetintegerthe index of the full result set to start the request results; default 0
limitintegerhow many results to return; default 20, maximum 100
filterstring, multiple argsquery filters
modifiedFromISO 8601 UTC DateTimelimit results to collectors last modified after this date/time
modifiedToISO 8601 UTC DateTimelimit results to collection items last modified before this date/time

Query filters

The filter argument enables you to specify filters to include or exclude results. Multiple filters can be specified using a single 'filter' argument with comma-seperated filters, or by using multiple filter arguments.

filter purpose
hasCollectionItem:true exclude collectors without collection items
hasCollectionItem:false exclude collectors with collection items
hasCollectionImage:true exclude collectors without collection items that have images
hasCollectionImage:false exclude collectors with collection items that have images

Example

Request

GET https://victoriancollections.net.au/api/v2/collectorIds?filter=hasImage:true&limit=2
api_key: {your-api-key}

Response
{
  "status": "ok",
  "result": {
    "totalResultCount": 1017,
    "offset": 0,
    "resultLimit": 2,
    "resultCount": 2,
    "resultSet": [
      "4f729f7497f83e0308601806",
      "515120c22162ef0d94ec25ad"
    ]
  }
}

GET /collectors/

Return a list of collectors matching the given criteria.

Arguments

argument type description
offsetintegerthe index of the full result set to start the request results; default 0
limitintegerhow many results to return; default 20, maximum 100
filterstring, multiple argsquery filters
modifiedFromISO 8601 UTC DateTimelimit results to collectors last modified after this date/time
modifiedToISO 8601 UTC DateTimelimit results to collection items last modified before this date/time
include string, multiple args see requesting additional collector fields

Query filters

The filter argument enables you to specify filters to include or exclude results. Multiple filters can be specified using a single 'filter' argument with comma-seperated filters, or by using multiple filter arguments.

filter purpose
hasCollectionItem:true exclude collectors without collection items
hasCollectionItem:false exclude collectors with collection items
hasCollectionImage:true exclude collectors without collection items that have images
hasCollectionImage:false exclude collectors with collection items that have images

Example

Request

GET https://victoriancollections.net.au/api/v2/collectors?filter=hasCollectionImage:true&include=name,location&limit=2
api_key: {your-api-key}

Response
{
  "status": "ok",
  "result": {
    "totalResultCount": 1017,
    "offset": 0,
    "resultLimit": 2,
    "resultCount": 2,
    "resultSet": [
      {
        "id": "4f729f7497f83e0308601806",
        "name": "4th/19th Prince of Wales's Light Horse Regiment Unit History Room",
        "locationStreet1": "Simpson Barracks ",
        "locationTownSuburb": "Macleod",
        "locationState": "Victoria",
        "locationLatitude": "-37.72129",
        "locationLongitude": "145.0913"
      },
      {
        "id": "515120c22162ef0d94ec25ad",
        "name": "5/6 Royal Victorian Regiment",
        "locationStreet1": "202 Burwood Road",
        "locationTownSuburb": "Hawthorn",
        "locationState": "Victoria",
        "locationLatitude": "",
        "locationLongitude": ""
      }
    ]
  }
}

GET /collectors/{collectorIdentifier}

Return the record of the collector with the given identifier. This particular method accepts two different types of identifier - a unique id or a unique key.

The collector's 'id' is the 12 byte hexadecimal string that forms the unique record identifier for that collector.

The collector's 'key' is a url-friendly version of the collector's name. It forms part of the URL for that collector's page on Victorian Collections.

e.g. https://victoriancollections.net.au/collectors/national-wool-museum

Arguments

argument type description
include string, multiple args see requesting additional collector fields

Example

Request

(using an id)
GET https://victoriancollections.net.au/api/v2/collectors/510b3f7f023fd725b4cd52cc?include=name,location
api_key: {your-api-key}

(using a key)
GET https://victoriancollections.net.au/api/v2/collectors/national-wool-museum?include=name,location
api_key: {your-api-key}

Response
{
  "status": "ok",
  "result": {
    "id": "510b3f7f023fd725b4cd52cc",
    "name": "National Wool Museum",
    "locationStreet1": "26 Moorabool Street",
    "locationTownSuburb": "Geelong",
    "locationState": "Victoria",
    "locationLatitude": "-38.14538",
    "locationLongitude": "144.3612"
  }
}

Notes

Requesting additional collector fields

By default, the only field returned within an collector record result is the collector id.

Additional fields may be requested using the include parameter. You may request multiple fields by using a single include parameter with a list of fields seperated by commas.

https://victoriancollections.net.au/api/v2/collectors?include=field1,field2...

Alternatively, you may add multiple include parameters

https://victoriancollections.net.au/api/v2/collectors?include=field1&include=field2...

To request all fields without needing to specify them individually, use an incude parameter with the field name 'all'.

The fields that can be requested in the include parameter are:

  • all (request all fields)
  • avatar
  • building
  • collectiondescription
  • culturevictoriaid
  • description
  • email
  • key
  • location
  • name
  • phone
  • postal - address
  • sectortype
  • websiteurl
Requesting additional item fields

By default, only a subset of fields are included within collection item record results. These include:

FieldDescription
id the item id
collectorId the id of the collector to which this item belongs
organisationId (deprecated) identical to the collectorId - included for legacy support only
dateModified the date the item record was last modified
itemPageUrl the url of the page for this item on Victorian Collections
thumb the url for the thumbnail for this item on Victorian Collections
registration the registration number for this item

Elements from the Dublin Core Metadata Element Set can be returned in addition to the default fields by adding 'include=dc' to the request arguments:

https://victoriancollections.net.au/api/v2/items?include=dc...

The dublin core fields that are available include:

  • title
  • creator
  • contributors
  • coverage
  • description
  • identifier
  • rights
  • subject
  • language