This website uses cookies to ensure you get the best experience. By clicking or navigating the site you agree to allow our collection of information through cookies. More info

Europeana IIIF APIs

The International Image Interoperability Framework (IIIF) combines a set of APIs 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 Newspapers.

Before start using 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.

IIIF datasets in Europeana: A scholar’s delight

IIIF datasets in Europeana: A scholar’s delight

Since its conception in 2011, the international community of the International Image Interoperability Framework (IIIF) has taken important steps in improving the way cultural heritage institutions (CHIs) present images on their digital collections platforms.

See more
Building a rich media experience with the Europeana API and IIIF

Building a rich media experience with the Europeana API and IIIF

If you’re a developer wishing to use Europeana content with International Image Interoperability Framework (IIIF) services, this post guides you through this process. From first querying the API, to presenting images on a web page using a rich media viewer, find out how simple it is to make the most of IIIF.

See more

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.

APILast versionDescription
IIIF Manifest API0.3-alpha (2018-11-27)Supports only the retrieval of manifests.
IIIF Full-text API0.5 (2018-11-12)Supports the retrieval of full-text, both the Annotation Pages and Full-text resources.

Getting Started

Retrieving a Manifest

A manifest describes the information needed for a viewer to present a digital object to the user, such as the title and the sequence of views/images. 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. Presently, only the version 2.1 of the IIIF specification is supported but very soon also the v3 will become available.

Request

https://iiif.europeana.eu/presentation/[RECORD_ID]/manifest
ParameterDescription
RECORD_IDThe 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.

Response

ParameterDatatypeDescription
@contextString (URL)The URL of the JSON-LD context (always with the value "http://iiif.io/api/presentation/2/context.json").
@idString (URI)The canonical identifier of the Manifest.
@typeStringThe type of the resource. Always set to "sc:Manifest".
labelArray (LangObject)The title(s) of the Item.
descriptionArray (LangObject)The description(s) of the Item.
metadataMetadataA short list of metadata values.
thumbnailImageThe thumbnail as defined in the edm:preview of the record.
navDateString (xsd:dateTime)The issue date of the Newspaper Item.
attributionStringA human readable label that must be displayed when the item is displayed or used, presenting the copyright or ownership statements and an acknowledgement of the owning and/or publishing institution.
licenseString (URI)One of the rights statement defined for use in Europeana. It defines the copyright, usage and access rights that apply to this digital object.
logoString (URL)An image depicting the Europeana logo.
seeAlsoArray (Dataset).
sequencesArray (Sequence)An array containing one only sequence.
Sequence
@idString (URI)The canonical identifier of the Sequence.
@typeStringThe type of the resource. Always set to "sc:Sequence".
labelStringA label for the sequence. Always set to "Current Page Order".
startCanvasString (URI)The URI of the first canvas to be displayed. Typically the first page./td>
canvasesArray (Canvas)An ordered list of Canvases.
Canvas
@idString (URI)The canonical identifier of the Canvas.
@typeStringThe type of the resource. Always set to "sc:Canvas".
labelStringA label for the Canvas.
heightNumberThe height of the canvas which corresponds to the height of the image./td>
widthNumberThe width of the canvas which corresponds to the width of the image./td>
attributionStringA human readable label that must be displayed when the item is displayed or used, presenting the copyright or ownership statements and an acknowledgement of the owning and/or publishing institution.
licenseString (URI)One of the rights statement defined for use in Europeana. It defines the copyright, usage and access rights that apply to this digital object.
imagesArray (Annotation)A list of one annotation that represents the projection of the image into the canvas where it is displayed.
otherContentArray (Fulltext)A list of one reference to the Annotation Page that holds all the full-text for that Newspaper page.
Annotation (modelling construct used for painting media into a Canvas)
@idString (URI)The canonical identifier of the Annotation.
@typeStringThe type of the resource. Always set to "oa:Annotation".
motivationStringA motivation for the annotation, in this case declaring that the image will be projected (ie. "sc:painting") on to the Canvas.
resourceObject (AnnotationBody)The image resource being projected into the Canvas.
onString (URI)The identifier of the Canvas on which the image will be projected.
AnnotationBody
@idString (URL)The URL of the image.
@typeStringThe type of the resource. Always set to "dctypes:Image".
formatStringThe mimetype of the resource.
service (optional)Object (Service)The Service hosting and delivering the IIIF resource, when applicable.
Service
@contextString (URL)The URL of the JSON-LD context (always with the value "http://iiif.io/api/image/2/context.json").
@idString (URL)The URL of the IIIF service hosting/serving the resource.
profileString (URI)The URI of the version supported by the service.
Metadata
labelStringThe name of a metadata property. One of: date, format, relation, type, language, source.
valueArray (LangObject)The value of the metadata property.
Image
@idStringThe URL of the image, ie. thumbnail.
@typeStringThe type of the resource. Always set to "dctypes:Image".
widthNumberThe width of the image.
heightNumberThe height of the image.
Dataset
@idStringThe URL to the metadata in a specific format.
formatStringThe mimetype of the format.
profileURLThe url of the profile. Always set to "http://www.europeana.eu/schemas/edm/".

Example: Requesting a Manifest in v2.1

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]/annopage/[PAGE_ID]
ParameterDescription
RECORD_IDThe 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_IDThe number of the page in logical sequence starting with 1 for the first page. There can be pages that do not contain any text which will mean that the request will return a HTTP 404.

Response

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

ParameterDatatypeDescription
@contextArray of String (URL)The URL of the JSON-LD context (always with the values "http://iiif.io/api/presentation/3/context.json" and "https://www.europeana.eu/schemas/context/edm.jsonld").
idString (URI)The canonical identifier of the Annotation Page.
typeStringThe type of the resource. Always set to "AnnotationPage".
itemsArray (Annotation)An array containing all the Annotation that are part of this page.
Annotation
idString (URI)The canonical identifier of the Annotation.
typeStringThe type of the resource. Always set to "FullTextResource".
motivationStringThe motivation of the annotation, see reference for more information. Always set to "transcribing".
dcTypeStringRepresents the granularity level of the Annotation, reflecting levels such as: Page, Block, Line and Word.
bodyObject (Body)The reference to the transcribed text.
targetArray (String)A target can represent an image or just a part of it that is being annotated. For most annotations that are at a level of granularity lower than Page will point to the specific coordinates where the text is found on the image, using the Media Fragments specification.
Body
idString (URL)The url of the transcribed text (ie. full-text resource) in case of a Page level annotation, or a segment of the transcribed text using in this case the URI Fragment Identifiers for the text/plain Media Type specification.
language (optional)StringThe language of the segment of the transcription text being annotated. It is represented as a ISO 639 language code.

Example: Requesting an Annotation Page in v2.1.

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]
ParameterDescription
RECORD_IDThe 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_IDThe identifier of the full text resource.

Response

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

ParameterDatatypeDescription
@contextString (URL)The URL of the JSON-LD context (always with the value "https://www.europeana.eu/schemas/context/edm.jsonld").
idString (URI)The canonical identifier of the full-text resource.
typeStringThe type of the resource. Always set to "FullTextResource".
languageStringThe more predominante language of the transcription text represented as a ISO 639 language code. Parts of the text may be written in different languages. When that is the case, the language information will be indicated as part of the full-text Annotations.
valueStringThe transcription text.

Example: Requesting a full-text resource.

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
FieldsDatatypeDescription
fulltextTextAllows searching on the transcribed text (ie. full-text) of the item.
issuedDateA true date field reflecting the date of the Newspapers Issue.
ProfileDescription
hitsDisplays the mentions in the transcribed text where the search keyword was found.
ParameterDatatypeDescription
hit.fl (optional)List (String)A comma- or space-separated list of fields from which hit highlighting should be generated. A wildcard of “*” (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 “*”.
hit.selectors (optional)NumberSpecifies the maximum number of highlighted selectors (ie. snippets in Solr) to generate per result (ie. record). If omitted defaults to 1. It is possible for any number of selectors from 1 to this value to be generated, up to a limit of 10.

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

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

Download 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.

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.

Metadata1Full-text (ALTO)2Page level full-text (EDM)3Issue level full-text (EDM)4
9200300download (229M) (MD5)download (63G) (MD5)download (116G) (MD5)download (113G) (MD5)
9200301download (37M) (MD5)download (13G) (MD5)download (20G) (MD5)download (20G) (MD5)
9200338download (213M) (MD5)download (158G) (MD5)download (278G) (MD5)download (277G) (MD5)
9200339download (39M) (MD5)download (11G) (MD5)download (21G) (MD5)download (17G) (MD5)
9200355download (212M) (MD5)download (97G) (MD5)download (159G) (MD5)download (157G) (MD5)
9200356download (137M) (MD5)download (40G) (MD5)download (17G) (MD5)download (17G) (MD5)
9200357download (23M) (MD5)download (5G) (MD5)download (9G) (MD5)download (9G) (MD5)
9200396download (4M) (MD5)download (849M) (MD5)download (2G) (MD5)download (1G) (MD5)

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 EDM documentation page.
  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.

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:

ItemDATASET_ID/LOCAL_ID.xml
PageDATASET_ID/LOCAL_ID/PAGE_ID.xml

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.

top