Skip to content

IIIF english version

Jump to bottom
David Haskiya edited this page Jul 28, 2023 · 11 revisions

Swedish version

The National Archives publish publiclly available digitized archival items using IIIF (International Image Interoperability Framework). IIIF is a collection of protocols for the management and publishing of digital media, primarily images, but also video and sound. The National Archives IIIF service supports

In the IIIF standards are also

There is currently no roadmap for implementing the latter in the National Archives IIIF service.

The National Archives service Search the collections use IIIF Image and IIIF Presentation, e.g. page spread from Bergshammars vapenbok. IIIF Image provides zooming and panning of images, IIIF Presentation provides browsing related media and presentation of metadata using in an embedded instance of Universal Viewer. The IIIF APIs make it possible to view the media in other viewing services, e.g. Universal Viewer example.

IIIF Image

The Image API has methods for processing source images. The National Archives IIIF Service implements compliance level 1, supporting the methods which are not italicized:

  • Cropping (full, square, x/y/width/height, percent x/y/width/height)
  • Scaling (max, width, width, width & height, width/height with upscaling, width/height with limit)
  • Rotation (0, "rotationBy90s", arbitrary angle, mirroring)
  • Colour quality (original, colour, greyscale, bitonal)
  • Image format (jpeg, png, tif, gif, pdf, jp2, webp)

The National Archives IIIF service also supports IIIF Image 2.0, e.g. for use in image viewers which do not support IIIF Image 3.0, like Universal Viewer.

Request

All requests use HTTP GET.

Response

The response to all IIIF Image calls have content-type: image/jpeg. Incorrect calls get status code:

  • 400 BadRequest, incorrect parameters
  • 403 Forbidden, the image has no rights statement
  • 404 Not Found, missing image
  • 429 Too many requests, the client has exceeded the rate limit, the headers X-RateLimit-xxx specify the limit and the time when the reuest may be repeated
  • 501 Not Implemented, not implemented method

Proxy for IIIF Image

External services using a IIIF image viewer, like Universal Viewer or Mirador, can take advantage of using a reverse proxy so that the image view will not call the National Archives IIIF Image API endpoint directly.

The National Archives log the users' IP address for statistics use, se the terms of service. Since the IIIF Image API requests come from the user's web browser, the log will thus list the end user's IP address if the image viewer uses the National Archives API endpoint directly. With a reverse proxy the log will list the proxy server's IP address instead. This has several advantages:

  • The external service does not need to notify the end users that their IP address will be logged for statistics
  • The National Archives' statistics will be more accurate if all IIIF Image traffic from an external service is logged aggregated under the proxy server's IPadress
  • The developer of the external service can set up their own statistics using the logging in the proxy server

A reverse proxy can be set up with eg. Apache HTTP Server or Nginx.

Example: reverse proxy using Apache HTTP Server

Example: reverse proxy using Nginx

Version 3.0

https://lbiiif.riksarkivet.se/{image id}/{region}/{size}/{rotation}/{colour model}.jpg https://lbiiif.riksarkivet.se/v3/{image id}/{region}/{size}/{rotation}/{colour model}.jpg

For a complete description of the URI syntax see version 3.0

Parameter Description
region Desired crop of the image: "full" eller "x-start,y-start,width,height"
size Desired image size in pixels: "max", "width, height", "width," or ",height"
rotation Desied rotation of the image: "0", "!0", "90", "!90", "180", "!180", "270" or "!270", where the number specifies the angle (in even 90 degrees intervals) and ! specifies mirroring
colour model The service supports "default" only

Version 2.0

https://lbiiif.riksarkivet.se/v2/{bild-id}/{region}/{size}/{rotation}/{colour model}.jpg

För en fullständig beskrivning av URI-syntax se version 2.0.

Parameter Beskrivning
region Desired crop of the image: "full" or "x-start,y-start,width,height"
size Desired image size in pixelse: "full", "width, height", "width," or ",height"
rotation Desired rotation of the image: "0", "!0", "90", "!90", "180", "!180", "270" or "!270", where the number specifies the angle (in even 90 degrees intervals) and ! specifies mirroring
colour model The service supports "default" only

IIIF Image request examples

Image format (format)

Support for "jpg" only.

Colour model (quality)

Support for "default" only.

"Region" / Crop

Example, "full" (complete image): http://lbiiif.riksarkivet.se/arkis!R0001216_00005/full/max/0/default.jpg

Example, "square" (centered square): http://lbiiif.riksarkivet.se/arkis!R0001216_00005/square/max/0/default.jpg

Example, crop based on absolute pixel coordinates: http://lbiiif.riksarkivet.se/arkis!R0001216_00005/300,300,100,100/max/0/default.jpg

"Size" / Scaling

Fixed width scaling: http://lbiiif.riksarkivet.se/arkis!R0001216_00005/full/300,/0/default.jpg

Fixed height scaling: http://lbiiif.riksarkivet.se/arkis!R0001216_00005/full/,500/0/default.jpg

Fixed width and height scaling (changes image aspect): http://lbiiif.riksarkivet.se/arkis!R0001216_00005/full/500,300/0/default.jpg

Rotation

No rotation (0): http://lbiiif.riksarkivet.se/arkis!R0001216_00005/full/max/0/default.jpg

Rotation 90 clockwise: https://lbiiif.riksarkivet.se/arkis!R0001216_00005/full/max/90/default.jpg

Rotation 90 clockwise and mirrored: https://lbiiif.riksarkivet.se/arkis!R0001216_00005/full/max/!90/default.jpg

IIIF Presentation

The Presentation API serves resources which enables the presentation of images and audiovisual media (sound and video), with attached metadata in a client application (web site, app, etc.) There are two types of resources at the top level:

  • Manifest, which contain references media files (image, sound, video) och metadata for these
  • Collection, which contains references to subordinate Collections and Manifests, creating a hierarchical structure

Request

All requests use HTTP GET.

The Presentation API uses a simple URL syntax.

Manifest

https://lbiiif.riksarkivet.se/{identifier}/manifest

Collection

The National Archives provide a Collection structure to enable external client to browse the manifests.

Top level collection: https://lbiiif.riksarkivet.se/collection/riksarkivet

The top level Collection contains references to the following parallell sortings/hierarchies:

More sortings will be added, e.g. Place.

Response

The response to all IIIF Presentation calls have content-type: application/json. Incorrect calls get status code:

  • 400 BadRequest, incorrect parameter (identifier)
  • 403 Forbidden, the manifest has no rights statement or is unavailable by API for other reasons
  • 404 Not Found, missing resource
  • 429 Too many requests, the client has exceeded the rate limit, the headers X-RateLimit-xxx specify the limit and the time when the reuest may be repeated

The responses are JSON-LD documents, i.e. RDF models, serialized in JSON format, for example: https://iiif.io/api/presentation/3.0/#b-example-manifest-response. There are several open source viewing applications for IIIF manifests, e.g.

Internal references

At the lowest level, primarily corresponding to archival records of the type series, a Collection contains references to Manifests, which correspond to archival record of the type volume or map/drawing. Internal references, to volumes in other series (See: in the search service), are included in the items list if they refer within the same archive. References to volumes in other archives are displayed in the search service but are not included in IIIF Collections because of technical limitations.

The content and structure of presentation resources are described in the Presentation API specification.

CORS

The IIIF service does not automatically set the response header

Access-Control-Allow-Origin: *

as this does not work with the National Archives search service. An API client which needs the CORS header can include the request header

Origin: https://domain.tld

and get the response header

Access-Control-Allow-Origin: https://domain.tld

Using a reverse proxy for the IIIF service, a default response header can be configured:

Access-Control-Allow-Origin: https://domain.tld

or

Access-Control-Allow-Origin: *

for all proxied responses. See reverse proxy using Apache HTTP Server and reverse proxy using Nginx for examples of configuration.

Rights

The IIIF Presentation and IIIF Image APIs give access to data for open (not confidential) archival content which is older 110 years.

IIIF Presentation manifests and IIIF Image are available for media with explicit license statements. Setting license statements is a work in progress.

Find image id from archival record/pid

Archival records on all levels (fonds, series, volume, photo, map/drawing etc.) have a persistent identifier (pid) which can be used to construct a link to the archival record's presentation in the searh service. For example: 2Yz2ClKdn2VMeUXQcoZOO6 can be used for an URL https://sok.riksarkivet.se/arkiv/2Yz2ClKdn2VMeUXQcoZOO6 which links to the presentation of the volume SE/RA/2113/2113.2/1, [Diplomatica Muscovitica Cosacica] 1654-1721, the ukrainian constitution of Pylyp Orlyk. This volume is digitized, to find the URI of the IIIF Manifest, you can read the volume as a IIIF Collection with https://lbiiif.riksarkivet.se/collection/arkiv/2Yz2ClKdn2VMeUXQcoZOO6:

{
  "id": "https://lbiiif.riksarkivet.se/collection/arkiv/2Yz2ClKdn2VMeUXQcoZOO6",
  "type": "Collection",
  "label": {
    "sv": [
      "1 (1654-1721) - Handlingar rörande förhandlingar mellan Sverige oc..."
    ]
  },
  "summary": {
    "sv": [
      "Referenskod: SE/RA/2113/2113.2/1",
      "Arkivinstitution: ",
      "Datering: 1654-1721"
    ]
  },
  "items": [
    {
      "id": "https://lbiiif.riksarkivet.se/arkis!R0000480/manifest",
      "type": "Manifest",
      "label": {
        "sv": [
          "1 (1654-1721) - R0000480 - Handlingar rörande förhandlingar mellan Sverige oc..."
        ]
      }
    }
  ]
}

The URI of the IIIF Manifest is found under "items".

Code example (Python)

Riksarkivet

Clone this wiki locally