RISD Museum Collection API

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

 

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"

 

See Also