Skip to main content
The Search API lets you integrate Doofinder’s search capabilities directly into your application. It handles full-text search, autocomplete, image-based search, visually similar products, and session-level event tracking. Current version: v6 (recommended)
Search API v5 is deprecated. If you are still on v5, migrate to v6 — paths changed from /5/search to /6/{hashid}/_search and the API now includes POST support, image search, and visually similar endpoints.

​
Base URL

Replace {search_zone} with your zone (eu1, us1, ap1).

​
Authentication

The Search API uses the standard Doofinder API key. The zone prefix is optional:
Generate keys in the Admin Panel.

​
Endpoints

Search

GET/POST /6/{hashid}/_search — Full-text search with filters, facets, sorting, and grouping.

Suggestions

GET /6/{hashid}/_suggest — Autocomplete terms as the user types.

Image Search

POST /6/{hashid}/_image_search — Search by image (base64-encoded).

Visually Similar

GET /6/{hashid}/_visually_similar — Find visually similar products by dfid.

​
Session & Event Tracking

Sending session events is required for accurate stats and improved ranking via behavioral signals.

Init Session

PUT /6/{hashid}/stats/init — Start a user session before the first search.

Click

PUT /6/{hashid}/stats/click — Log when a user clicks a search result.

Add to Cart

PUT /6/{hashid}/stats/cart/{session_id} — Log items added to cart.

Redirect

PUT /6/{hashid}/stats/redirect — Log when a user follows a redirect rule.

​
Key Concepts

​
hashid

Every Doofinder search engine has a unique identifier called hashid (32-character hex string). All Search API paths include it:
Find your hashid in the Admin Panel under Configuration → Search Engines — hover over any engine to copy its hashid.

​
Indices

A search engine can have multiple indices (e.g. product, page, category). By default, all indices are searched. Use the indices[] parameter to restrict to one or more:

​
session_id and user_id

Track user sessions and identities to enable personalization and accurate analytics:
If you’re calling this API directly from your own backend, rather than through Doofinder’s JS layer, forward your end user’s real IP address on every request, using one of X-Real-IP or X-Forwarded-For. Without one of these headers, every request from your integration will appear to come from your server’s single static IP address. Repeated requests from that one static IP can be flagged as bot traffic, which silently drops the affected search and click/session stats from your reports. It also skews any geographic breakdown in your stats, since it will be based on your server’s location instead of your end users’ locations.

​
Filters and Facets

​
Filter parameters

Narrow results by field values. Term filters accept arrays; range filters use gte, lte, gt, lt:
URL-encode brackets: [ → %5B, ] → %5D. For complex filters, use the POST variant and send a JSON body:

​
Facet aggregations

Request aggregations to power filter UI:
The response includes term counts and range min/max for each requested facet.

​
Multiprice Format

Doofinder supports multiple prices per product (e.g. for different currencies or customer groups). Index your items with price fields named using the convention price_{name} (e.g. price_eur, price_usd, price_member). To filter by a specific price field:
To sort by a specific price:
The price_name parameter in the Recommendations API body accepts the currency code (e.g. "EUR") to format prices in the response.

​
Grouping and Variants

When your catalogue has product variants (e.g. different sizes/colors of the same product), use grouping to collapse them into a single result:

​
Query Types

Doofinder automatically picks the best query strategy, but you can override it with query_name: The response always includes query_name so you can see which strategy was used.