Understand the API Response

Leveraging the API Response

Algolia search responses look something like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "hits": [
    {
      "firstname": "Jimmie",
      "lastname": "Barninger",
      "objectID": "433",
      "_highlightResult": {
        "firstname": {
          "value": "<em>Jimmie</em>",
          "matchLevel": "partial"
        },
        "lastname": {
          "value": "Barninger",
          "matchLevel": "none"
        },
        "company": {
          "value": "California <em>Paint</em> & Wlpaper Str",
          "matchLevel": "partial"
        }
      }
    }
  ],
  "page": 0,
  "nbHits": 1,
  "nbPages": 1,
  "hitsPerPage": 20,
  "processingTimeMS": 1,
  "query": "jimmie paint"
}

Hits

The most important field in the search response is hits, an array of objects matching the currently active search state.

Each hit contains the object’s retrievable attributes, those attributes that have been configured to be returned in search responses. Two additional fields may be present if highlighting and snippeting have been enabled:

• _highlightResult: an object keyed on the hit’s retrievable attributes; each key’s value returns a highlighted version of the original attribute, as well as information describing the quality of the match.
• _snippetResult: an object keyed on the hit’s retrievable attributes; each key’s value returns a snippeted version of the original attribute, as well as information describing the quality of the match.

If highlighting or snippeting has been enabled, the highlighted and snippeted values of firstname, for example, will be available as _highlightResult.firstname.value and _snippetResult.firstname.value, respectively. These values can then be used, instead of their original values, to support highlighting and snippeting in a results interface.

Pagination

Note that a single response does not return all hits - the hits are paginated, with the current pagination state reflected by a few response fields:

• nbHits: the total number of hits matching the search state
• nbPages: the total number of pages in the search response
• hitsPerPage: configurable; indicates how many hits are presented per page
• page: the current, zero-indexed page of responses

In a search interface, these fields can be used to render appropriate pagination controls. Roughly:

• Increment the desired page when a “Next” button is clicked, or a specific page when a numeral is clicked.
• Don’t show a “Next” button if page == nbPages.
• Don’t show a “Back” button if page == 0.

Keep in mind that this is only necessary when building a very customized experience; Algolia’s InstantSearch.js handles most use cases with minimal configuration.

Ranking Information

In the interest of keeping the response as small as possible, ranking information is not included in the response. However, if you would like to see why the engine has ranked each record, you can use the getRankingInfo parameter. This should only be used for troubleshooting, otherwise you are adding a lot more data to the response than necessary. Here’s an example.

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