Home

Awesome

Harvard Art Museums API Documentation

The Harvard Art Museums API is a REST-style service designed for developers who wish to explore and integrate the museums’ collections in their projects. The API provides direct access to the data that powers the museums' website and many other aspects of the museums.

Access to the API

All requests to the API begin with:

https://api.harvardartmuseums.org

And all requests must also specify the resource you want to retrieve:

https://api.harvardartmuseums.org/RESOURCE_TYPE

And every request must be accompanied by the apikey parameter and an API key. The API uses keys to authenticate requests. API keys take the form 00000000-0000-0000-0000-000000000000. Here is the full structure of a typical request:

https://api.harvardartmuseums.org/RESOURCE_TYPE?apikey=YOUR_API_KEY

Send a request to obtain your key.

Responses and data format

All data is in JSON format. Here is a typical response:

{
    "info": {
        "totalrecordsperquery": 10,
        "totalrecords": 224111,
        "pages": 22412,
        "page": 1,
        "next": "",
        "prev": "",
        "responsetime": "5 ms"
    },
    "records": [

    ],
    "aggregations": {

    }
}

Paging through data

Requests that return large numbers of records will be spread across multiple pages. By default, a request returns 10 records per page. You can increase this number (up to 100) by adding the size parameter to a request. For example add &size=100 to get 100 records per page. To move through a large record set, add the page parameter and set it some value greater than 1 (i.e. &page=2).

https://api.harvardartmuseums.org/object?size=5&page=42

The next and prev fields in the info block provide a handy shortcut for paging forward and backward through records. They will contain a fully formed URL to the next and previous pages of records. Send a new request to the value in the next field to move forward. Check for the existance of the next and prev fields to determine if you are at the beginning or end of your results.

Errors

Requests that contain a bad, invalid, or missing API key will return a 401 Unauthorized error. Remember every request requires the apikey parameter with a valid key. See the very top of this document for more information about keys. Requests for resources other than those listed in the resources section below will return a 404 Not Found error.

Images

Some of the datasets include image URLs as part of a block of image information in each record. Our images are served to you by an image server that supports a number of interfaces including IIIF.

Default service

The default service is accessed through the URLs found in the fields baseimageurl and primaryimageurl. This service is capable of resizing images on the fly. Append height and width parameters to image URLs to get an image sized to fit to the supplied dimensions. For example, if you want an image scaled to 150 pixels on the longest side construct the URL as follows.

https://nrs.harvard.edu/urn-3:HUAM:OCP16703_dynmc?height=150&width=150

IIIF

Some of the museums' data is accessible through IIIF image and presentation services.

The IIIF image service is accessed through the data found in the field iiifbaseuri. Read more about the capabilities of the IIIF Image API at http://iiif.io/api/image/2.1/. The service we provide adheres to version 2.1 of the API. A typical base URI for an image looks like this:

https://ids.lib.harvard.edu/ids/iiif/18483392

A fully formed IIIF request for a full resolution JPEG version of that same image looks like this:

https://ids.lib.harvard.edu/ids/iiif/18483392/full/full/0/default.jpg

Please note that URLs for images of objects that have rights restrictions are excluded for most API users. This means images for many 20th and 21st century works of art will not be available to you at the present time. We are working on a solution to this.

The IIIF presentation service is accessed through a separate service. Read more about the capabilities of the IIIF Presentation API at http://iiif.io/api/presentation/2.1/.

The top level collection is at:

https://iiif.harvardartmuseums.org/collections/top

The base URL for all presentation manifests begins with:

https://iiif.harvardartmuseums.org/manifests

You can request a manifest for any object by appending /object/OBJECT_ID to the base URL. For example the primary manifest for the object Self-Portrait Dedicated to Paul Gauguin is at:

https://iiif.harvardartmuseums.org/manifests/object/299843

At the present a manifest for an object contains one sequence and each image of that object is contained in its own canvas within that sequence.

Please note that our IIIF presentation service is very much a work in progress. The code for the server is available at https://github.com/harvardartmuseums/iiif-manifest-server and is based on work that was done at HarvardX. If you have any comments, suggestions, or questions about this service feel free to submit them through the feedback links listed below.

More technical documentation and use cases are described in the IIIF section.

Analysis

Slice and dice the data any way you like at our expense with the aggregation parameter. You can ask for aggregations on every resource. They are the best way to gather statistics and analyze the data. The aggregration parameter accepts the structure and syntax of Elasticsearch aggregations. Output from aggregations will appear as an additional block of data in the response. Learn more about analyizing the data via examples in the analysis section of the API documentation.

Resources that are available

Several primary museum resources are accessible in this API. They include the following:

Experimental data

There is a small amount of experimental data available at this endpoint.

Learning the API

Introduction to APIs

New to APIs? New to museum data? New to coding? Try out our beginners guide to APIs and museum data.

Example projects

You can do a lot with the API. Here are a few examples.

Art Explorer
A different approach to browsing through the collections.

Suns Explorer
A simple abstract use of the color information supplied with some of the object records.

Art Forest
A simple "game" that is part classic text adventure, point-and-click adventure, and walking simulator.

Spectrum Explorer
See color spectrum that is part of the branding of the Harvard Art Museums.

Museum Explorer
See the entire museum through tree and pack graphs and floor plans.

AI Explorer
Search and browse the collection via machine generated tags and descriptions.

ARTphone
Call or text the word "random" to 1-617-500-1866 to listen to the collection.

Magnetic Poetry, Magic Message, Face Match, etc
Playful projects that show the possibilities with computer vision and IIIF.

Example code snippets

You can talk with the API using almost any language or tool that speaks HTTP. Here are a few snippets to get you started. Just make sure to substitute your own API key in the apikey parameter before running them.

cURL

Find all of the objects in the collection.

curl -XGET https://api.harvardartmuseums.org/object?apikey=[YOUR APIKEY HERE]

Javascript + jQuery

// Find all of the objects that are paintings and have the word "rabbit" in the title
var apiEndpointBaseURL = "https://api.harvardartmuseums.org/object";
var queryString = $.param({
    apikey: "YOUR APIKEY HERE",
    title: "rabbit",
    classification: "Paintings"
});

$.getJSON(apiEndpointBaseURL + "?" + queryString, function(data) {
   console.log(data); 
});

Node.js

var rest = require("restler");

// Find all of the objects with the word "dog" in the title and return only a few fields per record
rest.get("https://api.harvardartmuseums.org/object", {
    query: {
        apikey: "YOUR APIKEY HERE",
        title: "dog",
        fields: "objectnumber,title,dated",
    }
}).on("complete", function(data, response) {
    console.log(data);
});

PHP

use GuzzleHttp\Client;

$client = new Client();
// Find all of the objects with the word "squirrel" in the title and return only a few fields per record
$response = $client->get("https://api.harvardartmuseums.org/object", 
    [
        "query" => [
            "apikey" => "YOUR APIKEY HERE",
            "title" => "squirrel",
            "fields" => "objectnumber,title,dated"
        ]
    ]
);
$records = json_decode($response->getBody());
print_r($records);

Python 3

import urllib3

http = urllib3.PoolManager()

# Find all of the objects with the word "cat" in the title and return only a few fields per record
r = http.request('GET', 'https://api.harvardartmuseums.org/object',
    fields = {
        'apikey': 'YOUR APIKEY HERE',
        'title': 'cat',
        'fields': 'objectnumber,title,dated'
    })

print(r.status, r.data)

Feedback

Have you tried the API? Let us know what you think.

If you have a specific feature request or find a bug, please open a GitHub issue.

About the API

Background information

There are many reasons why the API is important to us and why it exists. They can be summed up as this: Data is at the heart of the work we do and we need an efficient and stable system for tapping in to it.

A more expansive list of reasons why we have an API goes like this:

Several articles have been published on our magazine about how access to data (through APIs) changes the way we think about and use collections. See Technology in the Museums and The Beauty—and Complexity—of Data to dive a bit deeper.

Technical specs

The two core pieces of software behind the API are Node.js and Elasticsearch. The API is a Node.js application running on Heroku. It talks to an Elasticsearch instance running on Elasitc Cloud.

The data

The bulk of the data derives from our internal collections management systems. Our primary system is The Museum System (TMS) by Gallery Systems. We enhance the data in TMS by using third party services to aggregate statistics and run machine processing. These services include Google Analytics, Google Vision, Amazon Rekognition, Microsoft Cognitive Services, Clarifai, and Imagga.

We refresh the dataset every day around 6am.

Keep in mind that the data is not perfect. There are many gaps and a lot of ambiguity. The data is a direct manifestation of the knowledge produced by staff and affiliates of the museums. The majority of the data is produced by humans, thus subject to errors, opinion, and fuzziness. Consider it a living document and work in progress. Check back often.

Terms of use

<br/> <br/>
<br/>

Coda

Congratulations! You made it to the end. Over the years the museums' design team made stickers for us to give away as a means to spread joy and promote the API. Please enjoy this sampler.

A collage of nine hexagons each containing a part of an image from the museum's collection