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.
- What is IIIF?
- Importance
- Deploying a IIIF Service
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.
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.
- Current Version
- Conventions
- Schema
- Pagination
- Client Errors
- HTTP Redirects
- Rate Limiting
- Cross Origin Resource Sharing
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.
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
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.
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.
TODO.
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.
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
- Listing Items
- Items Types
- Viewing Items
- Producing Tiles
- IIIF Manifests & Metadata
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
[]
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.
Documentation In progress.
Documentation In progress.
Documentation In progress.