04 — google search

Google Search API

Run a live Google web search and get the SERP back as structured JSON: organic results, ads, answer boxes, knowledge graphs, related questions and searches.

GET/v1/search

POST/v1/search

GET is canonical; POST accepts the same fields as a JSON body. Use it when queries carry characters you'd rather not URL-encode.

Parameters

Search parameters
field	type	default	description
qrequired	string	—	The search query, 1–2048 characters.
gl	string	"us"	Two-letter country code the search runs from. `gl=de` returns what a searcher in Germany sees.
hl	string	"en"	Two-letter interface language. Affects result language and labels.
google_domain	string	"google.com"	The Google property to query, e.g. `google.de`.
device	"desktop" \| "mobile"	"desktop"	Which device's SERP to fetch. Layout and features differ between the two.
page	integer	1	1-based results page, up to `100`. Each page is a separate search and costs one credit.
time_range	"h" \| "d" \| "w" \| "m" \| "y"	—	Restrict results to the past hour, day, week, month, or year. Omit for any time.
autocorrect	boolean	true	When `false`, Google returns results for your literal query instead of a spell-corrected one.
safe	"off" \| "active"	"off"	`active` filters explicit content.

Making requests

GET requests

bash

curl "https://api.serpix.io/v1/search?q=standing+desk+reviews&gl=us&hl=en" \
  -H "Authorization: Bearer $SERPIX_API_KEY"

POST requests

post body

curl https://api.serpix.io/v1/search \
  -H "Authorization: Bearer $SERPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "standing desk reviews",
    "gl": "de",
    "hl": "de",
    "time_range": "m",
    "page": 2
  }'

Freshness-bounded search

time_range

# Only results Google indexed in the past week
curl "https://api.serpix.io/v1/search?q=nvidia+earnings&time_range=w" \
  -H "Authorization: Bearer $SERPIX_API_KEY"

One JSON object per search, with familiar block names if you've used other SERP APIs. Everything is snake_case and typed, and a block Google didn't render is omitted entirely, never null, never [].

200 — application/json

{
  "search_metadata": {
    "id": "srx_kq3v9tR2xLw8mA1c",
    "status": "success",
    "took_ms": 1184,
    "parser_version": "2026.07.1"
  },
  "search_parameters": {
    "q": "best espresso machines",
    "gl": "us",
    "hl": "en",
    "google_domain": "google.com",
    "device": "desktop",
    "page": 1
  },
  "search_information": {
    "total_results": 8420000,
    "query_displayed": "best espresso machines"
  },
  "ads": [
    {
      "position": 1,
      "block": "top",
      "title": "Espresso Machines On Sale — Free Shipping Over $49",
      "link": "https://www.example-store.com/espresso",
      "displayed_link": "https://www.example-store.com",
      "displayed_domain": "example-store.com",
      "snippet": "Shop prosumer espresso machines from Breville, Gaggia..."
    }
  ],
  "organic_results": [
    {
      "position": 1,
      "title": "The 7 Best Espresso Machines of 2026, Tested & Reviewed",
      "link": "https://www.seriouseats.com/best-espresso-machines",
      "displayed_link": "https://www.seriouseats.com › equipment",
      "snippet": "After 120 hours of side-by-side testing, the Breville Bambino Plus is still...",
      "source": "Serious Eats",
      "sitelinks": [
        {
          "title": "Best under $500",
          "link": "https://www.seriouseats.com/best-espresso-machines#budget"
        }
      ]
    },
    {
      "position": 2,
      "title": "Espresso Machine Buying Guide",
      "link": "https://www.wirecutter.com/espresso-machines",
      "snippet": "We've tested 42 machines since 2015..."
    }
  ],
  "related_questions": [
    {
      "question": "Is a $200 espresso machine worth it?",
      "snippet": "Entry-level machines can pull respectable shots if...",
      "title": "Budget espresso, tested",
      "link": "https://www.example.com/budget-espresso"
    }
  ],
  "related_searches": [
    { "query": "best espresso machine under 500" },
    { "query": "breville bambino plus review" }
  ],
  "detected_features": ["inline_videos", "top_stories"],
  "pagination": { "current": 1 }
}

search_metadata

field	type	default	description
id	string	—	Unique search id, `srx_`-prefixed. Appears in your console request log; include it when contacting support.
status	string	—	Always `"success"` on a 200.
took_ms	integer	—	End-to-end fetch + parse time in milliseconds.
parser_version	string	—	The parser build that produced this response. Pin it when comparing extractions over time.
html_url	string?	—	Reserved: a link to the raw HTML page this response was parsed from. Rolling out; currently absent.
json_url	string?	—	Reserved: a link to re-fetch this JSON response later. Rolling out; currently absent.

search_parameters

The parameters this search actually ran with (your input plus applied defaults): q, gl, hl, google_domain, device, page.

search_information

field	type	default	description
total_results	integer?	—	Google's estimated result count, when shown.
query_displayed	string?	—	The query Google displayed results for.
corrected_query	string?	—	Present when Google auto-corrected your query. Re-run with `autocorrect=false` to force the literal query.

organic_results

organic_results[n]

{
  "position": 3,
  "title": "Best Espresso Machines 2026 — Tested by Baristas",
  "link": "https://www.example.com/espresso-guide",
  "displayed_link": "https://www.example.com › coffee › gear",
  "snippet": "We pulled 400 shots on 18 machines. These six are...",
  "source": "Example Coffee Lab",
  "sitelinks": [
    { "title": "Under $500", "link": "https://www.example.com/espresso-guide#budget" },
    { "title": "Dual boiler picks", "link": "https://www.example.com/espresso-guide#dual" }
  ]
}

field	type	default	description
position	integer	—	1-based rank within organic results on this page.
title	string	—	Result title.
link	string	—	The destination URL, not a Google redirect.
displayed_link	string?	—	The breadcrumb-style URL as rendered on the SERP.
snippet	string?	—	The description text under the title.
source	string?	—	Publisher name when the SERP shows one.
sitelinks	array?	—	Sub-links under the result, each with `title` and `link`.

Sponsored results, parsed with the same care as organic, including the advertiser domain for ad intelligence work.

ads[n]

{
  "position": 2,
  "block": "top",
  "title": "Barista Express® Official Site — Espresso, Simplified",
  "link": "https://www.example-brand.com/barista-express",
  "displayed_link": "https://www.example-brand.com/espresso",
  "displayed_domain": "example-brand.com",
  "snippet": "Grind, dose and extract café-quality espresso at home.",
  "sitelinks": [
    { "title": "Compare models", "link": "https://www.example-brand.com/compare" }
  ]
}

field	type	default	description
position	integer	—	1-based rank within the ad block.
block	"top" \| "bottom"	—	Whether the ad ran above or below organic results.
title	string	—	Ad headline.
link	string	—	Ad destination URL.
displayed_link	string?	—	The URL string rendered on the ad.
displayed_domain	string?	—	The advertiser's domain. Key on this for share-of-voice tracking.
snippet	string?	—	Ad description text.
sitelinks	array?	—	Ad sitelink extensions, title + link.

answer_box

{
  "answer_box": {
    "type": "featured_snippet",
    "title": "How much pressure does espresso need?",
    "answer": "9 bars",
    "snippet": "Espresso is traditionally extracted at 9 bars of pressure — roughly 130 psi...",
    "link": "https://www.example.com/espresso-pressure",
    "source": "Example Coffee Lab"
  }
}

field	type	default	description
type	string?	—	Answer box variant, e.g. featured snippet.
title	string?	—	Heading, when present.
answer	string?	—	The short direct answer, when Google renders one.
snippet	string?	—	Longer supporting text.
link	string?	—	Source URL.
source	string?	—	Source name.

knowledge_graph

{
  "knowledge_graph": {
    "title": "Espresso",
    "type": "Coffee beverage",
    "description": "Espresso is a concentrated form of coffee produced by forcing hot water...",
    "source": "https://en.wikipedia.org/wiki/Espresso",
    "attributes": {
      "Origin": "Italy",
      "Introduced": "Early 20th century"
    }
  }
}

field	type	default	description
title	string?	—	Entity name.
type	string?	—	Entity type line under the title.
description	string?	—	Panel description text.
source	string?	—	Description source URL.
attributes	object?	—	Key–value facts from the panel, as displayed.

related_questions

“People also ask” entries: question, plus snippet, title, and link of the answering page when expanded content is present.

related_searches

Query suggestions from the bottom of the SERP: query, with a link when one is rendered.

detected_features

SERP features present on the page but not parsed yet, such as inline_videos or top_stories. Most SERP APIs silently drop what they can't parse; Serpix tells you it was there. Features that show up here often get parsed next.

pagination

field	type	default	description
current	integer	—	The page this response covers, matching your page parameter.
next	string?	—	Reserved: a URL for the following page. Currently absent; fetch deeper pages by incrementing page.

Errors

Failed requests are never charged. Search failures return an error object with a search_id; request failures (auth, validation, balance) return a detail string.

Search failures

When a valid request can't produce results, the response carries an error code and the search id from your console request log:

503

HTTP/2 503
content-type: application/json
x-serpix-credits-charged: 0
x-serpix-credits-remaining: 24999

{
  "error": {
    "code": "search_unavailable",
    "search_id": "srx_kq3v9tR2xLw8mA1c"
  }
}

Error codes
field	type	default	description
search_unavailable	503	—	Google didn't serve a usable results page. Transient; retry with a short backoff.
search_failed	502	—	The search couldn't be completed. Safe to retry; if it persists, contact support with the `search_id`.

Request failures

Rejected before any search work happens:

402

HTTP/2 402
content-type: application/json

{ "detail": "insufficient credits" }

Request error status codes
field	type	default	description
401	unauthorized	—	Missing, malformed, or revoked API key. See Authentication.
402	payment required	—	Credit balance can't cover the search. Top up and retry.
422	validation	—	A parameter failed validation: empty `q`, `page` out of range, an unknown `device`. The body lists each offending field.