Get similar documents with POST

Retrieve documents similar to a reference document identified by its id.

Useful for “more like this” or recommendations.

POST /indexes/{indexUid}/similar

cURL

cURL

curl \
  -X POST 'MEILISEARCH_URL/indexes/INDEX_NAME/similar' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \
  --data-binary '{
    "id": TARGET_DOCUMENT_ID,
    "embedder": "EMBEDDER_NAME"
  }'

200

{
  "hits": [
    {
      "id": 2770,
      "title": "American Pie 2",
      "poster": "https://image.tmdb.org/t/p/w1280/q4LNgUnRfltxzp3gf1MAGiK5LhV.jpg",
      "overview": "The whole gang are back and as close as ever. They decide to get even closer by spending the summer together at a beach house. They decide to hold the biggest…",
      "release_date": 997405200
    },
    {
      "id": 190859,
      "title": "American Sniper",
      "poster": "https://image.tmdb.org/t/p/w1280/svPHnYE7N5NAGO49dBmRhq0vDQ3.jpg",
      "overview": "U.S. Navy SEAL Chris Kyle takes his sole mission—protect his comrades—to heart and becomes one of the most lethal snipers in American history. His pinpoint accuracy not only saves countless lives but also makes him a prime…",
      "release_date": 1418256000
    }
  ],
  "id": "143",
  "offset": 0,
  "limit": 2,
  "estimatedTotalHits": 976,
  "processingTimeMs": 35
}

Authorizations

Authorization · string · header · required

An API key is a token that you provide when making API calls. Read more about how to secure your project.

Include the API key to the Authorization header, for instance:

-H 'Authorization: Bearer 6436fc5237b0d6e0d64253fbaac21d135012ecf1'

If you use a SDK, ensure you instantiate the client with the API key, for instance with JS SDK:

const client = new MeiliSearch({
  host: 'MEILISEARCH_URL',
  apiKey: '6436fc5237b0d6e0d64253fbaac21d135012ecf1'
});

Path Parameters

indexUid · string · required

Unique identifier of the index.

Body

application/json

Request body for similar document search

id · string · required

Document ID to find similar documents for

embedder · string · required

Name of the embedder to use for semantic similarity

offset · integer

Number of documents to skip

Required range: x >= 0

limit · integer

Maximum number of documents returned

Required range: x >= 0

filter · any

Filter queries by an attribute's value

attributes_to_retrieve · string[] | null

Attributes to display in the returned documents

retrieve_vectors · boolean

Return document vector data

show_ranking_score · boolean

Display the global ranking score of a document

show_ranking_score_details · boolean

Adds a detailed global ranking score field

show_performance_details · boolean

Adds a detailed performance details field

ranking_score_threshold · number<double>

Excludes results with low ranking scores

Response

200

application/json

The documents are returned.

Option 1

Option 2

Response containing similar documents

hitsPerPage · integer · required

Number of results on each page

Required range: x >= 0

page · integer · required

Current search results page

Required range: x >= 0

totalPages · integer · required

Exhaustive total number of search result pages

Required range: x >= 0

totalHits · integer · required

Exhaustive total number of matches

Required range: x >= 0

hits · object[] · required

Results of the query

Show child attributes

id · string · required

Document ID that was used as reference

processingTimeMs · integer · required

Processing time of the query in milliseconds

Required range: x >= 0

performanceDetails · any

Performance details of the query