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 except the additional information fields at the root 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 word 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 second position within the best matching attribute (1 = position 2). Recall that word position only concerns ordered attributes. For unordered attributes, firstMatchedWord will always be an even number, divisible by thousand (0, 1000, 2000, etc.), that is, there will be no remainder. This is because the position of the match doesn’t matter in the ranking, Algolia always considers it to be in the first position. See Understanding word position for more information.

  • 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 record, 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, synonyms, or both.

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

  • filters (integer): This field is reserved for advanced usage, such as Optional filters’ scoring. 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.

  • personalization (object): If personalization has been enabled, this parameter details if the item has been re-ranked by an affinity score.

• 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. If true, the facet counts are approximated.

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

  • appliedRules (array): An array of rule objectIDs for all query rules applied to the search.

Examples

Get ranking information 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
5
val query = query("query") {
    getRankingInfo = true
}

index.search(query)

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)
  )
}

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