Image Search

Image (visual) search takes one image source and returns matching products. In the browser use the SearchApp’s imageSearch method; for SSR use the standalone fetchImageSearch.

Prerequisite: the search app is registered (.use(search())), your app is wrapped in <GloodProvider>, and https://search.glood.ai is in your CSP connectSrc. See Installation.

1. Get the image as a `data:` URL

Pass exactly one source: image (base64 or a data: URL) or imageUrl (an http(s) URL, fetched server-side). From a file input, convert to a data: URL:

const toDataUrl = (file: File) =>
  new Promise<string>((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(reader.result as string);
    reader.onerror = reject;
    reader.readAsDataURL(file);
  });

2. Run the search

Retrieve the SearchApp via useGloodAnalytics().getApp('search') and call imageSearch:

import { useState } from 'react';
import { useGloodAnalytics, type SearchItem } from '@glood/hydrogen';

export function ImageSearch() {
  const app = useGloodAnalytics()?.getApp('search');
  const [products, setProducts] = useState<SearchItem[]>([]);

  async function onFile(e: React.ChangeEvent<HTMLInputElement>) {
    const file = e.target.files?.[0];
    if (!file || !app) return;
    const res = await app.imageSearch({ image: await toDataUrl(file), pagination: { limit: 24 } });
    setProducts(res.products);
  }

  return (
    <div>
      <input type="file" accept="image/jpeg,image/png,image/webp" onChange={onFile} />
      <div className="grid">
        {products.map((p) => (
          <a key={p.product_id} href={`/products/${p.handle}`}>
            <img src={p.image?.url} alt={p.title} loading="lazy" />
            <span>{p.title}</span>
          </a>
        ))}
      </div>
    </div>
  );
}

Params are an ImageSearchParams; res is an ImageSearchResponse and each product is a SearchProduct.

imageSearch always runs against the app’s controlEndpoint (non-edge) — the vision pipeline isn’t available on regional edges. This routing is automatic; see Configuration → Edge vs. non-edge routing.

3. Image constraints

Images are validated server-side; anything outside these returns 400:

Rule	Value
Format	`jpeg`, `png`, `webp` only
Size	1 KB – 5 MB
Dimensions	100×100 to 4096×4096 px

4. From a URL, or on the server

Pass imageUrl instead of image to search by a hosted image, and use fetchImageSearch when you don’t have a React component (loaders, mobile backends):

import { fetchImageSearch } from '@glood/hydrogen';

const res = await fetchImageSearch(
  { apiKey: context.env.GLOOD_API_KEY, myShopifyDomain: 'your-store.myshopify.com' },
  { imageUrl: 'https://example.com/photo.jpg', pagination: { limit: 24 } },
);

5. Attribution

Attribute clicks with search_type: 'image' via the SearchApp track helpers (trackResultClick), each taking a SearchTrack:

app.trackResultClick({
  search_type: 'image',
  source: 'image_search',
  products: [{ product_id: p.product_id }],
});

For Developers

1. Get the image as a `data:` URL

2. Run the search

3. Image constraints

4. From a URL, or on the server

5. Attribution

See also

​1. Get the image as a data: URL

​2. Run the search

​3. Image constraints

​4. From a URL, or on the server

​5. Attribution

​See also

1. Get the image as a `data:` URL

2. Run the search

3. Image constraints

4. From a URL, or on the server

5. Attribution

See also