Skip to main content
The /similar endpoint finds documents that are semantically close to a reference document. Once you have configured an embedder, you can use it to build recommendation features such as “More like this”, “Related items”, or “You might also like”.
This guide requires a configured embedder. If you haven’t set one up yet, see the hybrid search getting started guide.

​
Create an index with embeddings

Create an index called movies and add this movies.json dataset to it. If necessary, consult the getting started for more instructions on index creation. Then configure an OpenAI embedder: 
curl \
  -X PATCH 'MEILISEARCH_URL/indexes/movies/settings/embedders' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  --data-binary '{
    "movies-text": {
      "source": "openAi",
      "apiKey": "OPENAI_API_KEY",
      "model": "text-embedding-3-small",
      "documentTemplate": "A movie titled {{doc.title}} whose plot is: {{doc.overview}}"
    }
  }'
Replace MEILISEARCH_URL, MEILISEARCH_KEY, and OPENAI_API_KEY with the corresponding values in your application. Meilisearch will start generating embeddings for all documents. Use the returned taskUid to track the progress of this task.

​
Find a reference document

To recommend similar items, you first need a reference document. This is typically the item a user is currently viewing. For this example, search for “batman”: 
curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  --data-binary '{
    "q": "batman",
    "hybrid": {
      "semanticRatio": 0.5,
      "embedder": "movies-text"
    }
  }'
The top result is the movie “Batman” with id 192. Use this as the reference document.

​
Retrieve similar documents

Pass the reference document’s id to the /similar endpoint, specifying your embedder: 
curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/similar' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_KEY' \
  --data-binary '{
    "id": 192,
    "embedder": "movies-text"
  }'
Meilisearch returns the 20 documents most similar to the reference movie. Display these as recommendations to your users.

​
Use cases

  • E-commerce: “Customers also viewed” or “Similar products” on product detail pages
  • Content platforms: “Related articles” or “More like this” alongside the current content
  • Media streaming: “Because you watched X” recommendations based on the current title

​
Next steps

Choose an embedder

Compare embedding providers and pick the right one for your use case.

Personalized search

Combine recommendations with personalized search for a tailored experience.

Similar documents API reference

Full API reference for the /similar endpoint.