Google SERP API: Send a V1 Search Request | SERPpost

A Google SERP API request gives your application the Google result data for the query, country, language, and result type it sends. With SERPpost V1, send an authenticated POST request to /api/v1/search with t: "google", then confirm the response envelope has code: 0 before your application uses data. The current Google Search capability list identifies organic, relatedSearches, and aiOverview as fields to inspect when they are returned.

This guide is for a developer wiring a Google search step into an application. It shows the request shape, response checks, and the point where Reader fits after a result URL has been selected. It does not promise a fixed ranking, a local rank-tracking workflow, a result field for every query, or a performance target.

Start with one authenticated Google request

SERPpost V1 uses POST /api/v1/search for a Google Search request. Choose the query with s, set t to google, and include the country and language that describe the result set you want to inspect.

curl -X POST https://serppost.com/api/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "s": "web to markdown api",
    "t": "google",
    "p": 1,
    "d": 20000,
    "country": "us",
    "language": "en",
    "maxCache": 0
  }'

The example asks for the first page of a U.S. English Google request. maxCache: 0 is part of the request context when you need a fresh request. In production, pick cache behavior deliberately for your workload and keep the chosen value with your own job record.

Check the envelope before reading result fields

The response envelope tells your application whether V1 accepted the request. Check code first. When it is 0, inspect the data that is relevant to the selected result type. When it is non-zero, keep the request context and handle the response in your own retry or error path.

{
  "code": 0,
  "msg": "",
  "data": {
    "id": "request-id",
    "organic": []
  }
}

Do not assume every Google result includes the same fields. The current V1 capability list names organic, relatedSearches, and aiOverview for Google Search. A query can still return a different shape or omit an optional field, so parse the fields that your next application step actually needs.

Handle the request in Python

This example sends the documented V1 request, checks the HTTP response, and then checks the V1 envelope. Keep the API key in an environment variable rather than in source code.

import os

import requests


def search_google(query):
    response = requests.post(
        "https://serppost.com/api/v1/search",
        headers={
            "Authorization": f"Bearer {os.environ['SERPPOST_API_KEY']}",
            "Content-Type": "application/json",
        },
        json={
            "s": query,
            "t": "google",
            "p": 1,
            "d": 20000,
            "country": "us",
            "language": "en",
            "maxCache": 0,
        },
        timeout=30,
    )
    response.raise_for_status()

    envelope = response.json()
    if envelope.get("code") != 0:
        raise RuntimeError(f"SERPpost V1 returned code={envelope.get('code')!r}")

    return envelope["data"]


result = search_google("web to markdown api")

If your worker retries a request, give the job an ID and record the endpoint, t, country, language, page, depth, cache choice, HTTP status, V1 code, and returned data.id when present. That is the information you need to explain what happened to one request without turning a single example into a service-level claim.

Choose the country and language before comparing results

Country and language are request inputs, not a cosmetic setting. Keep them stable when you compare two queries or test a parser. If your application serves more than one market, include the selected market in the stored result or job record so a later reader knows which request produced it.

The same rule applies to page and depth. Change one setting at a time when you are validating downstream behavior. A result comparison is only useful when you can tell which input changed.

Use Reader after search selects a source URL

Search gives your application a result set. Reader is a separate V1 request for a public URL that your workflow has selected. Use /api/v1/url when the next step needs page metadata, readable Markdown, HTML, a public file, or a screenshot.

{
  "s": "https://example.com/article",
  "t": "url",
  "w": 3000,
  "d": 20000,
  "html": 1,
  "proxy": 0,
  "maxCache": 0
}

Keep search and capture as two explicit steps. The Google request tells you which result URLs appeared for the selected inputs. The Reader request records what your application captured from a public source URL. That separation makes testing and troubleshooting clearer.

Test the request before adding production traffic

Use a small set of non-sensitive queries that represent the job your application will run. Include a normal query, a query with a different country or language, and one case where an empty or unusual result would exercise your error handling. Save only the response fields your code needs.

Before you move a new path into a worker, check these items:

1. The request uses the documented endpoint and a server-side API key.
2. t, country, language, page, depth, and cache behavior match your job.
3. The application checks the HTTP response and V1 code.
4. The parser handles a missing optional field.
5. The job records enough context for a retry or investigation.
6. A selected source URL goes to Reader only when the next step needs source content.

Use the API Playground to inspect the request and response before integration. The V1 documentation is the current parameter and response reference. If you are migrating an existing Google Custom Search setup rather than adding a Google result request, read the separate Google Custom Search API alternatives guide so the migration decision and the request implementation do not get mixed together.

FAQ

Which endpoint handles a Google search request?

Send an authenticated POST request to /api/v1/search and use t: "google". Check the current V1 documentation before relying on a parameter or response field in production.

Does every Google response include aiOverview?

No response field should be assumed from one sample. The current capability list identifies aiOverview as a Google Search field to inspect when it is returned. Code should handle the field being absent.

When should I use Reader instead of Search?

Use Search for the Google result set. Use Reader after your application has a public source URL and needs capture output such as metadata, Markdown, HTML, a file, or a screenshot.

How do Request Slots affect this request?

Request Slots are the number of live API requests an account can run at once. Check the current value in your Dashboard and set worker concurrency to a value your application can handle.

Sources and review date

This guide was reviewed on August 25, 2026. The V1 endpoint shapes, Google Search fields, response envelope, Reader request and Request Slots definition were checked against current SERPpost source and V1 documentation on that date. Validate current account and request details before deployment.