The Powerhouse Museum Application Programming Interface (API)

draft 0.6 for API v1

[kindly provided by Chris Wong in 2011

Lecturer + Course Coordinator BSc(IT)
School of Computing and Communications
Faculty of  Engineering & IT
University of Technology, Sydney ]


 

Introduction

The Powerhouse Museum API is a REST based query interface which provides a rich interface into the existing Powerhouse museum catalogue.

 

It provides the ability to retrieve item information in JSON, JSONP, YAML and XML formats. You can use the museum's information model to locate, navigate and search for specific items. You can also query it using YQL or via simple search queries

 

API Key

To access the Powerhouse museum API, you will first need to have an account with the powerhouse museum.

First, register an account with the powerhouse museum via the http://api.powerhousemuseum.com/login/ website (This is Powerhouse website -> Collection/Research Tab -> API/Data Access tab)

Secondly, once you have verified your account and logged in, select the "Create a key" menu option.  Once you have created a Key, you can maintain this via the "Manage my Keys" option

 

This key is used to track specific uses of the API and to ensure that the API user (which does NOT include the end-user of the application!)  follows the terms and conditions of the Powehouse museum.

 

Do not share this API key with anyone else – this is your key, and there is a quota and tracking on it.

Using the API

The Powerhouse API is a REST API, essentially you use a structured HTTP URL to retreive or search records from the Powerhouse museum.

 

By default, the only supported HTTP Verb is GET (ie: retrieve or search). This implies that the API is currently read-only, and does not support the HTTP verbs POST, PUT, DELETE etc for updates.

 

URL

The API is accessed via the HTTP protocol at the address:

http://api.powerhousemuseum.com/api/v1/keytype/path?parameters

 

The parameters are as follows:

keytype

The keytype is the object which you are trying to retrieve. Valid keytypes include:

  • item
  • item-name  (NOTE: this is separated with a hyphen not an underscore)
  • theme
  • subject
  • provenance
  • multimedia
  • categories
  • collection

 

path

The path is the virtual REST path used to list or retrieve the specific keytype.

This is of the form:

  1. keytype/format                        retrieves a list of keytype in the format representation. If you omit the format, JSON is returned by default. Any incorrect format will result in JSON.
  2. keytype/nnn/format            retrieves a specific keytype object using the key nnn (which typically is the object's id).
  3. keytype/nnn/subkeytype/format            retrieves a list of subkeytype of a specific keytype object using the key nnn. The subkeytype depends on the type of object being returned, see the specific keytype documentation below for allowable types.
    Again, if the format is omitted, the default return type is JSON.

 

parameters

The parameters vary depending on the query.

Separate each parameter using the & (ampersand) character

The only compulsory parameter is the api_key=xxxxxxx where xxxxxxx is your API key

 

Most searches include the following common modifiers:

start=x

start at item number x (integer, optional, default=0)

limit=x

return x items in list (integer, optional, maximum=100, default=50)

all_fields=1

 return all possible fields, even if empty

fields=field1,field2,...

 return only the selected fields (some like "id" will always be returned)

order_by=field

order results by a chosen field (ascending)

order_by=-field

order results by a chosen field (descending)

order_by=?

make a random selection of results from the entire set, not just those shown by &start=x&limit=y

filter=value

filter the entire result set by the filter(s) chosen

You can search for specific objects by using the following common filters. Note that the available fields to search on varies by object type (see below for valid filters)

 

Common Filters:

field=xxx

Performs a search where the value is included anywhere in that field

field_begins=xxx

Matches for when the term xxx is at the start of the field

field_ends=xxx

 Matches for when the term xxx is at the end of the field

field_lt=xxx

 Does a less than comparison.

field_lte=xxx

 Does a less than or equal to comparison.

field_gt=xxx

 Does a greater than comparison.

field_gte=xxx

 Does a greater than or equal to comparison.

field_in=xxx

 Term may have multiple comma separated values any of which is matched for in field via a 'contains' search.

field_exact=xxx

Field must match term exactly (case sensitive).

field_isblank=1

If term is 1 this filter matches when the field is empty, null or zero.

field_isblank=0

only return results where the field has some content.

Examples:

name_begins=Transport             returns items whose name begins with the string Transport

num_multimedia_gt=0            returns items with more than 0 multimedia records

keytypes & the information model

 

See Figure 1 Relationships between keytypes - below

 

The following list the object types that the Powerhouse museum API supports.

category

The Museum's collection is formally catalogued into a number of different object categories. 

Valid filters:

  • 'num_items', 'name', 'id'

Valid subtypes

  • items            returns the list of items for this category

Examples

  • http://api.powerhousemuseum.com/api/v1/category/xml?api_key=123&limit=100
    • return the first 100 categories
    • Note that the element <total> returns the number of hits, <start> returns the beginning number of hits, <end> returns the last number of hits, and <result> returns the number of hits
  • http://api.powerhousemuseum.com/api/v1/category/xml?api_key=123&name_begins=Transport
    • return all categories whose name begins with Transport
      ie: Transport-Water, Transport-Air, Transport-Land will be returned.
  • http://api.powerhousemuseum.com/api/v1/category/xml?api_key=123&limit=100&start=100&order_by=title
    • return the second group of 100 categories ordered by title
    • Note that the <end>
  • http://api.powerhousemuseum.com/api/v1/category/xml?api_key=123&limit=100&order_by=title
    • return the first 100 categories ordered by title
    •  
  • http://api.powerhousemuseum.com/api/v1/category/56/xml?api_key=123
    • return all category #56
  • http://api.powerhousemuseum.com/api/v1/category/56/items/xml?api_key=123
    • return all items for that category

 

item

An item is the most granular unit of the collection available through the API currently.

In general an Item is the equivalent of the object you see inside a museum showcase.

An Item has a large number of descriptive data fields that explain what it is, why the museum has, as well as where possible who made, used and designed it, where and when.

Not all Items have a full set of data fields.

 

Valid filters & order_by fields:

  • 'width', 'weight_units', 'weight', 'title', 'summary', 'significance_statement', 'registration_number', 'production_notes', 'production_date_latest', 'production_date_earliest', 'num_tags', 'num_subjects', 'num_provenance', 'num_multimedia', 'marks', 'length_units', 'id', 'history_notes', 'height', 'display_location_building', 'display_location', 'diameter', 'description', 'administrative_history', 'acquisition_credit_line'

 

Valid subtypes

  • multimedia            returns a multimedias object for this particular item.
    Note that you can use the <thumbnail><url> element to retrieve the thumbnail image details (IF it exists)

 

Example queries

  • http://api.powerhousemuseum.com/api/v1/item/xml?api_key=123&limit=100&start=0&order_by=id
    • Returns the first 100 items in the catalog, ordered by id
  • http://api.powerhousemuseum.com/api/v1/item/8421/xml?api_key=123
    • Returns the specific item id=8421
  • http://api.powerhousemuseum.com/api/v1/item/xml?api_key=123&limit=100&start=0&order_by=id&num_multimedia_gt=0
    • Returns the first 100 items in the catalog, ordered by id, where the field 'num_multimedia' is greater than 0 ie: any items with a multimedia associated with it
  • http://api.powerhousemuseum.com/api/v1/item/146646/multimedia/xml/?api_key=123
    • returns the list of multimedias associated with this particular item

 

Item-Name

Item Name describes what type of thing the Item is.

Items may have more than one Item Name attached to them. This tends to act as a subcategory when used in conjunction with the category type

Notes: This seems to be a list of keywords only, somewhat like a n:m relationship between the category  and item tables.

There is no direct link – you have to use a search ie:

 

Item.categories["Tranport-Air"]  -> search by name_exact (category) == category[69]

Item.names["Helicopters"] -> search by name_exact (item-name) == item-name[3912]

 

Valid Subtypes

items        Return a list of items for this item-name

Valid filters:

'num_items', 'name', 'id'

Example queries

  • http://api.powerhousemuseum.com/api/v1/item-name/xml?api_key=123
    • dump all item-names
  • http://api.powerhousemuseum.com/api/v1/item-name/1/xml?api_key=123
    • retrieve details about item-name #1

Comments

The website allows you to go:  Category ["Transport-Air"] -> Item-Name ["Helicopters"]-> 13 Items

But there is no direct navigation method to do this via the API.
This means you need to use a search instead of a direct REST call.

 

Example:

  1. Go to the powerhouse museum Browse Collection Categories (http://www.powerhousemuseum.com/collection/database/browsecategories.php )
  2. You get an entire list of Categories displayed.
  3. If you select “Domestic Equipment – Home”, the page then displays a sub-category listing (from “Advertising Cards” to “Yokes”.) These are item-names in the PHM API
  4. Selecting “Robots” gives you 246 matches for the sub-category. Note that the URL is http://www.powerhousemuseum.com/collection/database/search_tags.php?tag=Robots
  5. You can then choose specific items

 

Unfortunately there seems to be no easy way to grab list subcategory list from a given category.  Here is one brute force method:

  1. dump the entire item list for that category , use the following search: category/nn/items/xml?fields=names&limit=100
    (where nn = the category number) to return a subset of the
  2. Unfortunately this only returns the 1st 100 items. You may need to capture more for an accurate listing eg: do the above search, but add  &start=101  then &start=201 … & so on

 

themes

We have created themes about some of the objects in the collection.

These themes group different objects together to illustrate some of the wide variety of topics the Museum's collection encompasses.

The themes can illustrate different subjects, focus on intriguing objects, or tell forgotten stories about objects in our collection.

They may be biographies of people connected with our objects, or provide detailed specialist information.

They can show the relationships between objects in our collection.

Themes are one way of making sense of our vast and varied collection online.

They can provide an entry point to the Museums collection.

New themes are added regularly and existing ones are often updated or further developed.

Related object records are accessible from these themes, and themes are accessible from individual object records.

Valid filters:

  • 'title', 'num_subjects', 'num_multimedia', 'num_items', 'num_children', 'id', 'description'

 

Valid subtypes

  • item            returns the list of items for this category

Examples

  • http://api.powerhousemuseum.com/api/v1/theme/xml?api_key=123&limit=100
    • return all themes
  • http://api.powerhousemuseum.com/api/v1/theme/items/xml?api_key=123&limit=100
    • return all items for that theme

 

multimedia

Multimedia are primarily JPG thumbnails at 160x160 px resolution although may also be video files and PDFs.

These are most commonly 2D photographs of Items from varying perspectives and positions.  

Multimedia can have captions, be attached to Themes or have rights allowing use of a 'medium' image size.

Medium images will always fit within a box 370px wide and 260px high.

Some with no known copyright have been added to the flickr commons and this will have a flickr_id.

There is also a flag to indicate when an image is an old, low resolution black and white image.           

Valid filters:

'mime_format', 'id', 'flickr_id', 'childrens_description', 'caption', 'SMO'

Valid subtypes

  • none

Examples

  • http://api.powerhousemuseum.com/api/v1/multimedia/xml?api_key=123
    • return all multimedia types
  • http://api.powerhousemuseum.com/api/v1/multimedia/1/xml?api_key=123
    • return multimedia #1

Comments

Note: this is a painful anomaly in the design of the powerhouse museum API, this should really have 2 tags:

multimedias which contains multimedia and the multimedia type itself.

 

collection

 

 Collections are clusters of objects given to the Museum by a specific donor as a group.

They often represent the work of a particular person or company such as the Hedda Morrison Photographic Collection or The Tooths and Co Brewery Collection.

Other collections are the result of the personal collecting of a donor, such as the Cavill Silverware Collection,  a donation from Professor Kenneth Cavill of his collection of early 20th century Australian Silverware.           

Valid filters:

  • 'num_items', 'name', 'id'

Valid subtypes

  • items            returns the list of items for this category

Examples

  • http://api.powerhousemuseum.com/api/v1/collection/xml?api_key=123
    • return all collections
  • http://api.powerhousemuseum.com/api/v1/collection/1/items/xml?api_key=123
    • return all items for that collection

 

 

provenance

Provenance is information about the objects origin or use.

Here people, organisations, places and/or dates are linked to Items by certain roles.

These roles include things such as designer, owner, maker, user, artist, publisher, archive creator, photographer, author, printer.

Valid filters:

  • 'role', 'place', 'name', 'date_range', 'date_latest', 'date_earliest'

Comments

Note that this seems to be a n:m relationship table only – the contents about the provenance is actually stored in the item itself. So this is just repeated information and you don't usually need to use this object type.

 

subject

Subjects are non-hierarchical keywords which can be associated to Items or Themes.

These Subjects are added by staff when Items are catalogued and describe what the object is about.

They are not the same as Tags. An example of a subject is Australian history, or Aviation ephemera.

Valid filters:

  • 'num_themes', 'num_items', 'name', 'id'

Valid subtypes

  • Items            returns the list of items for this category
  • themes             returns list of themes linked to this category

Examples

  • http://api.powerhousemuseum.com/api/v1/subject/xml?api_key=123
    • return all subjects
  • http://api.powerhousemuseum.com/api/v1/subject/1/items/xml?api_key=123
    • return all items for that subject
  • http://api.powerhousemuseum.com/api/v1/subject/1/themes/xml?api_key=123
    • return all themes for that subject

 

Right click on the above a chose 'view image in new window' to see it full size.