Skip to content

Images and IIIF

The images are on the museum's image server and are fetched with IIIF, an international standard for sharing images from museums and archives. With IIIF you can ask for exactly the size and crop you need, instead of downloading the whole file.

When to use what?

You want to … Use
show an image on a web page primaryImage.imageUrl (1200 pixels wide)
choose size, crop or rotation yourself iiifService with the IIIF Image API
show the work in a IIIF viewer with zoom (Mirador, Universal Viewer) The IIIF manifest
find images by content Semantic search, not IIIF

IIIF gives images and structure, not search. You find the works with Find works.

Three parts of IIIF

  • Image API: the image itself, in the size and crop you ask for (iiifService).
  • Presentation API: the manifest, which brings together the work's images and metadata for a viewer.
  • Image viewer: a program that reads the manifest. You do not need to write code to zoom.

Step 1: Find the image

Every work has primaryImage (the main image) and multimedia[] (all published images).

import os import requests

API = "https://api.nasjonalmuseet.no/api/v1" headers = {"X-API-Key": os.environ["NM_API_KEY"]}

work = requests.get(f"{API}/objects/NG.M.00939", headers=headers, timeout=30).json() image = work["primaryImage"] print("Image, 1200 px wide:", image["imageUrl"]) print("IIIF Image API:", image["iiifService"])

A crop: upper left quadrant, 600 px wide

print("Crop:", f"{image['iiifService']}/pct:0,0,50,50/600,/0/default.jpg") print("IIIF manifest (for viewers):", f"{API}/iiif/manifest/{work['nmId']}.json")

Step 2: Build a IIIF address

A IIIF Image address has five parts after iiifService:

{iiifService}/{region}/{size}/{rotation}/{quality}.{format}
Example Gives
/full/1200,/0/default.jpg The whole image, 1200 pixels wide
/full/max/0/default.jpg The whole image in full resolution
/pct:0,0,50,50/600,/0/default.jpg Upper left quadrant, 600 pixels wide
/square/300,/0/gray.jpg Square crop in greyscale, 300 pixels

Step 3: Open the manifest in a viewer

The manifest is open, without a key, because image viewers cannot send their own headers:

curl -s "https://api.nasjonalmuseet.no/api/v1/iiif/manifest/NG.M.00939.json"

Paste the address (https://api.nasjonalmuseet.no/api/v1/iiif/manifest/NG.M.00939.json) into Mirador or Universal Viewer, and you can zoom into the image.

Common mistakes

  • imageUrl is null: the image has no file in the image archive. Skip it.
  • Images are not the same as rights. That an image can be fetched does not mean it is free to reuse. See Terms of use.
  • Large images: full/max can be very large (gigapixel images). Ask for the width you need.