The /similar route uses AI-powered search to return a number of documents similar to a target document.

Meilisearch exposes two routes for retrieving similar documents: POST and GET. In the majority of cases, POST will offer better performance and ease of use.

​
Get similar documents with POST

POST
/indexes/{index_uid}/similar

Retrieve documents similar to a specific search result.

​
Path parameters

NameTypeDescription
index_uid *Stringuid of the requested index

​
Body

ParameterTypeDefault valueDescription
idString or numbernullIdentifier of the target document (mandatory)
embedderStringnullEmbedder to use when computing recommendations. Mandatory
attributesToRetrieveArray of strings["*"]Attributes to display in the returned documents
offsetInteger0Number of documents to skip
limitInteger20Maximum number of documents returned
filterStringnullFilter queries by an attribute’s value
showRankingScoreBooleanfalseDisplay the global ranking score of a document
showRankingScoreDetailsBooleanfalseDisplay detailed ranking score information
rankingScoreThresholdNumbernullExclude results with low ranking scores
retrieveVectorsBooleanfalseReturn document vector data

​
Example

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"
  }'

​
Response: 200 OK

{
  "hits": [
    {
      "id": "299537",
      "title": "Captain Marvel"
    },
    {
      "id": "166428",
      "title": "How to Train Your Dragon: The Hidden World"
    }
    {
      "id": "287947",
      "title": "Shazam!"
    }
  ],
  "id": "23",
  "processingTimeMs": 0,
  "limit": 20,
  "offset": 0,
  "estimatedTotalHits": 3
}

​
Get similar documents with GET

GET
/indexes/{index_uid}/similar

Retrieve documents similar to a specific search result.

​
Path parameters

NameTypeDescription
index_uid *Stringuid of the requested index

​
Query parameters

ParameterTypeDefault valueDescription
idString or numbernullIdentifier of the target document (mandatory)
embedderString"default"Embedder to use when computing recommendations. Mandatory
attributesToRetrieveArray of strings["*"]Attributes to display in the returned documents
offsetInteger0Number of documents to skip
limitInteger20Maximum number of documents returned
filterStringnullFilter queries by an attribute’s value
showRankingScoreBooleanfalseDisplay the global ranking score of a document
showRankingScoreDetailsBooleanfalseDisplay detailed ranking score information
rankingScoreThresholdNumbernullExclude results with low ranking scores
retrieveVectorsBooleanfalseReturn document vector data

​
Example

curl \
  -X GET 'MEILISEARCH_URL/indexes/INDEX_NAME/similar?id=TARGET_DOCUMENT_ID&embedder=EMBEDDER_NAME'

​
Response: 200 OK

{
  "hits": [
    {
      "id": "299537",
      "title": "Captain Marvel"
    },
    {
      "id": "166428",
      "title": "How to Train Your Dragon: The Hidden World"
    }
    {
      "id": "287947",
      "title": "Shazam!"
    }
  ],
  "id": "23",
  "processingTimeMs": 0,
  "limit": 20,
  "offset": 0,
  "estimatedTotalHits": 3
}

Was this page helpful?