Add IIIF Content Search when you have trustworthy, coordinate-bearing text (from OCR, HTR, or aligned transcription) and users who need to find words inside an object and see them highlighted on the page. Skip it when your text layer is unreliable, your collection is small, or your audience only browses images — the cost of generating and serving located annotations only pays off at scale and quality.

What problem does Content Search solve?

The IIIF Content Search API answers one question: "where on these pages does my term appear?" A viewer such as Mirador sends a query and gets back annotations with xywh coordinates, drawing highlight boxes over the matching words. It is scoped to a single manifest — one book, one map series, one register — not the whole repository.

GET https://search.example.org/iiif/ms-123/search?q=pestilence

Response (Content Search v2 shape):

{
  "@context": "http://iiif.io/api/search/2/context.json",
  "id": "https://search.example.org/iiif/ms-123/search?q=pestilence",
  "type": "AnnotationPage",
  "items": [
    {
      "type": "Annotation",
      "motivation": "highlighting",
      "target": "https://example.org/iiif/ms-123/canvas/12#xywh=842,1190,210,46"
    }
  ]
}

When does it genuinely fit?

Adopt content search when most of these are true:

• You have word-level coordinates (ALTO or hOCR from OCR, or coordinate-aligned HTR).
• Your character error rate is low enough that searches return real hits, not noise.
• Objects are long enough that in-page search beats scrolling (registers, codices, ledgers).
• Your viewer audience expects "find on page" behaviour.

When should you not add it?

Signal	Better choice
OCR CER above ~15%	Improve OCR first; bad search erodes trust
Fewer than ~50 short objects	Manual browse or a flat full-text page
Users want cross-collection discovery	Build a Solr/Elasticsearch index instead
No coordinates, only plain text	A simple text view; defer search
No budget to run a query service	Static manifests with a downloadable transcript

Content search is the wrong tool for discovery across objects. That is a repository concern solved by a search index whose results deep-link into manifests.

How do coordinates get there in the first place?

The annotations come from your OCR/HTR output. Ask your engine for coordinate-bearing formats:

# Tesseract producing hOCR with bounding boxes
tesseract page_012.png page_012 -c tessedit_create_hocr=1 hocr

# Kraken producing ALTO with line and word coordinates
kraken -i page_012.png page_012.xml segment ocr -o alto

A build step then converts hOCR/ALTO word boxes into IIIF annotations keyed by canvas, which your search service queries at runtime. No coordinates means no highlighting — you can still return whole-canvas hits, but the experience is weak.

What does the serving side cost?

You need a query endpoint that takes q and returns an AnnotationPage of hits. In practice that is a thin layer over Solr or Elasticsearch, or a purpose-built service. Plan for: an index build pipeline, storage for per-word annotations (these can outweigh the images in row count), and a service to keep running. For a 10,000-page collection that is real infrastructure, not a static file.

A decision checklist before committing

• [ ] Is my OCR/HTR accurate enough that searches are useful, not embarrassing?
• [ ] Do I have word- or line-level coordinates (ALTO/hOCR)?
• [ ] Are objects long enough that in-page search adds value?
• [ ] Can I run and maintain a query service indefinitely?
• [ ] Do I actually need within-object search, or cross-collection discovery?

If you cannot tick the first two boxes, fix OCR before touching Content Search.

Key Takeaways

• Content Search is per-manifest, in-page search with highlighting — not collection-wide discovery.
• It requires coordinate-bearing text from OCR/HTR (ALTO or hOCR) to be useful.
• Poor OCR makes content search actively harmful to user trust; fix accuracy first.
• It is overkill for small or image-only collections.
• Cross-collection discovery is a separate Solr/Elasticsearch concern.
• Budget for an ongoing query service and a sizeable annotation store, not just a static file.

Frequently Asked Questions

What does the IIIF Content Search API actually do?

It lets a viewer search the text of a single object (a manifest) and receive back annotations with coordinates, so matches are highlighted as boxes on the page image. It searches within one object, not across a whole collection.

Do I need OCR or transcription before adding content search?

Yes. Content search returns hits located on the image, so you must have word-level coordinates from OCR/HTR or aligned manual transcription. Without coordinates you can search text but cannot highlight it on the page.

Is IIIF Content Search the same as a collection-wide search?

No. Content Search is scoped to one manifest. Cross-collection discovery needs a separate search index (Solr, Elasticsearch) that links results back to manifests; the two are complementary, not interchangeable.

When is content search not worth the effort?

Skip it when your OCR is too poor to trust, when the corpus is tiny, or when users only browse visually. The annotation infrastructure and coordinate alignment cost outweighs the benefit for small or image-only collections.

What backend do I need to serve Content Search?

A service that accepts a q parameter and returns an AnnotationList (v1) or AnnotationPage (v2) of hits with xywh coordinates. Common choices are a thin layer over Solr, or tools like the SimpleAnnotationServer and Digirati's text services.

Does content search work without word coordinates?

You can return whole-canvas hits without precise boxes, but the experience is poor. Word- or line-level xywh coordinates are what make in-page highlighting useful, so generate them during OCR with ALTO or hOCR output.

Related reading

• When to Annotate images with IIIF
• Link TEI transcriptions to IIIF: A Practical Guide
• When to Use the IIIF Change Discovery API
• Measuring CER and WER for OCR quality
• Improving OCR accuracy on old print