IIIF APIs Documentation
- Jolan Wuyts
- Hugo Manguinhas
- Luthien Dulk
The Europeana APIs offer for IIIF covers the Presentation API (versions 2.1 & 3), the Content Search API (version 1) and make use of the IIIF Image API when made available by content providers. Additionally, Europeana’s IIIF offer also includes support for fulltext (such as transcriptions, translations of transcriptions, captions and subtitles) via the IIIF Fulltext API using an EDM extension for fulltext. These APIs follow the specifications defined by the IIIF consortium.
You don’t need an API key for this API!
Introduction
The International Image Interoperability Framework (IIIF) is a range of standards that were initially designed to offer a standardized and scallable way to describe how digital objects composed of one or more images can be displayed to an end-user. This offers the flexibility to developers and users to respectively develop and use different IIIF compatible viewers according to their needs and preferences. Since its first release, it has grown to cover other types of media such as sound and video, and soon also 3D.
IIIF datasets in Europeana: A Scholar’s delight
The recently launched Europeana Media player brings Europeana into a new era of International Image Interoperability Framework (IIIF) compatible, interoperable and unified playout of audiovisual heritage material online.
IIIF & Europeana Working Group
This dedicated IIIF & Europeana Working Group follows the first of the proposals from the Task Force 'Preparing Europeana for IIIF involvement.'
Impact Assessment report: EuropeanaTech and IIIF
This assessment looked at the impact of EuropeanaTech’s members, steering group and the Europeana Initiative’s work on IIIF - read a summary of the research and download the full report.
Retrieving a manifest
A manifest describes the information needed for a viewer to display a digital object to the end-user, such as basic metadata such as a title and description, and the content that makes part of the digital object. The manifest is not meant to present all the descriptive metadata associated to a given digital object but just the bare minimum for a user to grasp what it is about. If you wish to access the full metadata for an item, see the Record API. The manifest also offers links to the Record API using the “seeAlso“ field.
The manifests are generated on-the-fly by converting the metadata records represented in EDM into the IIIF Presentation API specification. Presently, both version IIIF Presentation API 2.1 & 3 are supported. The novelty of version 3 is that it also covers audio and video besides images.
Request
https://iiif.europeana.eu/presentation/[RECORD_ID]/manifest
Accept: [ACCEPT]Parameter | Location | Description |
|---|---|---|
RECORD_ID | path | The identifier of the record which is composed of the dataset identifier plus a local identifier within the dataset in the form of "/DATASET_ID/LOCAL_ID", for more detail see Europeana ID. |
Accept | header | Used to indicate the mimetype of the format and IIIF version. The following indicate the Accept header to be used for version 2.1 and 3 respectively:
|
format (optional) | query | A convenience parameter used to indicate the version of the IIIF Presentation API. Indicating the format within the Accept header is the preferred way to request a specific version. This parameter should not be used if a profile is indicated in the Accept header. |
Response v3:
Response v2.1:
Retrieving images or portions of the image
The IIIF Image API specification offers the ability to request portions of the image in different resolutions allowing the image to be served progressively to a web client. Providers that have implemented the IIIF Image API for their content may indicate the availability of the image service using a dedicated profile. When this is the case, the Manifest will refer to the image service so that web clients can make use of it. Europeana also has available high resolution scans that were produced under the Europeana Newspapers project that are served using IIIF Image API.
Image service
Retrieves an image by applying the operations indicated in the path. The image endpoint used is from the Europeana Newspapers project.
Request
https://iiif.europeana.eu/image/[IMAGE_ID]/[REGION]/[SIZE]/[ROTAION]/[QUALITY].[FORMAT]Parameter | Location | Description |
|---|---|---|
IMAGE_ID | path | The identifier of the image. |
REGION | path | The region parameter defines the rectangular portion of the underlying image content to be returned. Region can be specified by pixel coordinates, percentage or by the value full, which specifies that the full image should be returned. |
SIZE | path | The size parameter specifies the dimensions to which the extracted region, which might be the full image, is to be scaled. |
ROTATION | path | The rotation parameter specifies mirroring and rotation. A leading exclamation mark (\"!\") indicates that the image should be mirrored by reflection on the vertical axis before any rotation is applied. The numerical value represents the number of degrees of clockwise rotation, and may be any floating point number from 0 to 360. |
QUALITY | path | The quality parameter determines whether the image is delivered in color, grayscale or black and white. |
FORMAT | path | The format of the returned image is expressed as a suffix, mirroring common filename extensions, at the end of the URI. |
Image service details
Retrieves information about the image and the available operations that can be done on the image. The image endpoint used is from the Europeana Newspapers project.
Request
https://iiif.europeana.eu/image/[IMAGE_ID]/info.jsonParameter | Location | Description |
|---|---|---|
IMAGE_ID | path | The identifier of the image. |
Retrieving full-text content
The term full-text is meant to refer to the correlation between the content resource (e.g. image, audio or video) and its textual representation (ie. transcription, subtitle, caption). In the EDM profile, the textual representation of the content resource is referred to as Full-Text Resource while the relations between the segments of the text and the coordinates in the image are referred to as Annotations.
Annotation Pages
An Annotation Page contains all the annotations that make up the full-text of a content resource (ie. image, audio or video). It is referred to by the Manifest and can be accessed via the following request.
Request
Parameter | Location | Description |
|---|---|---|
RECORD_ID | path | The identifier of the record which is composed of the dataset identifier plus a local identifier within the dataset in the form of "/DATASET_ID/LOCAL_ID", for more detail see Europeana ID. |
PAGE_ID | path | The identifier of the annotation page. |
Accept | header | Used to indicate the mimetype of the format and IIIF version. The following indicate the Accept header to be used for version 2.1 and 3 respectively:
|
textGranularity (optional) | query | Filters the annotations based on their granularity. Available values : page, block, line, word, media, caption |
lang (optional) | query |
A parameter used to request full-text in a specific language, if available. The value must be a two letter ISO639 code and match the languages that are supported by Europeana. Available values : en, nl, fr, de, es, sv, it, fi, da, el, cs, sk, sl, pt, hu, lt, pl, ro, bg, hr, lv, ga, mt, et, no, ca, ru, eu |
profile (optional) | query | A parameter used to define the extent of the response. The only value supported is 'text' which is used to request the response to be extended with the content of the text resource. Available values : text |
format (optional) | query | A convenience parameter used to indicate the version of the IIIF Presentation API. Indicating the format within the Accept header is the preferred way to request a specific version. This parameter should not be used if a profile is indicated in the Accept header. |
Response v3:
Response v2.1:
Annotation
An Annotation specifies a single relation between the full-text resource and the content resource (ie. image, audio or video). It is referred to by the Annotation Page and can be accessed via the following request.
Request
Parameter | Location | Description |
|---|---|---|
RECORD_ID | path | The identifier of the record which is composed of the dataset identifier plus a local identifier within the dataset in the form of "/DATASET_ID/LOCAL_ID", for more detail see Europeana ID. |
ANNO_ID | path | The identifier of the annotation. |
profile (query) | query | A parameter used to define the extent of the response. The only value supported is 'text' which is used to request the response to be extended with the content of the text resource. Available values : text |
Response v3
Response v2.1
Fulltext Resource
The full-text resource represents the (image or audio) transcription of a single content resource (e.g. a page of a newspaper or manuscript). A full-text resource can be accessed separately from an annotation or annotation page using the following method.
Request
Parameter | Location | Description |
RECORD_ID | path | The identifier of the record which is composed of the dataset identifier plus a local identifier within the dataset in the form of "/DATASET_ID/LOCAL_ID", for more detail see Europeana ID. |
FULLTEXT_ID | path | The identifier of the full-text resource. |
lang (optional) | query | A parameter used to request full-text in a specific language, if available. The value must be a two letter ISO639 code and match the languages that are supported by Europeana. Available values : en, nl, fr, de, es, sv, it, fi, da, el, cs, sk, sl, pt, hu, lt, pl, ro, bg, hr, lv, ga, mt, et, no, ca, ru, eu |
Response v3
Response v2.1 (not supported)
Searching on full-text
There are two methods for searching on full-text, one for searching across all items where fulltext is available and a second to search within the fulltext of a single item.
Search accross all items with full-text
This method adopts the same API structure and functionality as the Search API with the addition of two search fields and one profile as described below. For more information on the other methods, see the Search API documentation.
Request
Parameter | Location | Description |
|---|---|---|
query | query | The text or search criteria to be used for searching. Two additional fields are supported:
|
profile | query | A profile typically determines how extensive the response will be, by either dictating the metadata fields that will be present (ie. minimal, standard and rich) or appending additional data elements such as facets. Most profiles can be combined with the exception of the metadata based profiles or combined profiles such as rich. An additional profile is supported named “hits“ that displays the mentions in the transcribed text where the search keyword was found. Available values : minimal, standard, rich, facets, hits, breadcrums, params, portal, translate |
hit.fl (optional) | query | Fields for which hit highlighting is generated. A wildcard “*” (asterisk) can be used to match multiple fields, such as “fulltext.*” or even “*” to highlight on all fields where highlighting is possible. If omitted default to “*”. Multiple fields can be indicated using a comma or space. |
hit.selectors (optional) | query | The maximum number of highlighted selectors to generate per item. If omitted defaults to 3. It is possible for any number of selectors from 1 to this value to be generated, up to a limit of 10. |
Search within full-text of a single item
For a Newspapers item, this will mean searching in the text of all the pages that make up the Newspaper.
Request
Parameter | Location | Description |
|---|---|---|
RECORD_ID | path | The identifier of the record which is composed of the dataset identifier plus a local identifier within the dataset in the form of "/DATASET_ID/LOCAL_ID", for more detail see Europeana ID. |
Accept | header | Used to indicate the mimetype of the format and IIIF version. The following indicate the Accept header to be used for version 2.1 and 3 respectively:
|
q query | query | The text to be used for searching. |
qf | query | A search query filter, ie. a filter is applied on the result list to remove unwanted results and therefore has no effect on ranking. This parameter can be used multiple types if more than one query filter is needed. |
textGranularity | query | Filters the annotations based on their granularity. Available values : page, block, line, word, media, caption |
lang | query | A parameter used to request full-text in a specific language, if available. The value must be a two letter ISO639 code and match the languages that are supported by Europeana. Available values : en, nl, fr, de, es, sv, it, fi, da, el, cs, sk, sl, pt, hu, lt, pl, ro, bg, hr, lv, ga, mt, et, no, ca, ru, eu |
Response v3
Response v2.1
Source code and changelog
As mentioned in the introduction, the IIIF APIs are made up of several distinct APIs, each one with its own source code project in GitHub and changelog as listed below.
API | Last version | Description |
|---|---|---|
Supports only the retrieval of manifests. | ||
Supports the retrieval of full-text which inludes full-text resources, annotation and annotation pages, and search within full-text. | ||
Search API (see documentation) | Supports the search accross items with full-text. | |