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.

JSON

Generate mock data Open in Formatter

{
  "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

queryrequiredstringThe search query string submitted by the user.

tookrequirednumberTime in milliseconds the search engine took to execute.

totalHitsrequirednumberTotal matching documents before pagination.

hits[].scorerequirednumber (0–1)Relevance score — higher means more relevant to the query.

hits[].highlightoptionalobjectFields with query terms wrapped in <em> tags for UI highlighting.

facetsoptionalobjectAggregated filter options with counts for each selectable value.

facets.<name>[].valuerequiredstringFilter option identifier shown in the UI.

facets.<name>[].countrequirednumberNumber of results that match this filter value.

Variants

No resultsEmpty search response — useful for handling the zero-results state in UI

No results

Generate mock data Open in Formatter

{
  "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

One click loads this exact example into the tool — no copy-paste needed. Format it, validate it, explore the tree, or generate TypeScript types instantly.

Format Validate Explore tree Generate TypeScript 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.AI & LLMEmbedding Vector ResponseEmbeddings API response with the vector array, model, and usage.