Search

GET /indexes/{indexUid}/search

Api key

Search for documents matching a specific query in the given index.

This route should only be used when no API key is required. If an API key is required, use the POST route instead.

Path parameters

indexUid string Required

Index Unique Identifier

Query parameters

q string

Query string.

Default value is "".
attributesToRetrieve string

Comma-separated list of attributes whose fields will be present in the returned documents. Defaults to the displayedAttributes list which contains by default all attributes found in the documents.

Default value is *.
attributesToHighlight string

Comma-separated list of attributes whose values will contain highlighted matching terms. Highlighted attributes are returned in _formatted response object.
highlightPreTag string

Specify the tag to put before the highlighted query terms.

Default value is <em>.
highlightPostTag string

Specify the tag to put after the highlighted query terms.

Default value is </em>.
attributesToCrop string

Comma-separated list of attributes whose values have to be cropped. Cropped attributes are returned in _formatted response object.
cropMarker string

Sets the crop marker to apply before and/or after cropped part selected within an attribute defined in attributesToCrop parameter.

Default value is ….
cropLength integer

Sets the total number of words to keep around the matched part of an attribute specified in the attributesToCrop parameter.

Default value is 10.
facets string

Comma-separated list of attributes whose fields will be distributed as a facet. If you have set up filterableAttributes, you can retrieve the count of matching terms for each facets.Learn more about facet distribution in the dedicated guide
filter
Attribute(s) to filter on.

Can be made of 3 syntaxes
- Nested Array: ["something > 1", "genres=comedy", ["genres=horror", "title=batman"]]
- String: something > 1 AND genres=comedy AND (genres=horror OR title=batman)
- Mixed: ["something > 1 AND genres=comedy", "genres=horror OR title=batman"]
_geoRadius({lat}, {lng}, {distance_in_meters}) and _geoBoundingBox([{lat, lng}], [{lat}, {lng}]) built-in filter rules can be used to filter documents within geo shapes.

Attribute(s) used in filter should be declared as filterable attributes. See Filtering and Faceted Search.
offset number

Number of results to skip.

Default value is 0.
sort string

Fields on which you want to sort the results.

Attribute(s) used in sort should be declared as sortable attributes. See Sorting.

_geoPoint({lat}, {long}) built-in sort rule can be used to sort documents around a geo point.
limit number

Maximum number of results to return.

Default value is 20.
page number

Sets the specific results page.

Default value is 1.
hitsPerPage number

Sets the number of results returned for a query. If hitsPerPage is not provided as a query parameter, this parameter is ignored.

Default value is 20.
showMatchesPosition boolean

Defines whether an _matchesPosition object that contains information about the matches should be returned or not.

Default value is false.
matchingStrategy string

Defines which strategy to use to match the query terms within the documents as search results. Two different strategies are available, last and all. By default, the last strategy is chosen.

Values are last or all. Default value is last.

Responses

• 200 application/json

Ok
Hide response attributes Show response attributes object
- hits array[object] Required
  
  Hide hits attributes Show hits attributes object
  
  _formatted object
  
  Only present if attributesToHighlight/attributesToCrop is not empty. Return highlighted and cropped fields.
  
  Hide _formatted attribute Show _formatted attribute
  
  Additional properties are allowed
  
  _matchesPosition object
  
  Only present if showMatchesPosition = true. Array of all search query occurrences in all fields.
  
  Hide _matchesPosition attribute Show _matchesPosition attribute
  
  Starting position and length in bytes of the matched term in the returned value
  
  Hide attributes Show attributes
  
  start integer Required
  
  length integer Required
  
  Additional properties are NOT allowed
  
  _rankingScore number
  
  Only present if showRankingScore = true. The ranking score of that document.
  
  _rankingScoreDetails object
  
  Only present if showRankingScoreDetails = true. The ranking score of each ranking rule for that document.
  
  Hide _rankingScoreDetails attribute Show _rankingScoreDetails attribute
  
  The ranking score per ranking rule.
  
  Hide attributes Show attributes
  
  words object
  
  Hide words attributes Show words attributes
  
  order integer Required
  
  The order that this ranking rule was applied
  
  matchingWords integer Required
  
  number of words in the query that match in the document. The higher the better.
  
  maxMatchingWords integer Required
  
  max number of words in the query that can match in the document for this iteration of the words ranking rule.
  
  score number Required
  
  The relevancy score of a document according to a ranking rule and relative to a search query. Higher is better.
  
  1.0 indicates a perfect match, 0.0 no match at all (Meilisearch should not return documents that don't match the query).
  
  typo object
  
  Hide typo attributes Show typo attributes
  
  order integer Required
  
  The order that this ranking rule was applied
  
  typoCount integer Required
  
  The number of typos to correct in the query to match that document.
  
  maxTypoCount integer Required
  
  The maximum number of typos that can be corrected in the query to match a document.
  
  score number Required
  
  The relevancy score of a document according to a ranking rule and relative to a search query. Higher is better.
  
  1.0 indicates a perfect match, 0.0 no match at all (Meilisearch should not return documents that don't match the query).
  
  proximity object
  
  Hide proximity attributes Show proximity attributes
  
  order integer Required
  
  The order that this ranking rule was applied
  
  score number Required
  
  The relevancy score of a document according to a ranking rule and relative to a search query. Higher is better.
  
  1.0 indicates a perfect match, 0.0 no match at all (Meilisearch should not return documents that don't match the query).
  
  attribute object
  
  Hide attribute attributes Show attribute attributes
  
  order integer Required
  
  The order that this ranking rule was applied
  
  attributeRankingOrderScore number Required
  
  Score computed depending on the first attribute each word of the query appears in.
  
  The first attribute in the searchableAttributes list yields the highest score, the last attribute the lowest.
  
  queryWordDistanceScore number Required
  
  Score computed depending on the position the attributes where each word of the query appears in.
  
  Words appearing in an attribute at the same position as in the query yield the highest score. The greater the distance to the position in the query, the lower the score.
  
  score number Required
  
  The relevancy score of a document according to a ranking rule and relative to a search query. Higher is better.
  
  1.0 indicates a perfect match, 0.0 no match at all (Meilisearch should not return documents that don't match the query).
  
  exactness object
  
  Hide exactness attributes Show exactness attributes
  
  order integer Required
  
  The order that this ranking rule was applied
  
  matchType string Required
  
  One of exactMatch, matchesStart or noExactMatch.
  
  exactMatch: the document contains an attribute that exactly matches the query.
  
  matchesStart: the document contains an attribute that exactly starts with the query.
  
  noExactMatch: any other document.
  
  matchingWords integer
  
  for noExactMatch, the number of exact words contained in an attribute. The higher the better.
  
  maxMatchingWords integer
  
  for noExactMatch, the maximum number of exact words contained in an attribute
  
  score number Required
  
  The relevancy score of a document according to a ranking rule and relative to a search query. Higher is better.
  
  1.0 indicates a perfect match, 0.0 no match at all (Meilisearch should not return documents that don't match the query).
  
  Additional properties: object
  
  Custom rule in the form of either attribute:direction, vectorSort(vector) or _geoPoint(lat, lng):direction.
  
  Hide Additional properties: attributes Show Additional properties: attributes
  
  order integer Required
  
  The order that this ranking rule was applied
  
  value string | number | point Required
  
  The value that was used for sorting this document
  
  distance number
  
  The distance between the target point and the geoPoint in the document
  
  similarity number
  
  the similarity score between the target vector and the value vector.
  
  1.0 means a perfect similarity, 0.0 a perfect dissimilarity.
  
  attribute string | number
  
  Retrieve attributes of a search result. attributesToRetrieve controls these fields.
  
  _geoDistance number
  
  Using _geoPoint({lat}, {lng}) built-in sort rule at search leads the engine to return a _geoDistance within the search results. This field represents the distance in meters of the document from the specified _geoPoint.
  
  Additional properties are allowed
- offset integer
  
  Number of documents skipped.
- limit integer
  
  Number of returned documents.
- estimatedTotalHits integer
  
  Estimated number of candidates for the search query.
- page integer
  
  The specific search results page to fetch.
- hitsPerPage integer
  
  Number of returned results per page.
- totalHits integer
  
  Exhaustive total number of search results for the search query.
- totalPages integer
  
  Number of navigatable results pages for the search query.
- facetDistribution object
  
  Distribution of the given facets.
  
  Hide facetDistribution attribute Show facetDistribution attribute
  
  Additional properties: object
  
  Hide Additional properties: attribute Show Additional properties: attribute
  
  Additional properties: integer
- facetStats object
  
  When using the facets parameter, the distributed facets that contain some numeric values are displayed in a facetStats object that contains, per facet, the numeric min and max values of the hits returned by the search query. If none of the hits returned by the search query have a numeric value for a facet, this facet is not part of the facetStats object.
  
  Hide facetStats attribute Show facetStats attribute
  
  Additional properties: object
- processingTimeMs integer Required
  
  Processing time of the query.
- query string Required
  
  Query originating the response.
- Additional properties are NOT allowed
• 401 application/json

Unauthorized
Hide response attributes Show response attributes object
- message string Required
- code string Required
- type string Required
- link string Required
• 404

Not Found

GET /indexes/{indexUid}/search

curl \
 -X GET https://example.meilisearch.com:7700/indexes/movies/search \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Response examples (200)

{
  "hits": [
    {
      "id": 25684,
      "title": "American Ninja 5",
      "poster": "https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg",
      "overview": "When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.",
      "release_date": 725846400,
      "_formatted": {
        "id": 25684,
        "title": "American Ninja 5",
        "poster": "https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg",
        "overview": "When a scientists daughter is kidnapped, American <em>Ninja</em>, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the <em>ninja</em>.",
        "release_date": 725846400
      },
      "_matchesPosition": {
        "overview": [
          {
            "start": 49,
            "length": 5
          },
          {
            "start": 155,
            "length": 5
          }
        ]
      }
    }
  ],
  "facetDistribution": {
    "genres": {
      "action": 273,
      "animation": 118,
      "adventure": 132,
      "fantasy": 67,
      "comedy": 475,
      "mystery": 70,
      "thriller": 217
    }
  },
  "facetStats": {
    "price": {
      "min": 1,
      "max": 4999.99
    }
  },
  "limit": 0,
  "offset": 0,
  "estimatedTotalHits": 0,
  "query": "string",
  "processingTimeMs": 0
}

Response examples (401)

{
  "message": "The Authorization header is missing. It must use the bearer authorization method.",
  "code": "missing_authorization_header",
  "type": "auth",
  "link": "https://docs.meilisearch.com/errors#missing_authorization_header"
}