API Documentation

Getty Museum Collection
Records about artworks in the Getty Museum, past and present
This Museum Collection API provides access to the metadata about the more than 250,000 objects within the Getty Museum Collection as well as objects that have been deaccessioned from the collection. It also contains information about the people, groups, places, events, and other supplementary information that you'd need to know in order to make sense of those records.
Last updated: 2022-03-21
See revision history

This API Documentation is a work in progress.

With some exceptions, the data available from this API is made available under CC0. Check the Usage Guidelines section of this document for more details.

Quick Reference

This API is based on the Linked.Art standard, and uses ActivityStreams to track changes and IIIF to provide images. We also provide a SPARQL endpoint to allow for graph queries.

Getting Started

This API is currently designed to accommodate three tasks: getting records, tracking changes in records, and asking questions about the collection as a whole.

We currently don't provide a way to get a list of all of the objects or other entity types in the dataset. We know how useful this would be, and it's on our roadmap. We also don't provide a way to download all the data in the dataset; this is also on the roadmap. Stay tuned.

Getting Records and Images

The first task is to access information about the records Getty has published, which are separated into types or "entities" in our dataset.

Records

The most obvious record type is for Object entities, usually artwork like Van Gogh's Irises. However, Vincent van Gogh himself is a Person entity, and the gallery we display Irises in is a Place entity. Each entity within our dataset has a URL where you can access the record as a JSON document, and the JSON contains links to other entities across our dataset.

For example:

You can learn more about the model we use on the Linked.Art website.

Images

The other kinds of records we provide are images of the artwork. We provide these via our Getty-wide IIIF API – a standard used across cultural heritage for accessing pictures. There are two APIs available for images – one, the IIIF Image API, lets you access to JPEGs of the images at different resolutions. The other, the IIIF Presentation API, lets you access to all the images associated with an Object, presented with some contextual information, provided as a JSON document known as a IIIF Manifest.

You can get access to these IIIF API URLs from each Object entity record — assuming we have images for that artwork! (Warning! There may be restrictions on what you can do with these images – see Usage Guidelines below.)

For example:

For more information about what IIIF can do, check out the API documentation on the IIIF website:

Tracking Changes

The second task is to be able to know when changes happen in records. What we've found is that many users cache our records and want the latest data — but they don't want to re-download the entire dataset looking for changes — particularly since our records don't change that often!

Instead of forcing users to do that, we use the ActivityStreams protocol to publish an API that lists every record that's been created, edited, or deleted in date order. This standard emerged from social media — think of it as a timeline. Each activity has information about what happened, who did it, when they did it, and what they did it to. It's like a post every time a record changed! For the Museum Collection, this feed is available at:

https://data.getty.edu/museum/collection/activity-stream

The API provides a list of pages of activities — you can access the first page at https://data.getty.edu/museum/collection/activity-stream/page/1, which are the very first changes made to the API. You could also access page 11000, recording some of the changes that happened in March 2021.

Each page lists activities — for example, this activity records a change to our record for LACMA, showing that it was updated on March 1st, 2021.

You can use the ActivityStream to get a list of every record we have in our system, by starting at the first page and crawling forward, keeping track of everything that's been created and deleted. If you already have a copy of our data, though, you can start at the last page and crawl backwards, only pulling the records that have changed since the last time you scanned!

Asking Questions

You might not want to look up a single record, or even pay attention to the entire dataset. Instead, you may have questions like "how many paintings are wider than 1 meter?" or "what artwork has been exhibited the most times?" or "who's the most common artist in Getty's Collection?". There are so many interesting questions that we can't provide API endpoints that cover all of them. Instead, we provide a tool that lets you ask the API yourself.

Under the hood, our API is actually a knowledge graph that uses Linked Data standards JSON-LD and RDF. If you just want to use the API, you don't need to know that at all — just think of them as REST APIs that provide slightly unusual JSON.

However, if you're interested in taking advantage of those technologies and the graph-y nature of the data, you can use the SPARQL query language to write custom queries against our public SPARQL endpoint for the Museum Collection.

It's available at https://data.getty.edu/museum/collection/sparql, and we provide a web-based interface for it at https://data.getty.edu/museum/collection/sparql-ui.

SPARQL can be deep magic — it's incredibly powerful, but because of that power it takes an investment of time to understand how best to use it.

Usage Guidelines

We are providing this data without restrictions for all to enjoy. We've got a few guidelines, but we've worked hard to make this dataset as open and explorable as possible.

Licensing

This dataset is available under CC0: you can use this data however you like without asking for permission, save for the two exceptions described below.

You also do not need to credit us in any way, although we'd love it if you did — we've provided a preferred credit below. We would also love to hear about how you've used the dataset — send us an email!

Exception #1: Images

The API provides links to images via Getty's IIIF API, but does not provide the images themselves.

Images are not always available under the same terms as the dataset.

Many of the linked images are part of Getty's Open Content program and can also be used without permission from us under CCO — but not all of the images are. For each image reference, we've included a metadata block that looks like this:

// This JSON has been truncated to remove irrelevant bits

{
  "id": "https://data.getty.edu/media/image/561a6437-3960-5238-87de-5d50d9fc6fb1",
  "type": "VisualItem",
  "subject_to": [
    {
      "type": "Right",
      "classified_as": [
        {
          // This is the important bit
          "id": "https://creativecommons.org/publicdomain/zero/1.0/"
        }
      ]
    }
  ]
}

If the value at subject_to[0].classified_as[0].id is "https://creativecommons.org/publicdomain/zero/1.0/", then you're free to use the image without Getty's permission. If the value is anything else, the image is under copyright or some other restrictions apply, and different terms and conditions apply that affect how you can use the image.

Please contact rights@getty.edu if you would like to license images of artworks that are not available under Open Content.

Exception #2: Written Descriptions

The API also provides object descriptions and artist biographies. While Getty has rights to some of these, others are under third-party copyright, and we can't authorize their reuse by others.

Within an object record, you can find the rights within a subject_to block contained within each description:

// This JSON has been truncated to remove irrelevant bits

{
  "type": "HumanMadeObject",
  "id": "https://data.getty.edu/museum/collection/object/3a7dbc98-cfda-49b9-a744-9042eefda3b3",
  "referred_to_by": [
    {
      "type": "LinguisticObject",
      "content": "Working from a live model, Raphael Sanzio...",
      "subject_to": [
        {
          "type": "Right",
          "classified_as": [
            {
              "type": "Type",

              // This is the important bit!
              "id": "https://creativecommons.org/licenses/by/4.0/"
            }
          ]
        }
      ]
    }
  ]
}

Similarly, within people or groups, the biographies look like this

// This JSON has been truncated to remove irrelevant bits
{
  "type": "Person",
  "id": "https://data.getty.edu/museum/collection/person/c3a876a9-5333-40d5-8488-6cc722058f5e",
  "referred_to_by": [
    {
      "type": "LinguisticObject",
      "content": "...Art was Van Gogh's means of personal, spiritual redemption...",
      "subject_to": [
        {
          "type": "Right",
          "classified_as": [
            {
              // This is the important bit!
              "id": "https://creativecommons.org/licenses/by/4.0/"
            }
          ]
        }
      ]
    }
  ]
}

The machine-readable version of the rights information for both is at the JSON path

referred_to_by[0].subject_to[0].classified_as[0].id

If the value is https://creativecommons.org/publicdomain/zero/1.0/, then you're free to use the text however you'd like. If it is https://creativecommons.org/licenses/by/4.0/, you can use the text as you'd like with appropriate attribution. If the value is anything else, there are restrictions on how you can use this text, and you should refer to the linked license for more clarity.

Attribution

We respectfully ask that you acknowledge Getty as a source wherever possible, especially with respect to research or publication, in order to preserve a link to the dataset. By providing acknowledgment or citation, you enable others to verify, replicate, and further explore your presentation and interpretation of our data.

And it’s just nice.

Our preferred attribution is:

Courtesy of the J. Paul Getty Museum, Los Angeles

In addition, most of our written texts are licensed under CC BY, which means that you'll need to correctly attribute the text if you use it. We've included specific attribution content for each text within the data:

// This JSON has been truncated to remove irrelevant bits

{
  "id": "https://data.getty.edu/museum/collection/person/c3a876a9-5333-40d5-8488-6cc722058f5e",
  "type": "Person",
  "referred_to_by": [
    {
      "type": "LinguisticObject",
      "content": "...Art was Van Gogh's means of personal, spiritual redemption...",
      "subject_to": [
        {
          "type": "Right",
          "subject_of": [
            {
              "type": "LinguisticObject",

              // There may be more than one text attached—the one you'd want
              // is the one classified using this AAT term.
              "classified_as": [
                {
                  "id": "http://vocab.getty.edu/aat/300026687",
                  "type": "Type",
                  "_label": "Acknowledgements"
                }
              ],

              // This is the preferred attribution text
              "content": "Text provided by the J. Paul Getty Museum. Licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0)"
            }
          ]
        }
      ]
    }
  ]
}

Dataset Integrity

Collections data is provided for the purposes of exploration, education, experimentation, and fun, but it is provided “as is” and is to be used at your own risk. Getty makes no representations or warranties of any kind.

Please be aware that the API contains incomplete data and/or errors. Getty staff does not guarantee or provide curatorial approval for these records. At Getty, research is always ongoing, and so our understanding of these objects and their metadata are subject to change. This API is updated on a regular basis to reflect our current best understanding of the object. You are advised to regularly update your copy of the datasets to ensure you are using the best available information.

If you have identified errors in the dataset, or have additional information to add, we welcome your feedback! Please contact us at MuseumCollections@getty.edu.

No Endorsement/Representation

Do not mislead others or misrepresent the datasets or their source. Use of this dataset does not grant or imply Getty's approval, commission, or support of your work, and you may not use Getty’s trademarks or otherwise claim or imply that Getty or any other third party endorses you or your use of the dataset. Getty retains the rights to all of its trademarks, and they are not part of the dataset. If you transform or modify to the dataset, you must clearly distinguish the resulting work as having been modified from the Getty dataset. If you create a derivative dataset from the Getty dataset, we ask that you consider releasing the derivative under a CC0 license, which mirrors the licensing of the Getty dataset.

Questions?

Please contact us if you have any questions.

Go explore the data!