-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #7 from internetarchive/update-docs
- Loading branch information
Showing
13 changed files
with
333 additions
and
378 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| <article id="resources" class="hiddenz"> | ||
| <h1 id="appendix">Appendix</h1> | ||
|
|
||
| <section> | ||
| <h2><a name="resources-legacy"></a>Getting legacy IIIF Presentation API 2.1 manifests</h2> | ||
|
|
||
| <p>To get the older Presentation API 2.1 IIIF manifest, plug in the ID to the following template:</p> | ||
| <div class="request">https://iiif.archive.org/iiif/2/<b>:id</b>/manifest.json</div> | ||
| </section> | ||
|
|
||
| <section> | ||
| <h2><a name="resources-listing">Listing all items</a></h2> | ||
| <p> | ||
| 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. There are also a small number of items returned that do not have material types associated 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. | ||
| </p> | ||
|
|
||
| <div class="request">https://iiif.archive.org/iiif</div> | ||
|
|
||
| </section> | ||
|
|
||
|
|
||
| <section> | ||
| <h2><a name="helpers">Helpers for various media types</a></h2> | ||
| <p> | ||
| To give you a sense of how different media types on the Internet Archive can be used in IIIF viewers, we've created a set of item "helpers" that provide some useful iformation and links. | ||
| </p> | ||
| <p>The pattern for these helper pages is as follows:</p> | ||
| <div class="request">https://iiif.archive.org/iiif/helper/<b>:id</b> </div> | ||
|
|
||
| <p>So, for example, the helper page for <a href="https://archive.org/details/img-8664_202009">a single image item</a> with item id <b>img-8664_202009</b> would be the following:</p> | ||
| <div class="request">https://iiif.archive.org/iiif/helper/img-8664_202009</div> | ||
|
|
||
| <p>The helper page for this <a href="https://archive.org/details/youtube-7w8F2Xi3vFw">movie item</a> with item id <b>youtube-7w8F2Xi3vFw</b> would be the following:</p> | ||
| <div class="request">https://iiif.archive.org/iiif/helper/youtube-7w8F2Xi3vFw</div> | ||
|
|
||
| <p>Not all media types on the Internet Archive have files that are playable in IIIF viewers, but the helper pages should work for images, texts, audio, and movie items.</p> | ||
| <br> | ||
| <br> | ||
| <br> | ||
| <br> | ||
|
|
||
|
|
||
|
|
||
| </section> | ||
| </article> | ||
| </hr> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| <article id="resources" class="hiddenz"> | ||
| <h1 id="collections">Collections</h1> | ||
|
|
||
| <section> | ||
| <h2><a name="resources-collections"></a>Getting IIIF collection manifests</h2> | ||
|
|
||
| <p>A group of more than one IIIF manifests is called a collection. On archive.org, a collection is a group of item pages organized under a collections page. For convenience, we've generate a IIIF collection manfiest for all of the collections on the Internet Archive. For more on how Internet Archive collections work, see <a href="https://help.archive.org/help/collections-a-basic-guide/">the "Collections - A Basic Guide"</a>.</p> | ||
|
|
||
| <h4>Example</h4> | ||
| <p>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:</p> | ||
| <pre><a href="https://archive.org/details/leedsuniversitylibrary">https://archive.org/details/leedsuniversitylibrary</a></pre> | ||
|
|
||
| <p>In this case, the id is:</p> | ||
| <pre>leedsuniversitylibrary</pre> | ||
|
|
||
| <p>To then get the IIIF collection manifest, plug in the ID to the following template:</p> | ||
| <div class="request">https://iiif.archive.org/iiif/3/<b>:id</b>/collection.json</div> | ||
|
|
||
| <p>For the Leeds example above, the final IIIF collection manifest URL would be:</p> | ||
| <div class="request">https://iiif.archive.org/iiif/3/leedsuniversitylibrary/collection.json</div> | ||
|
|
||
| <h3>Note about nested collections</h3> | ||
| <p>Please note that Internet Archive collections can be arbitrarily nested within other collections. In these cases, the IIIF collection manifest will return a link to one or more IIIF collection manifest(s) in addition to the items nested individually within that Internet Archive collection.</p> | ||
|
|
||
| </section> | ||
|
|
||
| <section> | ||
| <h2><a name="resources-listing">Pagination for large collections</a></h2> | ||
| <p>The pattern described above for generating IIIF collection manifests will return the first 1000 items or sub-collections within the collection. In order to get the remaining items for collections larger than that, pagination is required.</p> | ||
| <p>This looks like the following: | ||
| <div class="request">https://iiif.archive.org/iiif/<b>:id</b>/<b>:page</b>/collection.json</div></p> | ||
|
|
||
| <p>For the University of Leeds collection above, there are at the time of this writing 3,775 items in the collection. That means that four collections manifest requests will be required to retrieve all the items and/or sub-collections listed within the collection.</p> | ||
|
|
||
| <table> | ||
| <thead><td>Collection manifest URL</td><td>Items retrieved</td></thead> | ||
| <tr><td>https://iiif.archive.org/iiif/3/leedsuniversitylibrary/collection.json</td><td>0-999</td></tr> | ||
| <tr><td>https://iiif.archive.org/iiif/3/leedsuniversitylibrary/2/collection.json</td><td>1000-1999</td></tr> | ||
| <tr><td>https://iiif.archive.org/iiif/3/leedsuniversitylibrary/3/collection.json</td><td>2000-2999</td></tr> | ||
| <tr><td>https://iiif.archive.org/iiif/3/leedsuniversitylibrary/4/collection.json</td><td>3000-3775</td></tr> | ||
| </table> | ||
| </section> | ||
| </article> | ||
| </hr> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,107 +1,29 @@ | ||
| <article id="introduction" class="hiddenz"> | ||
| <h1>Introduction</h1> | ||
| <h1 id="intro">Introduction</h1> | ||
|
|
||
| <p><a href="https://iiif.io">IIIF</a> stands for the International Image Interoperability Framework.</p> | ||
|
|
||
| <p> | ||
| For those newly aquainted with the IIIF specification, this | ||
| introduction describes the purpose and applications of | ||
| <a href="https://iiif.io">IIIF</a> and the Internet Archive's IIIF | ||
| Service. | ||
| This introduction describes the way that the IIIF standards have been applied to the Internet Archive's services. | ||
| </p> | ||
|
|
||
| <ol type="i" class="toc"> | ||
| <li><a href="">What is IIIF?</a></li> | ||
| <li><a href="">Importance</a></li> | ||
| <li><a href="">Deploying a IIIF Service</a></li> | ||
| </ol> | ||
|
|
||
| <section> | ||
| <h2><a name="intro-iiif">What is IIIF?</a></h2> | ||
| <p> | ||
| <a href="https://iiif.io">IIIF</a> (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). | ||
| </p> | ||
|
|
||
| <h3>Image API</h3> | ||
| <p> | ||
| The <a href="http://iiif.io/api/image/2.0/">Image API</a> 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 <a href="https://en.wikipedia.org/wiki/Idempotence">idempotence</a>). | ||
| The Image API supports and powers other computer applications | ||
| (like <a href="https://openseadragon.github.io/">zoomable image | ||
| viewers</a> | ||
| and <a href="http://universalviewer.azurewebsites.net/">book | ||
| readers</a>). | ||
| IIIF is a set of open standards for delivering high-quality, attributed digital objects online at scale. It’s also an international community developing and implementing the IIIF APIs in various contexts. IIIF is backed by a consortium of leading cultural institutions. For more details and examples, check out the <a href="https://iiif.io">IIIF website</a>, or the <a href="https://iiif.io/api">full API specifications</a>. | ||
| </p> | ||
| <p>For a very high-level overview see <a href="https://iiif.io/get-started/how-iiif-works/">"How IIIF Works"</a> published by the IIIF Consortium.</p> | ||
|
|
||
| <h3>Presentation API</h3> | ||
| <p> | ||
| The <a href="http://iiif.io/api/presentation/2.0/">Presentation | ||
| API</a> 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. | ||
| </p> | ||
|
|
||
| <p> | ||
| For more information, read about IIIF's | ||
| goals <a href="http://universalviewer.azurewebsites.net/">here</a>. | ||
| </p> | ||
|
|
||
| <h2><a name="intro-importance">Importance</a></h2> | ||
| <h2><a name="intro-importance">Why?</a></h2> | ||
| <p> | ||
| 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 goal of IIIF is interoperability: to make an | ||
| institution's image and audio/visual openly accessible resources available and easily reusable in a variety of web viewers and players, often open source, without the need for any special plugins or software. | ||
| </p> | ||
|
|
||
| <p> | ||
| The <a href="{{ request.url_root }}">Internet Archive IIIF API | ||
| v1</a> | ||
| (<a href="https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha">alpha</a>) | ||
| is | ||
| a <a href="https://en.wikipedia.org/wiki/Representational_state_transfer">RESTful</a> | ||
| <a href="https://en.wikipedia.org/wiki/Web_service">web | ||
| service</a> 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). | ||
| </p> | ||
| <p>Fore more about how the goals of interoperability fit with the Internet Archive's mission, see our <a href="https://blog.archive.org/2023/09/18/making-iiif-official-at-the-internet-archive/">Making IIIF Official at the Internet Archive</a> announcement.</p> | ||
|
|
||
| <p> | ||
| 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. | ||
| </p> | ||
| </section> | ||
|
|
||
| <section> | ||
| <h2>Deploying a IIIF Service</h2> | ||
| <p> | ||
| The Internet Archive IIIF API v1 (alpha) is built using | ||
| Python3.4 <a href="https://pypi.python.org/pypi/Flask">Flask</a> | ||
| web application framework and | ||
| the <a href="https://pypi.python.org/pypi/iiif2">iiif2</a> | ||
| library. The source code | ||
| for <a href="iiif.archive.org">iiif.archive.org</a> is publicly | ||
| available <a href="https://github.com/mekarpeles/iiif.archive.org">here</a>, | ||
| as is the source of | ||
| the <a href="pypi.python.org/pypi/iiif2">iiif2</a> image | ||
| processing | ||
| library <a href="https://github.com/mekarpeles/iiif2">here</a>. For | ||
| questions on implementing a service, | ||
| contact <a href="mailto:[email protected]">[email protected]</a>. | ||
| </p> | ||
| </section> | ||
| </article> | ||
|
|
||
| <hr/> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,60 @@ | ||
| <article id="resources" class="hiddenz"> | ||
| <h1 id="items">Items</h1> | ||
| <p> | ||
| <!-- | ||
| <ol type="i" class="toc"> | ||
| <li><a href="">Listing Items</a></li> | ||
| <li><a href="">Items Types</a></li> | ||
| <li><a href="">Viewing Items</a></li> | ||
| <li><a href="">Producing Tiles</a></li> | ||
| <li><a href="">IIIF Manifests & Metadata</a></li> | ||
| </ol> --> | ||
|
|
||
|
|
||
|
|
||
| <section> | ||
| <h2><a name="resources-types">Item Types</a></h2> | ||
| <p> | ||
| Items available through the this service include Images, Books, | ||
| Audio, and Movie materials. This means any item on archive.org which has a | ||
| `mediatype` of `texts`, `image`, `audio`, or `movie`.</p> | ||
|
|
||
| <p>For more pointers on how IIIF manifests can be used for different material types, see the Appendix section on <a href="#helpers">Helpers</a>.</p> | ||
|
|
||
| <p>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, <a href="https://github.com/internetarchive/iiif/issues">open an issue on the Github repository</a>.</p> | ||
|
|
||
| </section> | ||
|
|
||
| <section> | ||
| <h2><a id="retrieving-manifests"></a>Retrieving a manifest for an item</h2> | ||
|
|
||
| <p>Every Internet Archive item has a "details" page that is the main page for that item.</p> | ||
| <p> | ||
| The "details" page will have the word "details" in the URL, like in this example: | ||
| <pre><a href="https://archive.org/details/img-8664_202009">https://archive.org/details/img-8664_202009</a></pre></p> | ||
|
|
||
| <h4>Example</h4> | ||
| <p>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. </p> | ||
|
|
||
| <p>So, from our example just above, the Internet Archive identifier for that item is: <pre>img-8664_202009</pre></p> | ||
|
|
||
| <p>To then get the IIIF manifest, plug in the ID to the following template:</p> | ||
| <div class="request">https://iiif.archive.org/iiif/3/<b>:id</b>/manifest.json</div> | ||
|
|
||
| <p>For the example above, the final IIIF manifest URL would be:</p> | ||
| <div class="request">https://iiif.archive.org/iiif/3/img-8664_202009/manifest.json</div> | ||
|
|
||
| <h3>Note about IIIF Presentation API versions</h3> | ||
| <p> | ||
| The pattern above describes the way to return IIIF Presentation API 3.0 manifests, as denoted by the <b>/3/</b> in the URL. </p> | ||
| <p>The manifest URL can also be used with the version number removed (<span>https://iiif.archive.org/iiif/<b>:id</b>/manifest.json</span>), though note that with any future updates that URL will always return the most current version of the Presentation API.</p> | ||
|
|
||
|
|
||
| <p>The older experimental version of the IIIF APIs for Internet Archive materials hosted on Archivelabs served up IIIF Presentation API version 2.1 manifests; <a href="#appendix">see below for instructions on retrieving a legacy manifests</a>.</p> | ||
|
|
||
|
|
||
| </section> | ||
|
|
||
|
|
||
| </article> | ||
| </hr> |
Oops, something went wrong.