This is a beta version of migrating these workshop materials to a new platform. If you run into issues please file an issue or click on the edit link above and submit a pull request. You can use the previous version of the workshop materials as a fallback.

Content Search Query Interface

We’ve previously seen what needs to be added to a manifest to enable search inside. On this page we’ll cover how the client forms a query using the information from the manifest.

Query Parameters

http://iiif.io/api/search/1.0/#query-parameters

Parameter Definition
q A space separated list of search terms.
motivation A space separated list of motivation terms.
date A space separated list of date ranges.
user A space separated list of URIs that are the identities of users.

q

The q parameter allows for searching within the next of an annotation.

motiviation

It is possible to narrow results by the motivation of the annotation.

Motivation Definition
painting Only annotations with the sc:painting motivation
non-painting Annotations with any motivation other than sc:painting
commenting Annotations with the oa:commenting motivation
describing Annotations with the oa:describing motivation
tagging Annotations with the oa:tagging motivation
linking Annotations with the oa:linking motivation

Example

So an example of a search query would be like the following. It is as simple as adding a q parameter to the URI for the search service.

https://ocr.lib.ncsu.edu/search/segPap_003?q=amazon

Note that this particular implementation ignores all parameters other than q.

Query Response

To understand a search query response, you need to look at the relationship between resources and hits.

The hits are the search results. There are a number of features that are possible with hits but the main property to focus on are the annotations. The list of annotations are identifiers that refer to the @id of one of the listed resources.

A resource is an embedded annotation. (This is a performance optimization instead of having to make additional requests for many annotations.) The value of the on property for the annotation is a canvas. This can either be the full canvas or a region of the canvas using a spatial media fragment (xywh). The use of the xywh fragment then allows for a client to highlight just the text that matches the query.

To allow for painting an annotation onto a particular region of the canvas to highlight the search match, a search server would need to know the bounding box for the match. In some cases this might be the individual word or the line or paragraph the word is in.

Autocomplete

http://iiif.io/api/search/1.0/#autocomplete

The autocomplete service works similarly. Here’s an example URI for autocomplete:

https://ocr.lib.ncsu.edu/search/segPap_003?q=ama

The terms list returns the matches that can be provided as search suggestions.