Introduction# IIIF (International Image Interoperability Framework) is an international standard for image delivery widely used in digital archives and museum collections. The IIIF Content Search API allows you to search annotations (notes and tags) within manifests.
However, the IIIF Content Search API typically assumes server-side implementation, and it has been considered difficult to implement on static sites (GitHub Pages, Vercel, Netlify, etc.).
In this article, I will introduce a method for implementing the IIIF Content Search API on the client side using Service Workers . This approach enables the use of search functionality in IIIF viewers such as Mirador even on static sites.
Challenge# How Traditional IIIF Search API Works# [ M i r a d o r ] → G E T / s e a r c h ? q = k e y w o r d → [ S e r v e r ] → S e a r c h p r o c e s s i n g → J S O N r e s p o n s e
The IIIF Content Search API requires an endpoint that receives query parameters (?q=search term) and returns search results in JSON. This assumes dynamic server processing.
Limitations of Static Sites# On static sites:
Dynamic responses based on query parameters cannot be returned Server-side search processing cannot be executed Only static JSON files can be served Solution: Request Interception with Service Workers# A Service Worker functions as a proxy positioned between the browser and the network. By leveraging this, we can intercept search requests and perform search processing on the client side.
Architecture# [ [ [ M S M i e i r r r a a d i d o G c o r E e r ] T F E R ] W e x e / o t e s i r c c p i k h u o i e t n D f r s e d i / ] t s s a s i p i t e n l t i a a e c r I y / I c I s n i h I s e t n F e a e d i a r r e n C r c c x o c h e . J n h / p j a t i t s v e r n o a n e d n S t s e c u x ( r S l . f i e t j i p a s s r t r o s c n t h ? q t A = i P k m I e e y f w o o o n r r l m d y a ) t Implementation# 1. Generating the Search Index (At Build Time)# First, generate a search index from annotation data.
f } u n c a } r } b c o n ) e ; u t n n e } ; t ' t t e i i s o n ) u @ y o n l o t t t t l m a c m t ; r c p t t d n a r e a o n a a a n o e a r - e t i x n t n n n r ? : n : l i s g n i e t g i o v i g { t E e e e t o s : u v t a f e ` c e ' n s a n r n . a a a s e t $ a x S t r e i s p a g t t I s : { n t e r c r e . u n e i i d t c v ' a i h a s f s n : o o : I a a a : r e - t o h o n n d n n s c s i e = r ( . a : I ` : n v I ' h : n S E { b n d $ o a d h I d e [ a o n a : { ` . s t n e e a ] c d o n o $ t I t d n x r ; h y . n ` p { a d p e t . c ( _ b o $ t o r } : x r j h a v o . { i p g # / ' i s I n a d m o o t e x , e n n l y o p n i t y i s d o u _ t t s o _ w i . e e l i i . n r h i l x = , a v o b s e = f e ( > n a n a . g $ . n a g t s s b i { i g n { u i . e a o a o t n a o b U s n n / h o g n a r e n a , t e , s l U o p a , e } r . i t U / l t / i r c } a s o l a / r e n } n m g a s / v a e r , a a n t c n s i _ h o n f r / p $ e e 2 t t { s g / i a a t i c o t n . o o n i n j n n s o o s } t ) n . o ` e c n x { $ a ` t { n , . a v j n a s n s o o _ n . i ' i n , d d } e ` x , } ` , Generated index.json:
{ } " " " " ] @ t t e c y o n { } o p t t n e a r " " " " " " " t " l i t l m a c m t e : E e e a o n a a a x n s x n t n n n r t " t " t g i o v i g " S r : " u v t a f e : e i : a a a s e t a e [ g t t I s " " r s " e i i d t : h c " こ " o o " I t h : の : n n : d " t I 画 " I " h p n 1 像 " : d " : t : d 2 は j " h t / e , 1 a " : t " p / x 6 " c t h : i " 世 , o " p t / i , 紀 m h : t / i の m t / p e f ゲ e t / : x . ッ n p e / a i テ t : x / m o ィ i / a e p / ン n / m x l a ゲ g e p a e p ン " x l m . i 地 , a e p c / 図 m . l o s で p c e m e す l o . / a 。 e m c c r " . / o a c , c c m n h o a / v / m n m a 2 / v a s / a a n / c n s i 1 o n f " n 1 e t t " s e a , t x t . t i j . o s j n o s / n o 1 " n " , " , , 2. Service Worker Implementation# Create a Service Worker that intercepts search requests and processes them on the client side.
c a } f } f } s } a } s s o s u u e ) s e e n y i } c c s r n c r n r } l c i } ; y c c c c c r } l l i S s L n f o o e e E c o e G c e ; H f o f n o o o o o e ) f f i e t o c r n n a t x t n t . . } e t t ' ' ' w } r } h } a . n e c n n n n n t h ; . . i a a ( e s s r u e i s u f m ) n i u @ @ @ i , e ) i ) n a s I ( v s s s s s u e a a f r s d f s t t t c r c o t r i a e m b a ) e o r c i t t ' t s ' ' m r } o ) t ' a m b a ) d d t n u e f t t t t t r a d d - c e u e u h n u n n l p n a e f ; r n n o d y h @ o o @ @ o e , n , s @ n a e f l d t r n u n d d d s h a s n a r r i I t n t ( t t f t a n ' p i t t u i t t s ' c : : t n t f t e E u e l t n q i i r r e E E e r e c r n e n n i e e o i e e r c G o e t f { t : e n y a r d y i o @ h y o c o e v r r . . c u n n e e n r v v a i c a t c s d d n x r n r n y h e r r e o e ' : p l c ' p v u t a r r p t h r r f e l c p r t e d d s s e s e e r n h r i h s p e e d s e m d ( t , : t e : r x r : e : e : e a r y r . e e a : e : e n e a e i r e e u p w : n n c d I c o I e o x x e e c a e e r : r m t e { ' s ' t c p s e s ' t : t t = p t s o y x x l o t t h e n h n n a n C x a u l x n y q s e a ' q ' : r : r : i e e : n u : i r r c L t h p n U t n R { L L - x d d r s = a ; r t i . t u u s t : u s e . o : ' t l o . r . h i n n o = r = s s e i i s e i l e c e c c e z e r = e r p S e c ' s r e n : r r t ' n m . a s e I a n h l e s ' s s w c x n o x h a h h S e n y > r r o e ' s : s u e n o : { . y s s s a b f e t w I m d a u a = D p C t t . a C d a C I = w e e d t y o n a h t A c l s t a ' e . . e : t e t v e I e W n r = w a o o e e j c a e d a n a . a Q r = ( , u ' s r t U n : t u r : r c n t m a c f e e n U F . i d l a e t n n n n s h c x S c d a i s r u i > { n , e c t r n L s l y A . n t a a r [ h o r n e R i t l . ` i x a s t e e e h e h e w t e c e e d h p l o a . t . n e t r r p c r , r t r L s n h e s $ t e e e r r e a e x a t h r s e i i R : , t y l s a n n : y g ( h . e s ( ( e c ( S e { c = ( n ( ( r . C i r ( ( y n n n e / a e e . n o t C . e r : e , ' e a l h e a u l u J t ' ' = c h a t e i i t g s / t r n m n t r o t t H n f v r u a a r r o t f S - i a h a c s n n = r I p i i ' g a o a y n e = i t e e c d n r c l a e o O T n c n I s h f p d d y c I o i o , t p t t . t x > t r t n h e d c h . d S r N y s t e n ( e e o e e q . o I n i n h ( a i m e t ' y c t s l h P o S e m . p t i w d i . t n x x u t n F s f L r t o o n ( , . h . r ( e R a r e a a s e a v e n g c s U , e e t e . i i n t t { a ' r e ' S e r i a r t t ' l a M x d e h e r r x e C ( i s = o ' i A n , e q / e q a g r c S r : l t a ( e t ( . l q y t x o r o t > n , v s n q u s a u m i c h e i ' e p i x ( i j , u . . t n e / ' I a T o ( u e e r e s n h ( a n ' , ' ( n U i n s e t t t q a , ( d t e t e e s a c s . } I i r g a , ) d r n d o i r o o e u p { , i x a v s t r h t g $ n n c i p ; e l d e n n y L L n e i o t t e t s c R ( e { d d h f p ( x ) e x ( d ) o o t s / n ' i n . h e r t u e e R y l e U ) x U ) e w w t s , , o t u / q e ( r x x e ( i = v r U r ; x { e e S U e n ) r i u q ' l ( , s r c > e l { r l ) r r e r a I l n e u q . i p e a n ) l ) ; C C a l r d = ) d s e ' p n q o s t s t ) ; a a r , c ] > ; e t s ) a d u n p i e ) { ; s s c h , x ( t t e e s o o l e e h r / { . e , h x r e n n f = ( ( e 1 j v n U y ( s / . > ) ) A s / s e u a r ) r e j s . . P u c o n r m l ; e D s k e t i I l o n t l ' e ) q a o i v r n t n ' . ) ; } ; u t n p e i c f s t ) r ` e a ' W n m l o ) e e { ; s ) a t ( u r x & q t , } i . ) d m { t & u . t w ; e a . e u { i a s t j u s r n i ( s r t l g t n o l , , ( U o n . ) n r ' s u r ) t m , e r e ; i a a l s l l r ) u ( i c ) l c z h ; t l e P s i d a ) e Q r ; n u a t e m s r s . y . c ) h l ) a a s i ( m ' ( q ) ' ) ) ) ) ; { 3. Service Worker Registration# Register the Service Worker when the application starts.
e } x p i } t } } r o f r e r c r y c c r c c r g t ( o e o o e a o e i ! n t { n n t t n t s a ( s u s s u c s u t s ' o r t o r h o r e y s l n l n l n r n e e r e ( e - c r . f e . t e . f i v w a g l r r e a i f i a l i o u r r l i u c r s s g e o r s f n e n e t ( ; r o e - c W ( ; r ' ) r ; s t o ' a I ( e i r S t I { ' a o k e i I R r n e r o F e c r v n g h r ' i S i - e c = e s s g i e a t w i n a r r . s W w c a t t n o a h t s e a r i i r v k t S o I i e e n I g r n r I a a v f F t i v i a S o s i c i e r g e l a ) n a e r ) o t W d c t o o : h { r r ' S s . k , e u s e r p e r e v p r r i o v r r c r i e o e t c g r W e e i ) o d W s ; r ' o t k ) r e e ; k r r e e ( r d ) . ' : r ) e ; P g r i o s m t i e s r e ( < ' b / o i o i l i e f a - n s > e a { r c h - s w . j s ' ) ; 4. Search Service Declaration in the Manifest# Declare the search service in the IIIF manifest.
{ } " " " " ] @ i t s c d y e { } o " p r n : e v " " " " " t " i @ @ @ p l e " : c c i t r a x h e o d y o b t t " " n " p f e " t M : t : e i l : p a e " l " : n [ x " : e : " / i t h " h / f " t " : " t e e : t S S t x s p e " e p a t " : a h a : m " h / r t r / p , t / c t c / l t e h p h i e p x S : i . : a e / w i c / m r / i f o / p i t . m i l i i h i i e c i i m i . e f n / a f c 1 . a n . o " i t p i i m , o h i f o / i / e s a s p s a e p r t p a i m e . i r / a s j / c s n e s s h e i n o e / a f t n a i r e a " r n c s t , c d h t i h e / " o / x 1 n 1 . / / j s 3 c s e / o o a c n n r o t " c n e , h t x " e t , x . t j . s j o s n o " n , " , 5. Usage with Mirador# Simply registering the Service Worker before initializing Mirador enables the standard search functionality.
i e } m x p p u } M o o s , i r r e r r t t E e [ a f g ] d { d f R i ) o e e e s ; r r f c g t M V e a t i e i i g u ( s r r e i l ( t I a w s t ) e I d e t r I o r e f = F r . r u > S S t I n e e i s I c { r a n x I t v r i F i i c t S o c h i e n e S a a e l r M W r i c i o v z h r r i a S a k c t e d e e i r o r W o v r o n i V r c i k e e e W w r o e ( r r ) k ( ; e { r m } a n f i r f o e m s t ' U @ r / l l i } b ) / r { e g i s t e r - i i i f - s e a r c h - s w ' ; Operation Flow# 1 2 3 4 5 6 7 8 9 1 . . . . . . . . . 0 . U S M U M G S S S R s e i s i E e t e e M e r r e r T r a a s i r v a r a v t r p r i d d i i c o a o c o t i c c h n d p e r y r i e s o e p i i i e r n W l e s f W n s s o o s e / o d i d r a n s r e e s i t k d i d i k x x s h e s n s t e . e g p e r e r j c e l t t a / s u n a p i h h s i o t e y a s e e s e n n e r s g e a t d a e r m s a r e i t t e a e r c r s i e h g n a c h c n d e i i r h / e f s f c i p e J i s t e h r n t t a n e e s e d s c v a r t b q e h a I r e o u x t e S I c d a x e . h d c I h n s j e r F d t s ( i r o r c p C e d n e a t o s e ? q c n u t q u h t l e = e e e t c m s d n s t a t ) t s p S t e h a e r c s h e a A r P c I h f s o e r r m v a i t c e Benefits and Limitations# Benefits# Item Description Static site compatible Works on GitHub Pages, Vercel, Netlify, etc. No server required Everything is completed on the client side Low cost No server maintenance costs Fast Index is cached in the browser No Mirador modification needed Standard Mirador works as-is
Limitations# Item Description Index size Initial loading may take time for large collections HTTPS required Service Workers only work in HTTPS environments (localhost is an exception) Browser support Not supported in IE11 (all modern browsers are supported) Full-text search limitations Cannot achieve the same precision as advanced full-text search engines
Handling Large Collections# When the index size becomes large, the following measures are effective:
Index splitting : Split the index per manifestLazy loading : Fetch the index only when searchingCompression : Reduce file size with gzip compressionc o n I s n t d e i x n d U e R x L U r p l e r = m ` a / n i i i f i e f s / t $ { s i t e I d } / 3 / $ { i t e m I d } / s e a r c h - i n d e x . j s o n ` ; Summary# By leveraging Service Workers, the IIIF Content Search API can be implemented even on static sites. The key points of this approach are:
Generate search index at build time Intercept requests with Service Worker Execute search on the client side Return responses in IIIF standard format This enables providing search functionality on static sites without modifying IIIF viewers like Mirador. Please consider this as an option for providing a rich search experience while keeping costs low with a serverless approach when building digital archives.
Reference Links#