IIIF API


Introduction

For those newly aquainted with the IIIF specification, this introduction describes the purpose and applications of IIIF and the Internet Archive's IIIF Service.

  1. What is IIIF?
  2. Importance
  3. Deploying a IIIF Service

What is IIIF?

IIIF (the "International Image Interoperability Framework") is a collection of web standards for manipulating and serving image resources (Image API), as well as structuring collections of these images (Presentation API).

Image API

The Image API is an interface capable of producing and serving arbitrary tiles of arbitrary regions of an image (like Google Maps). The properties of these image tiles are specified within a URL, allowing permenant citation and retrieval at a later time (see idempotence). The Image API supports and powers other computer applications (like zoomable image viewers and book readers).

Presentation API

The Presentation API allows institutions to publish and consume metadata about collections and sequences of image resources, called Manifests. A Manifest may be composed of resources from any number of different institutions serving their images in IIIF format.

For more information, read about IIIF's goals here.

Importance

At its essence, the goal of IIIF is interoperability: to make an institution's image resources available and accessible to web applications and clients running on other domains.

The Internet Archive IIIF API v1 (alpha) is a RESTful web service which implements IIIF (Image API & Presentation API) and provides a mechanism for accessing all of the Archive's images and books in IIIF format. Every image item in the Archive now has has a corresponding info.json and every book a manifest.json. This means, you can seamlessly view any Archive.org image or book in any interface compatible with IIIF (such as OpenSeadragon, Mirador, and the Universal Viewer) and also enjoy the enhancements they provide (annotation, side-by-size viewing, and loading images from different institutions into the same space).

The service also provides a mechanism for producing permanantly citeable image tiles of any arbitrary region of any image or book found in the Internet Archive.

Deploying a IIIF Service

The Internet Archive IIIF API v1 (alpha) is built using Python3.4 Flask web application framework and the iiif2 library. The source code for iiif.archive.org is publicly available here, as is the source of the iiif2 image processing library here. For questions on implementing a service, contact support@archive.org.


Overview

This describes the resources that make up the Internet Archive IIIF API v1 (alpha). If you have any problems or requests, please contact support.

  1. Current Version
  2. Conventions
  3. Schema
  4. Pagination
  5. Client Errors
  6. HTTP Redirects
  7. Rate Limiting
  8. Cross Origin Resource Sharing

Current Version

Caution. The Internet Archive IIIF API is currently at version 1 (alpha). This means it is currently under development as a prototype for community feedback and may be either discontinued at any time, or deprecated in favor of an official version 1 release.

Conventions

IDs

ID placeholders are preceded by a ":" in examples. IDs need not appear in bold, however this is done in the following example for emphasis:

GET https://iiif.archivelab.org/:id

Schema

All API access is over HTTPS, and accessed from the https://iiif.archivelab.org/ domain. All data is sent and received as JSON.


  $ curl -i https://iiif.archivelab.org/  

  HTTP/1.1 200 OK
  Server: nginx/1.4.6 (Ubuntu)
  Date: Tue, 22 Sep 2015 08:07:27 GMT
  Content-Type: application/json
  Content-Length: 21307
  Connection: keep-alive
  Cache-Control: max-age=5

  {
    ...
  }
    

Trailing Slashes

Other than the server root, uris should not end with trailing slashes.

Summary Representations

When you fetch a list of resources, the response includes a subset of the attributes for that resource. This is the “summary” representation of the resource. (Some attributes are computationally expensive for the API to provide. For performance reasons, the summary representation excludes those attributes. To obtain those attributes, fetch the “detailed” representation.)

GET https://iiif.archivelab.org/

Detailed Representations

To get detailed metadata about a specific Archive.org item, fetch the item's metadata by ID through the Archive.org. (Note that authorization sometimes influences the amount of detail included in the representation.)

GET https://archive.org/metadata/:id

For example:


  $ curl -i "https://archive.org/metadata/thirteenbookseu03heibgoog"

  HTTP/1.1 200 OK
  Server: nginx/1.4.6 (Ubuntu)
  Date: Tue, 22 Sep 2015 08:07:27 GMT
  Content-Type: application/json
  Content-Length: 21307
  Connection: keep-alive
  Cache-Control: max-age=5

  {
    created: 1442378110,
    d1: "ia600309.us.archive.org",
    ad2: "ia800309.us.archive.org",
    dir: "/20/items/thirteenbookseu03heibgoog",
    files: [],
    files_count: 16,
    item_size: 196609584,
    metadata: {},
    reviews: [],
    server: "ia800309.us.archive.org",
    uniq: 893310999,
    updated: 1442380951,
    workable_servers: []
  }
    

If this data is insufficient, you may be able to attrieve additional information through the Advanced Search feature.

Pagination

Requests that return multiple items will be paginated to 50 items by default. You can specify further pages with the ?page GET parameter. For some resources, you can also set a custom page size up to 100 with the ?limit parameter. Note that for technical reasons not all endpoints respect the ?limit parameter, see events for example.

Item count begins at 0 (the first item is the 0th entry). Paging begins at 1, on the first page (i.e. ?page=1)


  $ curl -i https://iiif.archivelab.org/?page=1&limit=25
    

Calculating next page

This section will be updated when pagination for items is released.

Client Errors

TODO.

HTTP Redirects

Cross Origin Resource Sharing

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin. You can read the CORS W3C Recommendation, or this intro from the HTML 5 Security Guide.

Rate Limiting

For the API v1 (alpha) API, no rate limiting is in effect -- we are operating on a trust model. For the stable v1 release, unauthenticated requests will be limited to 2,000 per hour. When this change comes into effect, you will be able to check the returned HTTP headers of any API request to see your current rate limit status:


  $ curl -i https://iiif.archivelab.org/platowithenglish04platuoft

  HTTP/1.1 200 OK
  Date: Tue, 22 Sep 2015 08:07:27 GMT
  Status: 200 OK
  X-RateLimit-Limit: 2000
  X-RateLimit-Remaining: 1999
  X-RateLimit-Reset: 1372700873
  
Header Name Description
X-RateLimit-Limit The maximum number of requests that the consumer is permitted to make per hour.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.

For more information, refer to github's Traversing With Pagination documentation, as pagination for our interface is modeled after their service.


Items

  1. Listing Items
  2. Items Types
  3. Viewing Items
  4. Producing Tiles
  5. IIIF Manifests & Metadata

Listing Items

Querying the root of the Internet Archive IIIF v1 (alpha) server results in a list of all publicly available and compatible image and book items. Some items which are indexed in our search engine but do have no associated content files will result in an Internal Server Error. You can confirm whether the resource actually exists or not by visiting the item's /details page on archive.org. In the official v1 release, the message displayed for this error will be clarified.


  $ curl -i "https://iiif.archivelab.org/"

  HTTP/1.1 200 OK
  Server: nginx/1.4.6 (Ubuntu)
  Date: Tue, 22 Sep 2015 08:07:27 GMT
  Content-Type: application/json
  Content-Length: 21307
  Connection: keep-alive
  Cache-Control: max-age=5

  []
    

Item Types

Items available through the this service include Images, Books, Book Pages. This includes any item on archive.org which has a `mediatype` of `texts` or `image` which can be verified through the metadata API.

Supported Image Formats

The image formats available for a given item is determine by the item's files on archive.org. To see what formats are available for an item, go to https://archive.org/metadata/:itemid/files.

The API is capable of interfacing with jp2 (openjpeg), gif, jpg, tiff, png.

Viewing Images

Documentation In progress.

Producing Tiles

Documentation In progress.

IIIF Manifests & Metadata

Documentation In progress.