Museums and the machine-processable web

Victoria and Albert Museum API Docs

This version was saved 6 months ago View current version Page history

Saved by Richard Barrett-Small
on May 21, 2009 at 4:38:16 pm

Victoria & Albert Museum Digital Asset Bridge API Documentation

Welcome to our API. It is designed as a RESTful interface to our collections and what we know about them

Principles and Getting Started

Interface

We strongly believe in the URL as interface. It's nice to be able to read a URL and guess what it might bring back

We also believe the URL is a better interface than a complex SOAP or XML-RPC based system for returning data that is generally available elsewhere.

http://www.vam.ac.uk/api

This page.

Format

The first part of the URL indicates the format in which you would like your response

http://www.vam.ac.uk/api/json/

Returns all items in the database (paginated) in serialised JavaScript format

http://www.vam.ac.uk/api/xml/

Returns all items in the database (paginated) in XML format. Note this is not yet as fully implemented as JSON

Using the API in anger

Pagination

All results can be paginated using the limit and offset GET parameters.

Requests can have a maximum of 50 results per page

http://www.vam.ac.uk/api/json/?limit=25&offset=100

Keyword Searching

Everything the API knows about is searchable by keyword. Simply pass your query string to the search interface in the q GET parameter

http://www.vam.ac.uk/api/json/search?q=wooden+door

Searching for specific items

The emphasis on the API is on bringing back Objects from the museum collection.

Museum Objects

http://www.vam.ac.uk/api/json/museumobject/search?q=iran

But the museum also knows about other things...

People and Institutions

http://www.vam.ac.uk/api/json/name/search?q=wedgwood

Places

http://www.vam.ac.uk/api/json/place/search?q=france

Categories and Subjects

http://www.vam.ac.uk/api/json/category/search?q=death

Filtering Museum Object Searches

You can filter your museum object search results by people, places and categories

http://www.vam.ac.uk/api/json/museumobject/search?category=gold

Multiple categories can be passed to the category parameter.

http://www.vam.ac.uk/api/json/museumobject/search?category=gold+ivory

Add a place filter

http://www.vam.ac.uk/api/json/museumobject/search?category=death&place=belgium

Throw in a name, the format for which is the slug field acquired via a name search

http://www.vam.ac.uk/api/json/museumobject/search?name=brangwyn-frank-sir&category=death&place=belgium

Dates and other delights

Why not bring back recent objects?

http://www.vam.ac.uk/api/json/museumobject/search?after=1990

Or before 1000BC?

http://www.vam.ac.uk/api/json/museumobject/search?before=-1000

Pre-Roman Greek objects made of silver?

http://www.vam.ac.uk/api/json/museumobject/search?before=-150&place=greece&category=silver

A selection of random^* objects associated with wine!

http://www.vam.ac.uk/api/json/museumobject/search?category=wine&random=1

^{*Not really random but a pseudo-random offset of the results. MySQL RAND() is SO slow.}

A selection of nudes, but only those with images available!

http://www.vam.ac.uk/api/json/museumobject/search?qs=nude&images=1

Full record details

If you like the look of something in your results, simply append the object_number from the fields section of the response to the end of the appropriate URL interface more information

http://www.vam.ac.uk/api/json/museumobject/O12345

Yes - that's an 'O' for Oscar.

With a museum object, you'll see all the associated people, places and categories.

Images and Media

We have pre-processed several sizes of images and we make these available at predictable URLs based on the image_id field of image records

Currently, all URLs on the media server are authenticated using the same user and password as the main API. This will be for the duration of our alpha release but we anticipate allowing free access to all web-ready images at this location.

High-resolution images will be delivered via a different.

Constructing URLS to images

By taking this Museum Object result, and identifying the default_image_id value, we can make a URL to retreive the image.

    {
        "pk": 7052, 
        "model": "collection.museumobject", 
        "extras": {
            "default_image_id": "2007BL8769", 
        }, 
        ...

Collection object images are served from this location.

http://www.vam.ac.uk/media/thira/collection_images/

The second part of the URL is constructed from the first 6 characters of the image id.

http://www.vam.ac.uk/media/thira/collection_images/2007BL/

The final part of the URL is the image id with a jpg extension - at its most simple...

http://www.vam.ac.uk/media/thira/collection_images/2007BL/2007BL8769.jpg

Images Sizes

We have also pre-processed the following image sizes, which are based on Flickr sizes.:

75px square crop http://www.vam.ac.uk/media/thira/collection_images/2007BL/2007BL8769_jpg_s.jpg
100px longest axis thumb http://www.vam.ac.uk/media/thira/collection_images/2007BL/2007BL8769_jpg_t.jpg
130px square crop http://www.vam.ac.uk/media/thira/collection_images/2007BL/2007BL8769_jpg_o.jpg
240px longest axis http://www.vam.ac.uk/media/thira/collection_images/2007BL/2007BL8769_jpg_m.jpg
265px square crop http://www.vam.ac.uk/media/thira/collection_images/2007BL/2007BL8769_jpg_w.jpg
355px square crop http://www.vam.ac.uk/media/thira/collection_images/2007BL/2007BL8769_jpg_ds.jpg
355px wide http://www.vam.ac.uk/media/thira/collection_images/2007BL/2007BL8769_jpg_d.jpg
500px longest axis http://www.vam.ac.uk/media/thira/collection_images/2007BL/2007BL8769_jpg_l.jpg
1024px (max) longest axis http://www.vam.ac.uk/media/thira/collection_images/2007BL/2007BL8769_jpg_b.jpg