JSONKit
API Design

Search API Response JSON Example

A real-world JSON example of a search API response in the style of Algolia and Elasticsearch — including hit scoring, highlighted snippets, faceted filters, and pagination metadata.

{
  "query": "wireless headphones",
  "took": 18,
  "totalHits": 1482,
  "page": 1,
  "perPage": 20,
  "totalPages": 75,
  "hits": [
    {
      "id": "prod_8421",
      "score": 0.97,
      "title": "Sony WH-1000XM5 Wireless Headphones",
      "brand": "Sony",
      "price": 349.99,
      "rating": 4.8,
      "reviewCount": 2841,
      "inStock": true,
      "highlight": {
        "title": "Sony WH-1000XM5 <em>Wireless Headphones</em>",
        "description": "Industry-leading noise cancellation in <em>wireless</em> over-ear <em>headphones</em>"
      }
    }
  ],
  "facets": {
    "brand": [
      {
        "value": "Sony",
        "count": 42
      },
      {
        "value": "Bose",
        "count": 31
      },
      {
        "value": "Apple",
        "count": 18
      }
    ],
    "priceRange": [
      {
        "value": "under-100",
        "count": 184
      },
      {
        "value": "100-300",
        "count": 612
      },
      {
        "value": "300-plus",
        "count": 686
      }
    ],
    "rating": [
      {
        "value": "4-and-up",
        "count": 891
      },
      {
        "value": "3-and-up",
        "count": 1244
      }
    ]
  }
}

Field Reference

querystringrequiredThe search query string submitted by the user.
tooknumberrequiredTime in milliseconds the search engine took to execute.
totalHitsnumberrequiredTotal matching documents before pagination.
hits[].scorenumber (0–1)requiredRelevance score — higher means more relevant to the query.
hits[].highlightobjectoptionalFields with query terms wrapped in <em> tags for UI highlighting.
facetsobjectoptionalAggregated filter options with counts for each selectable value.
facets.<name>[].valuestringrequiredFilter option identifier shown in the UI.
facets.<name>[].countnumberrequiredNumber of results that match this filter value.

Variants

No resultsEmpty search response — useful for handling the zero-results state in UI
No results
{
  "query": "abjkqwxyz",
  "took": 3,
  "totalHits": 0,
  "page": 1,
  "perPage": 20,
  "totalPages": 0,
  "hits": [],
  "facets": {},
  "suggestions": [
    "wireless headphones",
    "bluetooth speakers"
  ]
}

Common Use Cases

  • →Building a product search page with faceted filtering and sorting
  • →Mocking a search API for frontend development without an Elasticsearch cluster
  • →Implementing keyboard-navigable search result UIs with highlighted terms
  • →Designing the schema for a search microservice response contract
  • →Testing zero-results, single-result, and paginated result states
searchAlgoliaElasticsearchfacetsfull-text searchAPI

Validate or format this JSON

Paste the example above into JSONKit's tools to validate, minify, or explore the structure interactively.

Format →Validate →Minify →

Frequently Asked Questions

A facet is an aggregated count of filter options alongside search results. For example, searching 'headphones' returns a brand facet showing Sony: 42, Bose: 31 — letting users narrow results by clicking a filter without a new search. Facets are computed in a single query, not separate requests.

Elasticsearch uses BM25 (a probabilistic relevance model) to score documents. Factors include term frequency in the document, inverse document frequency (rare terms score higher), and field length normalization. You can boost specific fields — a match in 'title' scores higher than a match in 'description'.

Highlights let your UI show which part of a document matched the query, typically by wrapping matched terms in <em> tags. This helps users immediately see why a result appeared. You render the highlighted HTML string directly — never put user-supplied content in innerHTML without sanitizing it first.

It depends on the UX pattern. In 'conjunctive' filtering, selecting Sony under brand re-queries and all other facet counts update to reflect the narrowed set. In 'disjunctive' filtering, brand counts stay fixed so users can add multiple brands. Most modern search UIs use disjunctive filtering for facets within a group and conjunctive across groups.

Related JSON Examples

API DesignPagination ResponsePaginated list response JSON with offset, cursor, total, and navigation links.API DesignREST API ResponseGeneric REST API response wrapper with data payload, status, and pagination meta.E-commerceProduct ListingE-commerce product JSON with pricing, variants, images, and inventory fields.