Victoria and Albert Museum API Documentation

Update May 2016 - This API is currently under review as part of our planned work on improving Search the Collections. If you currently make use of the API, and have any comments, queries or suggestions about it, please contact   r . p a l m e r @ vam.ac.uk

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

If you make a request to this service you are deemed to have accepted the terms and conditions.

Principles and Getting Started

The API Query Builder

Try building your own API calls with this rudimentary HTML GUI. Then, take those URLS away and do something nice with them or come back and read the rest of the documentation.

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

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 in HTML form.

Formats

After /api, the first part of the URL indicates the format in which you would like your response

JSON

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

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

XML

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

Returns all items in the database (paginated) in XML format. Note this is not yet as fully implemented as JSON but could be useful if your app prefers to consume XML. The JSON contains more of the related information concerning objects.

JSONP

To make it easier to do client-side mash-ups using V&A data, we offer all our JSON responses with a JSONP wrapper function. Simply pass the desired name of a callback function you wish to use on the client side in the callback parameter. Only A-z, 0-9 and underscore characters are allowed in your function name. 

http://www.vam.ac.uk/api/json/museumobject/?callback=my_callback1&q=medieval&materialsearch=gold&images=1

You can play with the JSONP functionality using our API Query Builder at http://www.vam.ac.uk/api/qb. This gives you a rudimentary GUI to help you create useful API calls for your own work. If you are interested in JSONP, you can save the HTML of the API Query Builder locally to play with the source. It is all encapsulated in that one file.

Another way to get started with JSONP is to follow the example below…

jQuery JSONP example

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.5.1/jquery.min.js"></script>
<script type="text/javascript">
/*
Clever stuff goes here
*/
function renderResults(jsonp_data) {	
    /* Do something with the JSON objects */
}

/*
Execute the XHR request and call success function
*/
function executeApiQuery(search_parameters) {
	options = {
	  type: 'GET',
	  dataType: 'jsonp',
	  data: search_parameters,
	  success: function(data){ 
		  renderResults(data);
	  },
	  failure: function(data){}
	};
	$('#submit').hide();
	$.ajax('http://www.vam.ac.uk/api/json/museumobject/', options);
}

/*
 Make AJAX JSONP request when page ready
*/
$(document).ready(function(){
	search_parameters = {
	  q: 'medieval', 
	  materialsearch:'gold',
	  images: 1
	}
	executeApiQuery(search_parameters);
})
</script>

Using the API in anger

General Keyword Searching

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

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/museumobject/search?q=wooden+door

Keyword searches in specific fields

You can filter your museum object search results by type, people, places. materials, techniques and categories

Object Type and Title

To find necklaces:

http://www.vam.ac.uk/api/json/museumobject/search?objectnamesearch=necklace

Or The Hay Wain

http://www.vam.ac.uk/api/json/museumobject/search?objectnamesearch=hay+wain

People and Places

Search on a specific artist or maker:

http://www.vam.ac.uk/api/json/museumobject/search?namesearch=josiah+wedgwood

Or items from Stockon

http://www.vam.ac.uk/api/json/museumobject/search?placesearch=stockton

Materials and techniques

Crucial to a museum of applied arts, you too can search on this information. Look for items that are glazes:

http://www.vam.ac.uk/api/json/museumobject/search?materialsearch=glazing

Or items made with ivory

http://www.vam.ac.uk/api/json/museumobject/search?materialsearch=ivory

Pagination

To reduce load on server, each response contains 15 results by default. You can increase the "size" of the "page" up to a maximum 45 by passing the limit parameter.

http://www.vam.ac.uk/api/json/museumobject/search?materialsearch=ivory&limit=30

You can then get the next set of results using the offset parameter, just as you would use it in SQL.

http://www.vam.ac.uk/api/json/museumobject/search?materialsearch=ivory&limit=30&offset=30

Dates and other delights

Why not bring back recent objects?

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

Or before 1000BC? Note the signed integer indicating a date BCE.

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&placesearch=greece&materialsearch=silver

A selection of random* objects associated with wine!

http://www.vam.ac.uk/api/json/museumobject/search?q=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?q=nude&images=1

Only records with a detailed description

http://www.vam.ac.uk/api/json/museumobject/search?q=nude&pad=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, categories, styles and periods, materials and techniques. In short, everything we know about the object usefully split up into separate fields.

Geo: Finding Places

The V&A Collections database contains geographical info. These places could be depicted in a painting or could be the place where an object was made. The places had some hierarchical information but no precise co-ordinates. We have taken the place texts and geocoded them using web services and the results are generally useful but… there may be anomalies!

You can search for objects from or near a given place (i) or search for places directly (ii)

i. Geospatial search for objects

You can set an anchor point using latitude and longitude to search around, then set a radius within which you wish to search

This returns objects we have successfully geocoded within a 50km radius of Bruges

http://www.vam.ac.uk/api/json/museumobject/search?latitude=51.208013&longitude=3.227105&radius=50

You can order your results in ascending order of distance from the anchor point

http://www.vam.ac.uk/api/json/museumobject/search?latitude=51.208013&longitude=3.227105&radius=50&orderby=distance

ii. Finding places directly

You can use the same parameters as above to more precisely find places (as opposed to a list of objects related to places). Later, you can grab objects from that specific place.

Find places with the word "mount" in them

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

Find places within a 50 mile radius of Leeds, UK (latitude, longitude taken from Leeds on Wikipedia.)

http://www.vam.ac.uk/api/json/place/search?latitude=53.799722&longitude=-1.549167&radius=50&orderby=distance

These results start with the nearest and move further away from the co-ords you supply

Great! I've found a place. Now what?

Simply pass the pk (that's the primary key) of the place to the museumobject resource URL using the place parameter. I've chosen Adel from the results above:

    {
        "pk": 2386, 
        "model": "collection.place", 
        "fields": {
            "updated": "2010-02-01 15:47:35", 
            "description": " West Yorkshire", 
            "parent": 536, 
            "country": "England", 
            "museumobject_count": 3, 
            "longitude": "-1.58787000", 
            "source": "cis_place", 
            "cis_id": "x34399", 
            "latitude": "53.84780100", 
            "type": "inhabited place", 
            "slug": "adel-england-x34399", 
            "name": "Adel"
        }
    },

Here the pk is 2386 and judging by the museumobject_count property, I can expect 3 results from the museumobject resource for this place.

Here's the URL fully constructed:

http://www.vam.ac.uk/api/json/museumobject/search?place=2386

Lo and behold, there are three photos of Adel to enjoy

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

Many high-resolution images are available to download for free at http://collections.vam.ac.uk/

Constructing URLS to images

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

    {
        "pk": 7052, 
        "model": "collection.museumobject", 
        "fields": {
            ...
            "primary_image_id": "2007BL8769", 
        }, 
        ...

Collection object images are served from this location.

http://media.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://media.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://media.vam.ac.uk/media/thira/collection_images/2007BL/2007BL8769.jpg

Images Sizes

We have also pre-processed the following image sizes:

Please note that due to the extra-ordinary bulk import of these images, some may not be available. A standard 404 will be returned in these cases.