Understand 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 is 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

A single response doesn’t 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:

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

InstantSearch.js handles these cases with minimal configuration.

Ranking information

By default, the search response doesn’t include ranking information to keep the response as small as possible. To include the ranking information, use the getRankingInfo parameter with your search request.

For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "_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
      }
  }
}