Data & APIs
Introduction
The Paul Mellon Centre’s Photo Archive APIs provide a REST-style service that allows developers to explore and integrate our public data into their projects. This API is the same tool that powers our website, and is used to distribute our data and images to aggregate services.
Requests
All requests follow the HTTP protocol with the following values and are stateless in terms of the REST concept:
- Headers
HTTP header fields - Arguments
URL path segments - Parameters
URL query parameters
The API is read-only, i. e. data can be retrieved, but not modified.
Responses
All responses follow the HTTP protocol and include a status code. The response format is defined by a request argument (see URLs). The fields included in a response are configurable via the field configuration and may vary for each instance.
Authentication
Please use HTTPS to access our API. You may access our API without authentication. If you find your requests are being throttled, please get in touch with us at photoarchive@paul-mellon-centre.ac.uk and we will provide an API key.
Data licence
The PMC waives all rights to the data contained in this catalogue. It is offered under a CC0 licence: https://creativecommons.org/publicdomain/zero/1.0/
You can copy, modify and distribute this data – even for commercial purposes – without the need to ask permission.
System API
The Photo Archive catalogue is underpinned by Gallery Systems’ eMuseum software. The eMuseum API is documented here: https://help.gallerysystems.com/emuseum/latest/usage/emuseum-api-documentation
URLs
The base URL for our system API is:
All URL query arguments and parameters are percent-encoded.
Formats
The following response formats are currently supported by our system API:
- XML
A simple XML format without schema. - JSON
A JavaScript Object Notation output. - RDF
A Resource Description Framework output.
Modules
The available modules are:
- objects
- people
The URL pattern to list all records of a module is:
Arguments
OAI-PMH
Our API supports the Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH), a protocol developed for harvesting metadata descriptions of records in an archive so that services can be built using metadata from many archives.
URLs
The base URL for our system API is:
Formats
To retrieve the metadata formats available from the repository, use the verb ListMetadataFormats:
The following schema response formats are currently supported:
- XML: EAD2002 schema
An encoding standard for archival finding aids - XML: LIDO v1.0 schema
Lightweight Information Describing Objects schema designed for contributing content to cultural heritage repositories.
OAI PMH protocol requests
Examples:
Retrieve all records in LIDO format:
Retrieve a specific record in EAD2002 format:
Image API
This API does not contain image files. However, it does contain all of the data you need to access our images. The PMC serves images via a separate API that is compliant with the IIIF Image API 2.0 specification. Using metadata from this API, you can craft URLs that will allow you to access images of artworks from our collection.
IIIF Image API
We deliver our images via the IIIF Image API 2.0. Our IIIF URLs have the following structure:
We recommend the following URL structure for most use-cases:
This is because 500px is a size that is cached on our server, therefore your request should resolve more quickly.
Image Sizes
The size parameter determines the dimensions to which the extracted resource is to be scaled.
|
Parameter |
Description |
|
full |
The extracted region is not scaled, and is returned at its full size. |
|
w, |
The extracted region should be scaled so that its width is exactly equal to w, and the height will be a calculated value that maintains the aspect ratio of the extracted region. |
|
,h |
The extracted region should be scaled so that its height is exactly equal to h, and the width will be a calculated value that maintains the aspect ratio of the extracted region. |
|
w,h |
The width and height of the returned image are exactly w and h. The aspect ratio of the returned image may be different than the extracted region, resulting in a distorted image. |
Examples:
To retrieve the largest image available:
To retrieve a scaled image 500px wide:
To retrieve an image stretched to 500px wide and 800px high exactly:
IIIF Manifests
We also offer IIIF Manifests for all objects in the collection. A manifest is a resource defined by the IIIF Presentation API 2.0. Each manifest contains artwork metadata—such as title, artist name, and copyright info—alongside a list of images associated with that artwork.
You can access the manifest by appending /manifest after the identifier in an artwork detail endpoint:
For example:
These IIIF manifests do not contain any data that cannot be found elsewhere in our API. But because they follow a standardized API, they can be used with IIIF-compliant tools, such as Mirador.
Image Licences
For information about permitted onward uses of our images, please refer to the Rights & Reproductions page.
A machine-readable licence from either Creative Commons or RightsStatement.org is included in our IIIF Manifest:
From a developer's perspective, we recommend only using images of objects that are tagged with a Creative Commons licence that permits onward use. It is up to you to determine whether or not you are allowed to use these images for your use-case and to obtain any necessary permissions.
