Zum Inhalt springen

Search

Visual search

https://searcio.com/api/v1

Die Dokumentation ist auf Englisch verfasst.

Auf dieser Seite

Let a shopper search by uploading a photo instead of typing. A vision model looks at the image and describes it with a handful of tags (colour, product type, material, style and so on), and those tags are then run as a normal search against the site's catalogue. This is not image similarity search: matching still happens on text, only on text the visitor never had to type.

The tags are written in the page's language, the one filter[lang] names, or else in the first of the site's languages, so they match the words of the catalogue they are searched in.

Base URL: https://searcio.com/api/v1/sites/{site}, or key-relative https://searcio.com/api/v1, where the site is resolved from the search key.

Authentication: the search key (?key=sk_… or X-Search-Key), as for GET /search, and works only on the site's own domain.


POST /search/visual

A multipart/form-data request carrying one file field.

Field Type Notes
photo file Required. An image, up to 8 MB.
type string (≤ 255) Only these content types, separated by commas, as on /search. Send type=product for a photo search in a shop, so pages do not come back.
filter[field] string, or a list The same filters as /search: a configured facet field or lang, as a query parameter beside key or as multipart fields. Send the page's filter[lang] on a multilingual shop; otherwise a photo taken on the English page also returns the German products.
key string The search key (or X-Search-Key).

The site must have visual search turned on; see the visual_search feature switch and AI visual tagging. Visual search and visual tagging are included in the same plans, but each has its own switch and its own monthly allowance.

Example

bash
curl -X POST "https://searcio.com/api/v1/sites/123/search/visual?key=sk_live_xyz" \
  -F "photo=@dress.jpg"

Response 200 OK

json
{
  "query": "red silk dress",
  "search_id": "9f1c2b7e-5f3a-4a1e-9d64-2f0c1b3a8e77",
  "tags": ["red", "silk", "dress"],
  "total": 1,
  "hits": [
    {
      "id": "p-1",
      "score": 4.2,
      "source": { "title": "Red Silk Dress", "type": "product", "url": "/products/red-silk-dress" },
      "highlight": null
    }
  ],
  "facets": {}
}

hits and facets have exactly the same shape as in GET /search, and search_id works the same way: send it to /search/click when a visitor opens a result. A photo search never triggers a search redirect: redirects match terms a visitor typed, and these tags are generated.

Empty results. When the vision model finds nothing worth tagging (a blurry photo, or one with nothing recognisable in it), the endpoint answers successfully with an empty result instead of an error:

json
{ "query": null, "tags": [], "total": 0, "hits": [], "facets": [] }

Render it like any search without results, with a "No matches, try another photo" message rather than an error banner.

Errors

Status When
401 Missing or invalid search key
403 Site disabled, Origin not the site's own domain, or visual search is not turned on for this site
422 photo is missing, is not an image, or exceeds 8 MB
429 Monthly visual search quota reached ({ "metric": "visual_searches", "limit": N }) or rate limited

The monthly quota is checked before the image is analysed, so a request over the quota never incurs the cost of the analysis. A successful photo search counts against both the visual search allowance and the site's normal search allowance, since a real catalogue search runs.


Frontend integration: a camera and upload button

This example needs no dependencies, only a file input, FormData and fetch. On a phone, capture="environment" opens the camera directly instead of the photo picker.

html
<input type="file" id="visual-search-input" accept="image/*" capture="environment" />
<ul id="visual-search-results"></ul>

<script>
  const KEY = 'sk_live_xyz';
  const BASE = 'https://searcio.com/api/v1/sites/123';

  const input = document.getElementById('visual-search-input');
  const results = document.getElementById('visual-search-results');

  input.addEventListener('change', async () => {
    const photo = input.files[0];
    if (!photo) return;

    results.innerHTML = '<li>Searching…</li>';

    const body = new FormData();
    body.append('photo', photo);

    const response = await fetch(`${BASE}/search/visual?key=${KEY}`, {
      method: 'POST',
      body,
    });

    if (!response.ok) {
      results.innerHTML = '<li>Sorry, that search failed. Try another photo.</li>';
      return;
    }

    const data = await response.json();

    if (data.hits.length === 0) {
      results.innerHTML = '<li>No matches for that photo - try a clearer shot.</li>';
      return;
    }

    results.innerHTML = data.hits
      .map((hit) => `<li><a href="${hit.source.url}">${hit.source.title}</a></li>`)
      .join('');
  });
</script>
  • No debouncing needed: the request is sent once per selected file, not per keystroke.
  • Put the search key in the query string, not in X-Search-Key: as with every endpoint called from the browser, CORS is resolved from ?key= (see CORS), so the request works whether or not the browser sends a preflight.
  • Degrade gracefully: hide the upload button when /storefront-config does not report visual search, so shoppers on a plan without it never see a control that could only answer 403.