Google Search Pagination Is Not results.length

Kian Doost — Thu, 20 Aug 2026 04:04:12 +0000

Disclosure: I work on Reserp. This article explains the public API contract and keeps application policy explicit.

Suppose a search API returns 17 URLs on its first response. What should the next page offset be?

With Google Search, the answer is not 17.

A visible search page can contain organic listings, news blocks, sitelinks, carousels, discussion replies, videos, and nested results. An API that preserves those visible blocks may return many URLs without changing Google's organic-result pagination rule.

Reserp makes that distinction explicit. Its start parameter is Google's organic-result offset, while the results array represents visible result blocks. This tutorial shows a direct client pattern that keeps those two concepts separate.

The first request

Reserp accepts a complete Google Search URL in one JSON field:

curl -X POST https://api.reserp.ai/v1/serp \
  -H "Authorization: Bearer $RESERP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.google.com/search?q=photonic+computing&gl=us&hl=en"}'

The URL can use normal Google parameters such as:

Parameter	Meaning	Example
`q`	search query	`photonic computing`
`gl`	country	`us`
`hl`	language	`en`
`start`	organic-result offset	`10`
`tbs`	time or result filter	`qdr:w`
`tbm`	search type	`nws`

The Google num parameter is unsupported and should not be sent.

What pagination metadata means

A successful response contains pagination independent of results.length:

{
  "pagination": {
    "start": 0,
    "nextStart": 10,
    "nextUrl": "https://www.google.com/search?q=photonic+computing&gl=us&hl=en&start=10"
  }
}

The rules are simple:

omit start or use 0 for the first page;
use 10 for the second page;
use 20 for the third page;
continue in non-negative increments of 10.

An invalid offset, such as start=17, produces a non-billable 400 invalid_request response.

Write a one-request Python primitive

The transport function below makes exactly one request. It does not retry or fetch another page:

import json
import os
from urllib.request import Request, urlopen


def search_once(google_url: str) -> dict:
    request = Request(
        "https://api.reserp.ai/v1/serp",
        data=json.dumps({"url": google_url}).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {os.environ['RESERP_API_KEY']}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urlopen(request) as response:
        return json.load(response)

Call it for the first page:

first = search_once(
    "https://www.google.com/search"
    "?q=photonic+computing"
    "&gl=us"
    "&hl=en"
)

print(first["pagination"])

Make the second page an application decision

If—and only if—the application decides it needs another page, pass the returned URL into another explicit invocation:

second_url = first["pagination"]["nextUrl"]
second = search_once(second_url)

The important part is what the code does not say:

# Wrong: visible block count is not Google's organic offset.
next_start = len(first["results"])

It also avoids burying a loop inside search_once. The calling job may have its own page limit, request budget, cancellation signal, or queue. Those are application policies, not transport behavior.

Optional fields stay optional

Each result block may include text, url, and children, but not every block has every field. In particular, text is optional in the public contract:

for block in first.get("results", []):
    text = block.get("text")
    url = block.get("url")

    if text is not None:
        print(text)
    if url is not None:
        print(url)

Do not flatten children unless your application has a reason to discard their URL boundaries. Reserp retains nesting precisely when flattening would lose descendant content or structure.

Error fields describe; the application decides

Every error body has four public fields:

{
  "ok": false,
  "error": "service_unavailable",
  "retryable": true,
  "billed": false
}

retryable is authoritative for retry eligibility. billed reports whether billing settled; it does not decide whether an error is retryable.

The one-request function above does not add a retry loop. A real application can inspect the HTTP error body and let its existing worker, queue, or scheduler decide what to do. That avoids a hidden retry colliding with a higher-level retry and turning one logical job into duplicate API calls.

The durable mental model

Keep the three layers separate:

Google organic offset: start = 0, 10, 20, ...
Visible page content:   results = heterogeneous blocks
Application policy:     whether and when to request another page

Once those layers are separate, pagination is predictable. Follow pagination.nextUrl, never infer an offset from the number of returned blocks, and keep each API invocation explicit.

The complete contract, including supported Google parameters and stable error codes, is available in the Reserp API documentation and OpenAPI JSON.

DEV Community: Reserp