> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Understand the API response

> Learn more about the Algolia API response

export const SearchRequest = () => <Tooltip tip="A search request is a single HTTP call to the Algolia Search API that can run one or more search operations. It can include multiple queries, for example, when querying several indices at once.">
    search request
  </Tooltip>;

Algolia search responses look similar to:

```json JSON icon="braces" theme={"system"}
{
  "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 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`.

<Note>
  InstantSearch.js handles these cases with minimal configuration.
</Note>

## 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`](/doc/api-reference/api-parameters/getRankingInfo) parameter with your <SearchRequest />.

For example:

```json JSON icon="braces" theme={"system"}
{
  "_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
    }
  }
}
```

For more information, see [Search API response](/doc/rest-api/search/search-single-index#response-hits)