Introduction

The International Image Interoperability Framework (IIIF) combines  is a set range of APIs standards that offer an alternative and complementary means to group, search and access information about the digital objects (aside from the Search and Record APIs) specifically tailored for the display of Newspaper materials. These APIs follow the specifications defined by the IIIF consortium and therefore can also be suitable for other materials that can have full text content besides Newspaperswere 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.

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.

Before starting to use these APIs, we recommend reading the Registering for an API key and reading the Terms of Use. If you want to get started with these APIs, go directly to the Getting Started section or try it out directly on the Console. If you want to get regular updates about the Europeana API, provide feedback and discuss it with other developers, we suggest to join the Europeana API discussion group at Google Groups.

Getting Started

Retrieving a manifest

A manifest describes the information needed for a viewer to present display a digital object to the end-user, such as basic metadata such as the a title and description, and the sequence of views/imagescontent 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.

Presently, only both version 2.1 & 3 of the IIIF specification is supported but very soon also the v3 will become availableare 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

Response

Example: Requesting a manifest in v2.1

Request:

https://iiif.europeana.eu/presentation/9200356/BibliographicResource_3000118390149/manifest?wskey=YOUR_KEY

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "https://iiif.europeana.eu/presentation/9200396/BibliographicResource_3000118436165/manifest",
  "@type": "sc:Manifest",
  "label": [
    {
      "@value": "Journal historique et littéraire - 1788-09-01"
    }
  ],
  "metadata": [ ... ]
  "thumbnail": {
    "@type": "dctypes:Image",
    "@id": "https://api.europeana.eu/api/v2/thumbnail-by-url.json?uri=https%3A%2F%2Fiiif.europeana.eu%2Fimage%2FQNYVL2Z2FVHRGMK2UNXIP4DUUOTOVA2ND3WIPJQF6V23SO2CJ5UA%2Fpresentation_images%2Fee0edfa0-0220-11e6-a696-fa163e2dd531%2Fnode-3%2Fimage%2FBNL%2FJournal_historique_et_litt%C3%A9raire%2F1788%2F09%2F01%2F00001%2Ffull%2Ffull%2F0%2Fdefault.jpg&type=TEXT"
  },
  "navDate": "1788-09-01T00:00:00Z",
  "attribution": "Journal historique et littéraire - 1788-09-01 - https://www.europeana.eu/portal/record/9200396/BibliographicResource_3000118436165.html. National Library of Luxembourg. Public Domain - http://creativecommons.org/publicdomain/mark/1.0/",
  "license": "http://creativecommons.org/publicdomain/mark/1.0/",
  "logo": "https://style.europeana.eu/images/europeana-logo-default.png",
  "seeAlso": [ ... ]
  "sequences": [
    {
      "@id": "https://iiif.europeana.eu/presentation/9200396/BibliographicResource_3000118436165/sequence/s1",
      "@type": "sc:Sequence",
      "label": "Current Page Order",
      "startCanvas": "https://iiif.europeana.eu/presentation/9200396/BibliographicResource_3000118436165/canvas/p1",
      "canvases": [
        {
          "@type": "sc:Canvas",
          "@id": "https://iiif.europeana.eu/presentation/9200396/BibliographicResource_3000118436165/canvas/p1",
          "label": "p. 1",
          "height": 1024,
          "width": 686,
          "attribution": "Journal historique et littéraire - 1788-09-01 - https://www.europeana.eu/portal/record/9200396/BibliographicResource_3000118436165.html. National Library of Luxembourg. Public Domain - http://creativecommons.org/publicdomain/mark/1.0/",
          "images": [
            {
              "@type": "oa:Annotation",
              "@id": "https://iiif.europeana.eu/presentation/9200396/BibliographicResource_3000118436165/annotation/p1",
              "motivation": "sc:painting",
              "resource": {
                "@type": "dctypes:Image",
                "@id": "https://iiif.europeana.eu/image/QNYVL2Z2FVHRGMK2UNXIP4DUUOTOVA2ND3WIPJQF6V23SO2CJ5UA/presentation_images/ee0edfa0-0220-11e6-a696-fa163e2dd531/node-3/image/BNL/Journal_historique_et_littéraire/1788/09/01/00001/full/full/0/default.jpg",
                "service": {
                  "@id": "https://iiif.europeana.eu/image/QNYVL2Z2FVHRGMK2UNXIP4DUUOTOVA2ND3WIPJQF6V23SO2CJ5UA/presentation_images/ee0edfa0-0220-11e6-a696-fa163e2dd531/node-3/image/BNL/Journal_historique_et_littéraire/1788/09/01/00001",
                  "profile": "http://iiif.io/api/image/2/level1.json",
                  "@context": "http://iiif.io/api/image/2/context.json"
                }
              },
              "on": "https://iiif.europeana.eu/presentation/9200396/BibliographicResource_3000118436165/canvas/p1"
            }
          ],
          "otherContent": [
            {
              "@id": "https://iiif.europeana.eu/presentation/9200396/BibliographicResource_3000118436165/annopage/1"
            }
          ]
        },
        ...
      ]
    },
    ...
  ]
}

Retrieving full-text

The term full-text is meant to refer to the combination of the textual representation of the digital object plus where parts of the text is present in the original image (represented as annotations). In the EDM profile, the textual representation of the digital object 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 Page (ie. image). It is referred to by the Manifest and can be accessed via the following request.

Request

https://iiif.europeana.eu/presentation/[RECORD_ID]/manifest

Response

The response is a JSON-LD structure composed of the following fields:

Example: Requesting an Annotation Page in v2.1.

Request:

https://iiif.europeana.eu/presentation/9200396/BibliographicResource_3000118436165/annopage/1

{
  "@context": [ "http://iiif.io/api/presentation/3/context.json", "https://www.europeana.eu/schemas/context/edm.jsonld" ],
  "id": "https://iiif.europeana.eu/presentation/9200396/BibliographicResource_3000118436165/annopage/1"
  "type": "AnnotationPage",
  "items": [
    // full text annotation with no language
    {
      "id": "http://data.europeana.eu/annotation/9200356/BibliographicResource_3000100331503/a4cbbc7a0dc6b056c7bc0",
      "type": "Annotation",
      "motivation": "transcribing",
      "dcType": "Block",
      "body": {
        "id": "http://data.europeana.eu/fulltext/9200356/BibliographicResource_3000100331503/XPTO#char=0,10"
      },
      "target": [ 
        "https://iiif.europeana.eu/presentation/9200356/BibliographicResource_3000100331503/canvas/p1#xywh=13,0,16,10"
      ]
    }
    , ... 
  ]
}

Fulltext Resource

The edm:FullTextResource represents the transcription of a single page of a Newspaper. A full-text resource can be accessed separately from the Annotation List that it is associated to using the following method.

Request

https://www.europeana.eu/api/fulltext/[RECORD_ID]/[FULLTEXT_ID]

Response

The response is a JSON-LD structure composed of the following fields:

Example: Requesting a full-text resource.

Request:

https://www.europeana.eu/api/fulltext/9200396/BibliographicResource_3000118435063/8ebb67ccf9f8a1dcc2ea119c60954111

{
  "@context": "https://www.europeana.eu/schemas/context/edm.jsonld",
  "id": "http://data.europeana.eu/fulltext/9200396/BibliographicResource_3000118435063/8ebb67ccf9f8a1dcc2ea119c60954111"
  "type": "FullTextResource",
  "language": "nl",
  "value": "… De ondergeteekende sedert veie jaren drukker van het met Uit. Oetober 11. vervallene Nieuw A. H. _ E. Blad, heeft de eer te berigten, dat hij, bewogen met het lot van eene menigte huisge zinnen die daardoor plotseling bij den naderenden winter hun be staan hebben verloren, besloten heeft tot de uitgaaf eener nieuwe courant onder de benaming van: Het Amsterdamsche Handels- en Effectenblad. en dat hij daartoe de voorloopige medewerking heeft verkregen van belangstellenden, die van oordeel zijn, dat het bestaan van een dagblad als het gewezen Nieuw A. H. _- E. 81. voor het algemeen … "
}

Searching on full-text

The full-text can also be searched using a separate Search API while the Newspapers Thematic Collection is in MVP. It supports the same functionality as the main API but under the following endpoint and with the addition of 2 search fields and 1 profile as described below. For more information on the other methods, see the Search API documentation.

Request

https://newspapers.eanadev.org/api/v2/search.json

Example: Searching on full-text and showing hit highlighting.

Request:

https://newspapers.eanadev.org/api/v2/search.json?query=paris&profile=hits&wskey=APIKEY

{
  "apikey": "api2demo",
  "success": true,
  "requestNumber": 999,
  "itemsCount": 12,
  "totalResults": 439085,
  "items": [ ... ],
  "hits": [
    {
      "scope": "/9200303/BibliographicResource_3000059897585",
      "selectors": [
        {
          "field": "rdf:value",
          "exact": "pāri",
          "prefix": "Vi sai mūsu lielajai valstij partijas XVIII kon ferencei par godu gājis ",
          "suffix": " varens sociālis tiskās sacensības vilnis. "
        }
      ]
    },
    ...
  ]
}

Accessing images in high resolution: downloading data

To foster the reuse of the data that is published in Europeana as part of the Newspapers Thematic Collections, we make both the metadata and the full-text available for bulk download as compressed zip files. The metadata is available as CC0 the same way as all the metadata exposed via the API (see Terms of Use) while the full-text is available as Public Domain Mark.

List of datasets

The table below lists all the datasets that are published and available for download. If you are looking for the complete text of a Newspaper then we suggest using the (4) option, as opposed to using (3) where the trascription is partioned per page.

Given the fact that the files are very big and can take many hours to download, as an alternative to download directly via the browser, you can login to the FTP server at "download.europeana.eu" with username "anonymous". This will allow you to resume if the download gets stuck.

Legend:

1. The original metadata in EDM XML format before being ingested into Europeana. There are slight differences between this data and the one published. For more information see the /wiki/spaces/EF/pages/2385313809.

2. The full-text encoded using ALTO (Analyzed Layout and Text Object) as it was delivered to Europeana. The ALTO is an open XML Schema meant to describe text coming from OCR and layout information of pages for digitized material. For more information see the official documentation page at the Library of Congress.

3. The full-text encoded using the EDM profile for IIIF fullltext after being preprocessed for publication in Europeana. A note that as opposed to the format used by the API (ie. JSON-LD), the data is in RDF/XML as it is the format used for ingestion into Europeana.

4. Very similar to (3) but wih the full-text represented at the Issue level. This means that the edm:FullTextResource will convey the complete transcription of the Newspaper.

Dataset structure

On each compressed zip file, there will typically be a file per each item (ie. metadata or issue level full-text) or page (ie. ALTO and page level full-text) with the following structure:

That structure can be translated into links to the Europeana Collection portal where the item can be displayed or into the several APIs described on this page.

Changelog

As mentioned in the introduction, the IIIF APIs are made up of several distinct APIs, each one with its own project in GitHub and changelog as listed below.