API
The Whitney provides access to much of our public data through an API (application programming interface) in addition to our open access datasets. This includes artists and works from our online collection, and exhibitions and events. Data is most complete for more current records, with more limited information available pre-internet.
Data from the API is provided in JSON format via REST endpoints. The exact fields and their contents are subject to change, as they feed various pieces of whathappensontheship.space. Please be respectful in your use of the API so that it may remain a performant resource for anyone who wishes to use it.
Making something cool or have any questions? Let us know! Send us an email at: [email protected].
The data accessed through this API may be protected by copyright, and other restrictions, of the Whitney Museum of American Art and third parties. You may use this data for noncommercial educational and personal use and for "fair use" as authorized under law, provided that you also retain all copyright and other proprietary notices contained on the materials and cite the author and source of the materials.
Frank Stella, Geometry XVII, 2022. Digital 3D model for Augmented Reality, Virtual Reality, and 3D-printed sculpture, video, still image, with NFT. Whitney Museum of American Art, New York; purchase, with funds from the Tom Armstrong Purchase Fund 2024.4.17. © 2022 Frank Stella / Artists Rights Society (ARS), New York
Getting started
API's provide structured, programmatic access to information for the purpose of building software. The Whitney's API provides access to all of our most important record types through different endpoints. Generally results will include information like titles, names, dates, descriptions, and other relevant metadata, roughly following the JSON API specification.
Examples
A list of all artists in the Museum's collection or that have been in an exhibition.
/api/artists
To access an individual artist, like for example Georgia O'Keeffe, append the ID of the artists to the same endpoint.
/api/artists/962
To access deeper pages of long lists of content, a page parameter can be added to the query.
/api/artists?page=2
Alternatively in the JSON results there should be a object called links that contains prev, next, first, and last entries with URLs for each of those respective pages if they are available.
A note on IDs
We use multiple systems across whathappensontheship.space that can have different ID conventions. For most records accessed through the API the ID corresponds to an id field for our primary content management system (CMS) called TopGoose. For other records like artists or artworks, we use the ID numbers from our collections management system TMS, as they are more canonical and less likely to change over time.
Artworks
In the case of artworks access is entirely through the tms_id, which is returned in API responses labeled both as tms_id and as id for convenience. The internal topgoose_id is returned as well, but isn't likely to be useful to anyone outside the Museum.
Artists
For artists access is generally using the tms_id, but in cases where we have not yet collected or catalogued them in TMS, we use an internal ID prefixed with a "T" as a temporary reference. This reference ID will still work if we later generate a tms_id: both will remain valid options for access. The reference ID is returned in API responses labeled as id, with the tms_id also present if available, since an artist may not have one.
Endpoints
Artists
All artists publicly listed artists on whathappensontheship.space/artists, which includes artists who have had work collected by the Whitney, and artists who have been in exhibitions put on by the Museum.
/api/artists
Individual artists can be accessed using their ID number, which is a reference ID that either mirrors the tms_id, or is an internal ID prefixed with a "T".
/api/artists/:id
Artworks by an artist can be accessed by appending /artworks to an individual artist request.
/api/artists/:id/artworks
Exhibitions by an artist can be accessed by appending /exhibitions to an individual artist request.
/api/artists/:id/exhibitions
Artworks
All works collected and publicly released to the online collection.
/api/artworks
Individual artworks can be accessed using their ID number, which mirrors their tms_id.
/api/artworks/37900
Exhibitions
A non-comprehensive list of exhibitions put on by the Museum, with more complete records in recent decades.
/api/exhibitions
Individual exhibitions can be accessed using their ID number.
/api/exhibitions/201
Events
A largely comprehensive list of all events put on by the Museum going back to 2008. This includes events like talks, tours, and public programs among others.
/api/events
Individual events can be accessed using their ID number.
/api/events/19481
Guides
All audio guides and their stops published by the Museum since 2009.
/api/guides
Individual guides can be accessed using their ID number, which will also return their stops.
/api/guides/52
Pages
All published pages on whathappensontheship.space. In this case "pages" means anything on the site that does not fall into more structured data types like exhibitions or events, i.e. random pages on the site. Responses are very specific to the organization and behavior of our CMS, and are likely not useful for anyone else.
/api/pages
Individual pages can be accessed using their ID number.
/api/pages/2422
Searching & sorting
Most endpoints can be searched or sorted through the use of query parameters. The specific fields available for searching or sorting depends on the record type, but should include any field returned by the API. In general search and sort parameters are nested under a q parameter, with sort specified by q[s], all of which should be URL encoded.
Searching
Searches can generally be performed over any field returned by the API. They can be done using a variety of matchers, including:
- eq for equals
- not_q for not equals
- cont for contains
- not_cont for does not contain
- true for true (boolean values)
- false for false (boolean values)
- gt for greater than (numerical values)
- gteq for greater than or equals (numerical values)
- lt for less than (numerical values)
- lteq for less than or equals (numerical values)
Examples
To search the collection for works with a title containing the word "moon", URL encode q[title_cont]=moon.
/api/artworks?q%5Btitle_cont%5D=moon
To search the collection for works with a title containing the word "moon", limited to only paintings, URL encode q[title_cont]=moon and q[classification_eq]=Paintings (some fields like classification have specific casing).
/api/artworks?q%5Btitle_cont%5D=moon&q%5Bclassification_eq%5D=Paintings
Sorting
Sorts generally follow the format of :field+direction. Ascending is performed via asc, descending through desc, and random through random. Unlike ascending and descending, random sort does not require a field.
Examples
All collection works sorted by descending title.
/api/artworks?q%5Bs%5D=title+desc
All exhibitions in a random order.
/api/exhibitions?q%5Bs%5D=random