- This describes the resources that make up the Internet
- Archive IIIF API v1 (alpha). If you have any problems or
- requests, please
- contact support.
-
-
-
+
- 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.
-
+ The Internet Archive IIIF API service that launched in 2015 was an alpha service that has now been officially upgraded and adopted by the Internet Archive as of September 2023. While stable, it is still under development and we welcome community feedback on desired features.
+
+ The code and logic that runs these APIs is available on Github, and that's where any bugs or features requests can be added.
-
- IDs
+ Convention: IDs
- ID placeholders are preceded by a ":" in examples. IDs need not
+ ID placeholders are preceded by a ":" (colon) in examples. IDs need not
appear in bold, however this is done in the following example for
emphasis:
-
- GET {{ request.url_root }}:id
-
+ https://iiif.archive.org/iiif/3/:id/manifest.json
+Getting started
+
-
+ Nearly all image, text, audio and video items available from the Internet Archive now have a IIIF API URI. This means you can seamlessly view nearly any Archive.org
+ image, book, audio or video in any compatible IIIF viewer and also enjoy
+ the enhancements they provide (e.g., annotation, side-by-size viewing,
+ and loading images from different institutions into the same
+ space).
+
+
- All API access is over HTTPS, and accessed from the
- {{ request.url_root }} domain. All data is sent and received as JSON.
+ The service also provides a mechanism for producing permanantly
+ citeable image tiles of any arbitrary region of any image, book, audio or video
+ found in the Internet Archive.
-
- $ curl -i {{ request.url_root }}
+ In IIIF terms, this functionality is accomplished via two APIs: the Presentation API and the Image API.
- 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
+ Presentation API
+
+ The Presentation
+ API allows institutions to publish and consume metadata about
+ collections and sequences of digital objects (e.g., pages in a book), called "manifests." For images and texts, this is almost always used in conjunction with the IIIF Image API to create manifests for digital objects that any IIIF viewer can use to present an engaging deep-zoom experience.
- {
- ...
- }
-
+ The Presentation API can also faciliate the portability and playback of time-based media like audio and video files. In the A/V context, IIIF manifests often present multiple playback options based on the media formats and quality types available.
+
+ A manifest for an Internet Archive item looks like this:
+ https://iiif.archive.org/iiif/3/:id/manifest.json
- Trailing Slashes
-
- Other than the server root, uris should not end
- with trailing slashes.
-
+ See the sections below for all the possible ways to retrieve manifests for items and collections.
- Summary Representations
+ For more pointers on how IIIF manifests can be used, see the Appendix section on Helpers for different material types.
+Image API
- 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.)
+ The Image API is an
+ interface capable of producing and serving arbitrary tiles of
+ arbitrary regions of an image (just like the different scales of resolution in Google Maps). The properties
+ of these image tiles are specified within a URL, allowing
+ permenant citation and retrieval at a later time.
+ The Image API supports and powers other computer applications
+ (like deep-zoomable image
+ viewers, comparison viewers, and more).
-
- GET {{ request.url_root }}
-
+ The Image API creates images using the following template:
+ {scheme}://{server}/{prefix}/{identifier}/{region}/{size}/{rotation}/{quality}.{format}
+ In the context of the Internet Archive items, that will look like this for a full image:
+ https://iiif.archive.org/image/iiif/3/:id+filename/full/max/0/default.jpg
- 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.)
-
+ Making use of the various parameters, a request for a bitonal center-cropped square image 375 pixels on each side, rotated 45 degrees will look like this:
+ https://iiif.archive.org/image/iiif/3/:id+filename/square/375,/45/bitonal.jpg
-
- 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: []
- }
-
+ See the Image API section on "Image Requests" for more details on how images can be manipulated and specific sizes or sections retrieved.
-
- If this data is insufficient, you may be able to attrieve
- additional information through
- the Advanced
- Search feature.
-
-
+ IIIF Image Viewers read something called an "info.json" file, which lets them know how to process the image for deep zooming.
-
-
-
- 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.
-
+ As a convenience, for a single-image Internet Archive item you can find a redirect to the info.json via the following template:
+ https://iiif.archive.org/iiif/:id/info.json
-
- Item count begins at 0 (the first item is the 0th entry). Paging
- begins at 1, on the first page (i.e. ?page=1)
-
+Example
+Take the following item as an example: https://archive.org/details/img-8664_202009.
-
- $ curl -i {{ request.url_root }}?page=1&limit=25
-
+In this case, img-8664_202009 is the item ID.
- Calculating next page
-
- This section will be updated when pagination for items is
- released.
-
+To get the filename you can go to "Show all" in the "Download Options" box. This will show you a list of links to the various files associated with an item. Taking the jpg link for this item, you get the following URL: https://archive.org/download/img-8664_202009/IMG_8664.jpg
-
+Here, IMG_8664.jpg is the filename.
-
-
-
- TODO.
-
+In order to get the :id+filename the way you need it for the IIIF Image API info.json, you can combine the ID and filename with a URL encoded slash, i.e. %2f.
+
+So for this image, the info.json would be:
+https://iiif.archive.org/image/iiif/3/img-8664_202009%2fIMG_8664.jpg/info.json
+And the full URL for the image would be:
+https://iiif.archive.org/image/iiif/3/img-8664_202009%2fIMG_8664.jpg/full/max/0/default.jpg
+A cropped portion at the full resolution can be requested like this:
+https://iiif.archive.org/image/iiif/3/img-8664_202009%2fIMG_8664.jpg/1100,904,704,664/max/0/default.jpg
+Where "1100,904,704,664" in that URL stands for 1100 pixels from the left edge, 904 pixels from the bottom edge, 704 pixels is the width of the desired section, and 664 pixels is the height.
+
+
+Because it can be time-consuming to manually generate the IIIF Image API URLs, we recommend a IIIF helper tool that can help you identify the Image API URLs for a corresponding IA item. One such tool is Glen Robson's Canvas Finder, which takes as input a Manifest URL (see below for how to find that) and returns links to the images associated with the manifest.
-
-
-
-
-
-
- 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 {{ request.url_root }}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.
-
+More image tools can be found via the community supported Awesome IIIF list.
diff --git a/iiify/templates/docs/resources.html b/iiify/templates/docs/resources.html
index d22efd5..a13f5cb 100644
--- a/iiify/templates/docs/resources.html
+++ b/iiify/templates/docs/resources.html
@@ -13,26 +13,25 @@ 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
+ Querying the root of the Internet Archive IIIF API
+ results in a list of all publicly available 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
+ Internal Server Error. There are also a small number of items returned that do not have material types associted with them that are IIIF compatible. 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.
+ archive.org.
- $ curl -i "{{ request.url_root }}"
+ $ curl -i "{{ request.url_root }}iiif"
- 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
+ HTTP/2 200
+ alt-svc: h3=":443"; ma=2592000
+ cache-control: max-age=900
+ content-type: application/json
+ date: Tue, 15 Aug 2023 14:41:49 GMT
+ server: Caddy
+ server: nginx/1.23.2
+ content-length: 122082
[]
@@ -42,47 +41,69 @@
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
+ Audio, and Movie materials. This means any item on archive.org which has a
+ `mediatype` of `texts`, `image`, `audio`, or `movie`, which can be verified through
the metadata
- API.
-
+ 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.
-
+ There are some edge cases where rare file types are not represented in the IIIF presentation manifest. If you encounter an item where you think this may be the case, contact support.
+
-
-
-
- Documentation In progress.
-
-
+
+
-
-
+ Every Internet Archive item has a "details" page that is the main page for that item.
- Documentation In progress.
-
+ The "details" page will have the word "details" in the URL, like in this example:
+ https://archive.org/details/img-8664_202009
+
+ What you'll need to get the IIIF manifest for any Internet Archive item is the identifier, which is the alphanumeric part of the URL that follows the "/details/" part.
+
+ So, from our example just above, the Internet Archive identifier for that item is:
img-8664_202009
+
+ To then get the IIIF manifest, plug in the ID to the following template:
+ https://iiif.archive.org/iiif/:id/manifest.json
+
+ For the example above, the final IIIF manifest URL would be:
+ https://iiif.archive.org/iiif/img-8664_202009/manifest.json
+
+
+
+ Getting IIIF collection manifests
+
+ More than one IIIF manifests can be formally grouped into what is called a "collection" manifest.
+
+ On archive.org, a collection is a group of item pages organized under a collections page. For convenience, we've create a route that generates a IIIF collection manfiest for all of the collections on the Internet Archive. For more on how collections work, see the "Collections - A Basic Guide" page.
+
+ As with the manifests above, you'll need the Internet Archive identifier for the colllection. Here's an example collection page from the University of Leeds:
+ ttps://archive.org/details/leedsuniversitylibrary
+
+ In this case, the id is:
+leedsuniversitylibrary
+
+ To then get the IIIF collection manifest, plug in the ID to the following template:
+ https://iiif.archive.org/iiif/:id/collection.json
+
+ For the Leeds example above, the final IIIF collection manifest URL would be:
+ https://iiif.archive.org/iiif/leedsuniversitylibrary/collection.json
+
+
+
+
-
+
Documentation In progress.
+
-
+
+ Getting legacy IIIF Presentation 2.1 manfiests
+
-
-
