RISD Museum Collection API

By Jeremy Radtke

01.15.2020

Research informs how we acquire works of art, care for the collection, and develop exhibitions. Research helps generate new knowledge and expertise, enhances access, and provides artists and our community with opportunities for sustained collaboration.

Established in 1877, the RISD Museum is part of a vibrant creative community. We interpret our collection with a focus on the maker, deeply engaging with art and artists and presenting ideas and perspectives that can be inspiring and complex. Collaboration with artists, students, and faculty at RISD, Brown, and other area colleges and universities is fundamental to how we research and interpret art and design.

The RISD Museum collection application program interface (API) lays out how our website’s search function operates, aiding discovery of the museum’s collection and allowing collection data to be used in innovative ways.

Overview

The API is free and open to use by anyone—no API key is required and no rate limiting is applied at this time. However, abuse or excessive calls to the API may result in IP-based blocking at the discretion of the museum. Data is delivered via JSON—or JavaScript object notation—payloads.

The API currently consists of one main endpoint for retrieving collection object data, https://risdmuseum.org/api/v1/collection, which returns an array of JSON objects, each corresponding to a collection object that matches the provided query.

This route accepts a number of query parameters to further filter the set of results. Items are limited to up to 25 per page, and successive pages may be accessed to obtain the full set of results.

PARAMETER NAME	ACCEPTED VALUES	DESCRIPTION
search_api_fulltext	any	Filter the results by the provided search term. Objects are matched only if they contain EVERY word supplied by this parameter. Any words that appear publicly on an object’s record will be matched, including title, maker, accession number, etc.
field_on_view	0/1	Filter the results by whether the objects are currently on view at the museum. 0 = objects ARE NOT on view, 1 = objects ARE on view, omission of this parameter returns all objects regardless of “on view” status.
field_public_domain	0/1	Filter the results by whether the objects are considered to be in the public domain. If an object is in the public domain, the images are considered downloadable and their use is unrestricted. If an object is NOT considered public domain, please contact the museum for information on using images from that object. 0 = objects ARE NOT public domain, 1 = objects ARE public domain, omission of this parameter returns all objects regardless of “public domain” status.
has_images	0/1	Filter the results by whether the objects have images available online. 0 = objects DO NOT have images, 1 = objects DO have images, omission of this parameter returns all objects regardless of whether they have images.
field_recent_acquisition	0/1	Filter the results by whether the objects are recent acquisitions (acquired within the last 5 years). 0 = objects ARE NOT recently acquired, 1 = objects ARE recently acquired, omission of this parameter returns all objects regardless of when they were acquired.
id	integer	Return only the object matching the given ID. This ID pertains only to the object’s “web ID” (the ID assigned to it for the purposes of the online catalog) and will not match other object identifiers such as its accession or reference number. This ID is exposed in the collection object’s JSON object returned by the API. This is particularly useful for querying information about an object’s related objects, if specified.
page	integer	Return the subset of results corresponding to the given page number. By default, results are provided 25 at a time. Page numbering starts at 0, so the first page of results is page 0, second page of results is page 1, etc.
items_per_page	5/10/15/20/25	Alter the number of results returned per page. Only the listed values are valid options.

In general, the same query parameters are used for the public collection search page at https://risdmuseum.org/art-design/collection. As such, you can test queries via this search before copying the query parameters over to the API endpoint.

Examples

Returns objects matching the term “picasso” in groups of 5: https://risdmuseum.org/api/v1/collection?search_api_fulltext=picasso&items_per_page=5
Return the second page of results for objects matching the term “warhol” and having images: https://risdmuseum.org/api/v1/collection?search_api_fulltext=warhol&page=1&has_images=1
Return results for objects matching the term “warhol” and having NO images: https://risdmuseum.org/api/v1/collection?search_api_fulltext=warhol&page=1&has_images=0
Match an object with a web ID of “34”: https://risdmuseum.org/api/v1/collection?id=340

Returned Properties

The API always returns a top-level array in its JSON response, which contains zero or more JSON objects. The following are properties returned by these JSON objects. If no data exists for that property of that object, the property value may either be an empty string or NULL. If the property type ends in “[]”, the property is presented as an array and may contain multiple values.

Collection Object JSON Objects

The main type of data returned are collection objects, which may have the following top-level properties:

PROPERTY	TYPE	DESCRIPTION
id	string	“web ID” of the object, used for accessing this object from the API
collection	string
credit	string	credit for the object
culture	string	associated culture of the object
dating	string	description of when the object was made
datingYearFrom	string	earliest estimated year object may be from (negative values correspond to BCE)
datingYearTo	string	latest estimated year object may be from (negative values correspond to BCE)
description	string	description of the object
dimensions	string	dimensions of the object
edition	string	edition of the object
images	string[]	URLs corresponding to images of the object
inscription	string	inscription or markings on the object
makers	object[]	maker objects corresponding to entities involved in the creation of the object (see Makers below for the possible properties returned)
medium	string[]	mediums which the object is created from
mediumTechnique	string	description of the mediums, techniques, and/or materials used in the creation of the object
objectNumber	string	object / accession number of the object
onView	boolean	whether the object is currently on view at the museum
place	string	description of places involved in the creation of the object
primaryMaker	string	short description of the primary maker
publicDomain	boolean	whether the object is considered to be in the public domain
recentAcquisition	boolean	whether the object was acquired recently (within the past 5 years)
referenceNumber	string	reference number of the object
relatedObjects	string[]	URLs corresponding to the API endpoint to obtain information about each related object
state	string	state of the object
support	string[]	support materials used in the creation of the object
technique	string[]	techniques used in the creation of the object
title	string	title of the object
type	string[]	type classifications of the object
url	string	publicly accessible URL of the object on the museum’s website

Maker JSON Objects

Makers are a sub-object that is only returned via the makers property of collection object objects, and each may contain the following properties:

PROPERTY	TYPE	DESCRIPTION
name	string	name of the person or organization associated with the object
risdAffiliation	string	description of the maker’s affiliation with RISD, if applicable
years	string	description of years associated with the maker
nationality	string[]	nationalities of the maker
nationalityModifiers	string	descriptive modifiers for the provided nationalities, such as if the nationalities are uncertain
role	string	the maker’s role in the creation of the object

Paging

The RISD Museum collection contains more than 100,000 objects, most of which are available online through the API. As such, a result set may contain hundreds or thousands of objects; results therefore are broken out into pages to limit the response size of a single API request. In order to capture the entire set of results, each page must be requested separately.

As described in the Query Parameters section above, paging is controlled via the “page” and “items_per_page” query parameters. For convenience, and to inform you how many pages are included in a results set, paging links are returned in the HTTP “Link” header of the API response.

The Link header may contain the following types of paging links (absence of the given link indicates the corresponding results page does not exist):

LINK TYPE	DESCRIPTION
first	the first page of results in the given set (always page=0)
last	the last page of results in the given set (helpful to determine how many pages of results exist and the approximate number of results)
prev	the previous page of results in the given set (if on the second or greater page)
next	the next page of results in the given set (if not on the last page and there is more than one page of results)

The link header conforms to the following pattern, with multiple links delimited by a comma:

<URL>; rel=＂type＂

For example, a simple search for the term “warhol” may return the following Link header value:

<https://risdmuseum.org/api/v1/collection?search_api_fulltext=warhol&page=1>; rel="next", <https://risdmuseum.org/api/v1/collection?search_api_fulltext=warhol&page=0>; rel="first", <https://risdmuseum.org/api/v1/collection?search_api_fulltext=warhol&page=26>; rel="last"