URI Parameters

The Image API allows for taking a source image, applying URL parameters to extract a region of that image, and then doing some further basic image manipulation. We'll go through the parameters here. (And you can learn more about the order of implementation later.)

Parameters Template

The URI for a IIIF image is made of defined parts to allow for human readability as well as machine processability.

You can see more details of the Image Request URI Syntax in the specification.

Let's construct our first IIIF URI together. We'll break it down into the base URI and then the parameters that can manipulate the image.

Don't worry if you're not certain what everything does yet. We'll show a detailed example next.

Open up a text editor to construct your image URL.

Base URI

The base URI includes only the scheme, server, prefix (optional), and identifier. The server and prefix are going to be institution specific. The server and prefix make the whole base URI a globally unique identifier.

This base URI is what is used to identify the resource (think linked data). We will see an example of this in a bit when we look at the info.json.

Any time you want an image at a particular size or some part of an image you'll start off with this base URI.

Scheme

Scheme is the first part of the base URI. This is the http or https part of the URL.

The strong recommendation is that images be served over HTTPS in order to be able to be used within other HTTPS pages. If an image served over HTTP is included in a page served over HTTPS then browsers will complain about mixed content.

We'll use https to start our URI:

Server

The (sub)domain where the images or image server lives. We'll extend our URI with an image server:

Prefix

The prefix is optional but can be useful if the server hosts other services that need to live at different paths.

In this case we will add iiif to the path:

Identifier

This is whatever identifier you want to use. The combination of the scheme+server+prefix and the identifier should be unique in the world.

The identifier muse be URI encoded if it includes spaces or slashes.

Parameters that Manipulate the Image

Everything after the identifier are parameters that allow you to request the specific version of the image you want. These are the parts that IIIF specifies and all implementations share.

Region

Region allows for returning the full image or any part of the image.

Size

Adding 400, will scale the image down to 400 pixels wide and will scale the height proportionally.

Rotation

In this case we will set this to 0 to not rotate the image at all.

Quality

The quality parameter allows for delivering a color image in gray or bitonal.

Format

The format is like a file extension and allows for requesting various formats like a JPEG or a PNG.

Here we'll require a JPEG:

URI Segments

So going back to our IIIF Image URI template here are the parameters and the values we've given to each.

Our Example

You've now created your first IIIF image URL!

https://iiif.lib.ncsu.edu/iiif/segPap_021/full/400,/0/default.jpg