Reverse Image Search

Search by image

import { searchByImage } from "@agntn/web";

const matches = await searchByImage("https://example.com/image.jpg", {
  provider: "serpapi",
  maxResults: 5,
});

for (const match of matches) {
  console.log(match.pageUrl, match.imageUrl, match.imageWidth, match.imageHeight);
}

This is its own capability, not a text search with a URL stuffed into the query. A provider without image lookup gets ImageSearchNotSupportedError, not a fake query it would answer with garbage. searchImageProviders() lists the ones that have it. Right now that is SerpAPI, which goes through Google Lens.

interface ImageSearchResult {
  pageUrl: string; // the page that shows the image
  imageUrl: string; // the matched image
  title: string;
  provider: string;
  source?: string;
  thumbnailUrl?: string;
  imageWidth?: number;
  imageHeight?: number;
  thumbnailWidth?: number;
  thumbnailHeight?: number;
  position?: number;
  exactMatch?: boolean;
}

Page and image stay separate on purpose. A match says where the image appears and which file matched, and never pretends those are the same thing.

What the URL must be

The image URL goes to the provider as is. So it has to be public, absolute, http or https, and it should not carry credentials or private query tokens, because the provider will fetch it and you just handed them the token. EmptyImageUrlError and InvalidImageUrlError cover the blank and malformed cases before any request leaves.

What stays out

Uploads, hosting, OCR, embeddings, perceptual hashes, local image analysis. None of it is here. Lookup by URL fits because it is a thin adapter over a search API. The rest drags in heavy dependencies and belongs in an image or vision package of its own.