getRankingInfo

About this parameter

Retrieve detailed ranking information.

This setting lets you see exactly which ranking criteria played a role in selecting each record.

Impact on the response:

When true, each hit in the response contains an additional _rankingInfo object, which contains the following fields, all at the same level.

• Textual relevance / Ranking

  • nbTypos (integer): Number of typos encountered when matching the record. Corresponds to the typos ranking criterion in the ranking formula.

  • firstMatchedWord (integer): Contains 2 pieces of information - the searchable attribute that best matched the query and the character position within that attribute.
    • To determine which attribute within the list of searchableAttributes was the best match, you need to divide the number by 1000: (int) (firstMatchedWord / 1000). For example, if firstMatchedWord=2001, (int) (2001/1000)=2, the best matching attribute is the 3rd one in the list of searchableAttributes (2 = position 3).
    • To calculate the character position within the best matching attribute, you need to extract the remainder of the division using the modulo function of your programming language, such as firstMatchedWord % 1000. For example, if firstMatchedWord=2001, (2001 % 1000)=1, the match began at the 2nd position within the best matching attribute (1 = position 2). Recall that character position only concerns unorderd attributes. For ordered attributes, firstMatchedWord will always be an even thousand (0, 1000, 2000, etc), that is, there will be no remainder. This is because the position of the match does not matter in the ranking, algolia will always consider it to be in the first position. For more on searchable attributes modifiers, go here.

  • proximityDistance (integer): The sum of the distances between matched words when the query contains more than one word. Corresponds to the proximity criterion in the ranking formula.

  • userScore (integer): Custom ranking for the object, expressed as a single numerical value. This field is internal to Algolia and shouldn’t be relied upon.

  • nbExactWords (integer): Number of exactly matched words. If alternativesAsExact is set, it may include plurals and/or synonyms.

  • words (integer): Number of matched words in the query, including prefixes and typos.

  • filters (integer): This field is reserved for advanced usage. It will be zero in most cases.

  • promoted (boolean): Present and set to true if a Rule promoted the hit.

• Geo search (see how these are used)

  • geoDistance (integer): Distance between the geo location in the search query and the best matching geo location in the record, divided by the geo precision.

  • geoPrecision (integer): Precision used when computed the geo distance, in meters. All distances will be floored to a multiple of this precision.

  • matchedGeoLocation (array): Contains the latitude, longitude, and distance (in meters) from a central axis point.

• Additional information

  • serverUsed (string): Actual host name of the server that processed the request. (Our DNS supports automatic failover and load balancing, so this may differ from the host name used in the request.)

  • indexUsed (string): Index name used for the query. In case of A/B testing, the index returned here is the one that was actually used, either index A (the target) or B (the variant).

  • abTestID (integer): In case of A/B testing, returns the ID of the A/B test.

  • abTestVariantID (integer): In case of A/B testing, returns the ID of the variant used. The variant ID is the position in the array of variants (starting at 1).

  • parsedQuery (string): The query string that will be searched, after normalization. Normalization includes removing stop words (if removeStopWords is enabled), and transforming portions of the query string into phrase queries (see advancedSyntax).

  • timeoutCounts (boolean): Whether a timeout was hit when computing the facet counts. When true, the counts will be interpolated (i.e. approximate). See also exhaustiveFacetsCount.

  • timeoutHits (boolean): Whether a timeout was hit when retrieving the hits. When true, some results may be missing.

Examples

Get ranking info along with search results

1
2
3
4
5
6
7
$results = $index->search('query', [
  'getRankingInfo' => true
]);

//foreach ($results['hits'] as $hit) {
//  var_dump($hit['_rankingInfo']);
//}

1
2
3
4
5
6
7
results = index.search('query', {
  getRankingInfo: true
})

# results['hits'].each do |hit|
#   puts hit['_rankingInfo']
# end

1
2
3
4
5
index.search('query', {
  getRankingInfo: true
}).then(({ hits }) => {
  console.log(hits.map(hit => hit._rankingInfo));
});

1
2
3
4
5
6
results = index.search('query', {
    'getRankingInfo': True
})

# for hit in results['hits']:
#   print(hit['_rankingInfo'])

1
2
3
4
5
6
7
8
let query = Query("query")
  .set(\.getRankingInfo, to: true)

index.search(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
index.search(
  new Query("query")
    .setGetRankingInfo(true)
);

1
2
3
4
index.search(
  new Query("query")
    .GetRankingInfo(true)
);

1
2
3
4
index.search(
  new Query("query")
    .setGetRankingInfo(true)
);

1
2
3
4
res, err := index.Search(
  "query",
  opt.GetRankingInfo(true),
)

1
2
3
4
5
6
client.execute {
  search into "myIndex" query Query(
    query = Some("query"),
    getRankingInfo = Some(true)
  )
}

1
2
3
4
5
val query = query("query") {
    getRankingInfo = true
}

index.search(query)

Which produces the following results:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  [...],
  "_rankingInfo": {
      "nbTypos": 0,
      "firstMatchedWord": 0,
      "proximityDistance": 0,
      "userScore": 7,
      "geoDistance": 1600,
      "geoPrecision": 1,
      "nbExactWords": 0,
      "words": 0,
      "filters": 0,
      "matchedGeoLocation": {
          "lat": 37.3688,
          "lng": -122.036,
          "distance": 1600
      }
  }
}