Mock Search Results API

Q: Can I test an empty search state?

Yes. scenario=empty returns zero results, zero facets and exact zero-page metadata; a conflicting nonzero total is rejected.

MOCK DATA

Build deterministic mock search pages with exact pagination, relevance or date sorting, facets, highlights, empty states and suggestions.

Generated test data for fixtures and development

Base URL: /api/search-results
Category: Developer Tools
Capabilities: 1 route
Last updated: July 29, 2026

GET /api/search-results Build one deterministic mock search-results page Computed answer

Live requestRuns against the public API

No key required

GET

/api/search-results?query=cursor+pagination&total=137&page=2&pageSize=20&sort=relevance&asOf=2026-07-10T12%3A00%3A00.000Z

Request parameters

queryrequired

Original search text displayed to the user.

scenariodefault results

Return normal results, an exact empty state or a caller-supplied suggestion state.

suggestedQuery

Required, distinct alternative query for scenario=suggestion; invalid for other scenarios.

total

Total matching records. Defaults to 47; empty requires 0.

pagedefault 1

One-based page number; beyond-last pages return an honest empty slice.

pageSizedefault 10

Maximum results returned on this page.

sortdefault relevance

Sort by descending score, newest timestamp or oldest timestamp.

facetsdefault true

Include exact full-result category counts.

asOf

Replay anchor for synthetic updatedAt values; defaults to the request clock and is echoed.

Advanced response options4 options

fields

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

exclude

Return all fields except these (comma-separated).

prettydefault false

Pretty-print the JSON response.

unwrapdefault false

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples 13 params · 9 fields · 3 examples

Code samples Ready-to-copy requests in 4 languages

curl JavaScript Python PHP

curl "https://randomapi.dev/api/search-results?query=cursor%20pagination&total=137&page=2&pageSize=20&sort=relevance&asOf=2026-07-10T12%3A00%3A00.000Z"

const res = await fetch("https://randomapi.dev/api/search-results?query=cursor%20pagination&total=137&page=2&pageSize=20&sort=relevance&asOf=2026-07-10T12%3A00%3A00.000Z");
const { data, meta } = await res.json();

import requests

data = requests.get("https://randomapi.dev/api/search-results?query=cursor%20pagination&total=137&page=2&pageSize=20&sort=relevance&asOf=2026-07-10T12%3A00%3A00.000Z").json()["data"]

$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/search-results?query=cursor%20pagination&total=137&page=2&pageSize=20&sort=relevance&asOf=2026-07-10T12%3A00%3A00.000Z"
), true);
$data = $json["data"];

Parameters Route-specific request inputs 9

Parameter	Type	Default & allowed	Description
`query` required	string	allowed: 1 – 100 example: cursor pagination	Original search text displayed to the user.
`scenario`	enum	default: results allowed: results \| empty \| suggestion example: results	Return normal results, an exact empty state or a caller-supplied suggestion state.
`suggestedQuery`	string	allowed: 1 – 100 example: authentication sessions	Required, distinct alternative query for scenario=suggestion; invalid for other scenarios.
`total`	int	allowed: 0 – 1000 example: 137	Total matching records. Defaults to 47; empty requires 0.
`page`	int	default: 1 allowed: 1 – 1000 example: 2	One-based page number; beyond-last pages return an honest empty slice.
`pageSize`	int	default: 10 allowed: 1 – 50 example: 20	Maximum results returned on this page.
`sort`	enum	default: relevance allowed: relevance \| newest \| oldest example: newest	Sort by descending score, newest timestamp or oldest timestamp.
`facets`	boolean	default: true example: true	Include exact full-result category counts.
`asOf`	date	example: 2026-07-10T12:00:00.000Z	Replay anchor for synthetic updatedAt values; defaults to the request clock and is echoed.

query string required

Original search text displayed to the user.

allowed: 1 – 100

example: query=cursor pagination

scenario enum

Return normal results, an exact empty state or a caller-supplied suggestion state.

default: results

allowed: results | empty | suggestion

example: scenario=results

suggestedQuery string

Required, distinct alternative query for scenario=suggestion; invalid for other scenarios.

allowed: 1 – 100

example: suggestedQuery=authentication sessions

total int

Total matching records. Defaults to 47; empty requires 0.

allowed: 0 – 1000

example: total=137

page int

One-based page number; beyond-last pages return an honest empty slice.

default: 1

allowed: 1 – 1000

example: page=2

pageSize int

Maximum results returned on this page.

default: 10

allowed: 1 – 50

example: pageSize=20

sort enum

Sort by descending score, newest timestamp or oldest timestamp.

default: relevance

allowed: relevance | newest | oldest

example: sort=newest

facets boolean

Include exact full-result category counts.

default: true

example: facets=true

asOf date

Replay anchor for synthetic updatedAt values; defaults to the request clock and is echoed.

example: asOf=2026-07-10T12:00:00.000Z

Universal parameters Shared response and formatting options 4

Parameter	Type	Default & allowed	Description
`fields`	list	example: query,effectiveQuery	Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
`exclude`	list	example: facets	Return all fields except these (comma-separated).
`pretty`	boolean	default: false example: true	Pretty-print the JSON response.
`unwrap`	boolean	default: false example: true	Drop the envelope: return the raw array/object without data/meta wrapper.

fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=query,effectiveQuery

exclude list

Return all fields except these (comma-separated).

example: exclude=facets

pretty boolean

Pretty-print the JSON response.

default: false

example: pretty=true

unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false

example: unwrap=true

Response schema Fields returned in each record 9

Field	Type	Description	Example
`query`	string	Original caller query.	cursor pagination
`effectiveQuery`	string	Query used to build result text; equals suggestedQuery in suggestion mode.	cursor pagination
`scenario`	string	results \| empty \| suggestion.	results
`suggestedQuery` nullable	string	Explicit alternative in suggestion mode, otherwise null.	null
`total`	integer	Exact full-result count before paging.	137
`sort`	string	Applied sort mode.	relevance
`pageInfo`	object	Exact one-based page bounds, totals and previous/next state.	{"page":1,"pageSize":10,"totalPages":14,"from":1,"to":10,"hasPreviousPage":false,"hasNextPage":true,"previousPage":null,"nextPage":2}
`results`	object[]	At most pageSize deterministic result records with safe URLs and exact Unicode code-point highlight offsets.	[{"id":"result_00001_1234abcd","title":"cursor pagination — API reference 1","url":"https://search.example/results/result_00001_1234abcd","snippet":"A fictional search fixture about cursor pagination.","category":"reference","score":0.91,"updatedAt":"2026-07-01T12:00:00.000Z","highlights":[]}]
`facets`	object[]	Category counts over all matches; empty when disabled or no results.	[{"value":"reference","count":34}]

query string

Original caller query.

example: cursor pagination

effectiveQuery string

Query used to build result text; equals suggestedQuery in suggestion mode.

example: cursor pagination

scenario string

results | empty | suggestion.

example: results

suggestedQuery string nullable

Explicit alternative in suggestion mode, otherwise null.

example: null

total integer

Exact full-result count before paging.

example: 137

sort string

Applied sort mode.

example: relevance

pageInfo object

Exact one-based page bounds, totals and previous/next state.

example: {"page":1,"pageSize":10,"totalPages":14,"from":1,"to":10,"hasPreviousPage":false,"hasNextPage":true,"previousPage":null,"nextPage":2}

results object[]

At most pageSize deterministic result records with safe URLs and exact Unicode code-point highlight offsets.

example: [{"id":"result_00001_1234abcd","title":"cursor pagination — API reference 1","url":"https://search.example/results/result_00001_1234abcd","snippet":"A fictional search fixture about cursor pagination.","category":"reference","score":0.91,"updatedAt":"2026-07-01T12:00:00.000Z","highlights":[]}]

facets object[]

Category counts over all matches; empty when disabled or no results.

example: [{"value":"reference","count":34}]

Documented examples

Build-generated requests and complete responses 3

Relevant highlighted results

 /api/search-results?query=cursor%20pagination&total=137&page=2&pageSize=20&sort=relevance&asOf=2026-07-10T12%3A00%3A00.000Z

GET /api/search-results?query=cursor%20pagination&total=137&page=2&pageSize=20&sort=relevance&asOf=2026-07-10T12%3A00%3A00.000Z

{
  "data": {
    "query": "cursor pagination",
    "effectiveQuery": "cursor pagination",
    "scenario": "results",
    "suggestedQuery": null,
    "total": 137,
    "sort": "relevance",
    "pageInfo": {
      "page": 2,
      "pageSize": 20,
      "totalPages": 7,
      "from": 21,
      "to": 40,
      "hasPreviousPage": true,
      "hasNextPage": true,
      "previousPage": 1,
      "nextPage": 3
    },
    "results": [
      {
        "id": "result_00057_a8975b3c",
        "title": "cursor pagination — worked example 57",
        "url": "https://search.example/results/result_00057_a8975b3c",
        "snippet": "A fictional search fixture about cursor pagination, with deterministic ranking, highlighting and pagination metadata.",
        "category": "reference",
        "score": 0.910757,
        "updatedAt": "2026-06-14T12:00:00.000Z",
        "highlights": [
          {
            "field": "title",
            "start": 0,
            "end": 17,
            "text": "cursor pagination"
          },
          {
            "field": "snippet",
            "start": 33,
            "end": 50,
            "text": "cursor pagination"
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

Honest empty state /api/search-results?query=missing%20fixture&scenario=empty&total=0&asOf=2026-07-10T12%3A00%3A00.000Z

GET /api/search-results?query=missing%20fixture&scenario=empty&total=0&asOf=2026-07-10T12%3A00%3A00.000Z

{
  "data": {
    "query": "missing fixture",
    "effectiveQuery": "missing fixture",
    "scenario": "empty",
    "suggestedQuery": null,
    "total": 0,
    "sort": "relevance",
    "pageInfo": {
      "page": 1,
      "pageSize": 10,
      "totalPages": 0,
      "from": 0,
      "to": 0,
      "hasPreviousPage": false,
      "hasNextPage": false,
      "previousPage": null,
      "nextPage": null
    },
    "results": [],
    "facets": []
  },
  "meta": {
    "endpoint": "search-results",
    "params": {
      "query": "missing fixture",
      "scenario": "empty",
      "total": 0,
      "page": 1,
      "pageSize": 10,
      "sort": "relevance",
      "facets": true,
      "asOf": "2026-07-10T12:00:00.000Z"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

Suggested-query state

 /api/search-results?query=auth%20sesions&scenario=suggestion&suggestedQuery=authentication%20sessions&total=12&asOf=2026-07-10T12%3A00%3A00.000Z

GET /api/search-results?query=auth%20sesions&scenario=suggestion&suggestedQuery=authentication%20sessions&total=12&asOf=2026-07-10T12%3A00%3A00.000Z

{
  "data": {
    "query": "auth sesions",
    "effectiveQuery": "authentication sessions",
    "scenario": "suggestion",
    "suggestedQuery": "authentication sessions",
    "total": 12,
    "sort": "relevance",
    "pageInfo": {
      "page": 1,
      "pageSize": 10,
      "totalPages": 2,
      "from": 1,
      "to": 10,
      "hasPreviousPage": false,
      "hasNextPage": true,
      "previousPage": null,
      "nextPage": 2
    },
    "results": [
      {
        "id": "result_00002_c4520f9d",
        "title": "authentication sessions — migration notes 2",
        "url": "https://search.example/results/result_00002_c4520f9d",
        "snippet": "A fictional search fixture about authentication sessions, with deterministic ranking, highlighting and pagination metadata.",
        "category": "guides",
        "score": 0.987374,
        "updatedAt": "2025-08-17T12:00:00.000Z",
        "highlights": [
          {
            "field": "title",
            "start": 0,
            "end": 23,
            "text": "authentication sessions"
          },
          {
            "field": "snippet",
            "start": 33,
            "end": 56,
            "text": "authentication sessions"
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

Builds one complete, deterministic search response fixture from the requested query and paging options. It is designed for search boxes, result lists and test assertions—not as a search engine. Every result uses a safe search.example URL and contains exact highlight offsets that point back to the returned title and snippet.

Three explicit scenarios cover the UI branches teams repeatedly hand-code: normal results, an honest empty state, and a caller-supplied suggestion. Relevance scores sort descending, date sorts use timestamps bounded by the echoed asOf, page metadata reconciles exactly, and requested facet counts sum to the full result count (facets=false deliberately returns an empty array).

This compute route deliberately has no seed parameter: identical resolved query parameters already produce identical output. Omitted asOf resolves from the request clock and is echoed for explicit replay.

Use it for

Test search pagination, facet filters and result-count copy
Exercise empty-result and suggested-query interface states
Assert highlight offsets and relevance/date sort order in clients

Frequently asked questions

Practical answers about this endpoint 3

Are highlight offsets guaranteed to match the text?

Yes. Every highlight names its field and exact start/end range, and the selected substring equals the returned highlight text.

Can I test an empty search state?

Yes. scenario=empty returns zero results, zero facets and exact zero-page metadata; a conflicting nonzero total is rejected.

Why is there no seed parameter?

This is a deterministic compute route: all resolved route parameters, including the echoed asOf anchor, completely determine the response.

Standards & references

Primary sources behind the contract

RFC 2606 — Reserved Top Level DNS Names

Useful next tools in the catalog

Mock Pagination API MOCK DATA

Deterministic offset and opaque-cursor pagination fixtures with exact totals, stable sorting and no duplicated or skipped records.

Fake Product Data API MOCK DATA

Fake e-commerce products with category-themed names, prices in real currencies (whole yen for JPY), valid EAN-13 barcodes, SKUs, ratings and image URLs.

Fake Form Submission API MOCK DATA

Generate coherent fake contact, signup, survey and application submissions with exact validation, attachment, spam and processing states.

Random User Data API MOCK DATA

Complete fake people — name, age-consistent birth date, email, phone, job and address — with working filters for gender, age range and email domain.

Fake Analytics Session Data API MOCK DATA

Generate privacy-safe analytics sessions and funnel summaries with exact event order, timing, outcome, conversion and revenue arithmetic.