Google Search

Search for Google results based on keywords.

If you already know that you want to use Google Search, this page is the one you should read. It shows the required input, the filters you can apply, how pagination works, and what localization controls are available.

At a Glance

Field	Value
Name	Google Search
Scraper	`google_search`
Engine	`google_search`
Website	Google
Website URL	Google.com
Output Format	`json`
Version	`1.0.0`
Parameter Count	`19`
Parameter Groups	Search Query (1), Localization (5), Advanced Parameters (6), Advanced Filters (3), Geographic Location (2), Pagination (1), Request Controls (1)

Request Example

This is the real request body used to validate google_search during this docs refresh. For /v1/serp, the engine field should be the engine's scraper value.

curl -X POST "https://run.xcrawl.com/v1/serp" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"engine":"google_search","q":"openai"}'

Response Example

The JSON below comes from the same live response. Long strings, data URLs, and large arrays were shortened so the example stays readable.

{
  "search_metadata": {
    "cached": true,
    "created_at": "2026-03-26 08:24:18 UTC",
    "id": "01KMMKX1EC62VPCD7FW8YZ8QVS",
    "json_endpoint": "https://serp.xcrawl.com/01KMMKX1EC62VPCD7FW8YZ8QVS.json",
    "processed_at": "2026-03-26 08:24:18 UTC",
    "raw_html_file": "https://serp.xcrawl.com/01KMMKX1EC62VPCD7FW8YZ8QVS.html",
    "status": "completed",
    "total_time_taken": 2
  },
  "search_parameters": {
    "engine": "google_search",
    "q": "openai"
  },
  "total_credits_used": 1,
  "ads": [
    {
      "block_position": "top",
      "description": "Official ChatGPT website — The ultimate how-to guide for your unique interests. Ask the official ChatGPT today. ChatGPT can help with book ideas, poems, or trip planning. Try it yourself. Shop smarter with ChatGPT.",
      "displayed_link": "https://chatgpt.com/",
      "link": "https://chatgpt.com/",
      "position": 3,
      "sitelinks": [],
      "source": "ChatGPT",
      "title": "Official ChatGPT from OpenAI",
      "tracking_link": "https://www.google.com/aclk?sa=L&pf=1&ai=DChsSEwih5qTvkI2SAxWGJtQBHV99Ch0YACICCAEQAxoCb2E&co=1&ase=2&gclid=EAIaIQobChMIoeak75CNkgMVhibUAR1ffQodEAAYASAAEgI0gvD_BwE&cid=CAAS0wHkaL0sW3DTIjSZ4Aae3ZqxOJQZNXFVmv08yvggeJu9P9TRL... [truncated, 556 chars]"
    },
    {
      "_note": "1 more items omitted"
    }
  ],
  "immersive_products": [],
  "knowledge_graph": {
    "entity_type": "food, kp3_verticals",
    "header_images": [
      {
        "image": "data:image/gif;base64,R0lGODlhAQABAIAAAP///////yH5BAEKAAEALAAAAAABAAEAAAICTAEAOw... [truncated data URL, 82 chars]"
      },
      {
        "_note": "3 more items omitted"
      }
    ],
    "kgmid": "/m/02vqfm",
    "knowledge_graph_search_link": "https://www.google.co.US/search?kgmid=/m/02vqfm&hl=en-US&q=openai"
  },
  "local_map": {
    "gps_coordinates": {},
    "image": "data:image/gif;base64,R0lGODlhAQABAIAAAP///////yH5BAEKAAEALAAAAAABAAEAAAICTAEAOw... [truncated data URL, 82 chars]"
  },
  "organic_results": [
    {
      "displayed_link": "https://openai.com",
      "favicon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABwAAAAcCAAAAABXZoBIAAABEElEQVR4Ab... [truncated data URL, 462 chars]",
      "link": "https://openai.com/",
      "position": 1,
      "redirect_link": "https://www.google.com/url?sa=t&source=web&rct=j&opi=89978449&url=https://openai.com/&ved=2ahUKEwi9nfzhl4KPAxWfSDABHTPgIkYQFnoECD4QAQ",
      "snippet": "We believe our research will eventually lead to artificial general intelligence, a system that can solve human-level problems. Building safe and beneficial ...",
      "snippet_highlighted_words": null,
      "source": "OpenAI",
      "thumbnail": "",
      "title": "OpenAI"
    },
    {
      "_note": "3 more items omitted"
    }
  ],
  "pagination": {
    "current": "1",
    "next": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=10&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
    "other_pages": {
      "2": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=10&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
      "3": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=20&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
      "4": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=30&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
      "5": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=40&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
      "6": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=50&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
      "7": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=60&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
      "8": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=70&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
      "9": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=80&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]",
      "10": "https://www.google.com/search?q=openai&sca_esv=3087728c2f704245&hl=en&ei=Me3EaeLIHYT_ptQP9-_mwA4&start=90&sa=N&sstk=Af77f_cDxMPFCmcbOh9frvIGLHiLLIfByR4_yw4whzTcqCMKCkn51lvgIqGpFvyc7BSavRXxloEGxCmTre_BywKBMDhP4a3NHpHKSA&v... [truncated, 268 chars]"
    }
  },
  "refine_search_filters": [
    {
      "question": "Is OpenAI owned by Elon Musk?"
    },
    {
      "_note": "3 more items omitted"
    }
  ],
  "refine_this_search": [],
  "related_searches": [
    {
      "block_position": 1,
      "link": "https://www.google.com/search?sca_esv=3087728c2f704245&hl=en&q=OpenAI+chat&sa=X&ved=2ahUKEwiipaHikb2TAxWEv4kEHfe3GegQ1QJ6BAg-EAE",
      "query": "OpenAI chat"
    },
    {
      "_note": "7 more items omitted"
    }
  ]
}

Required Parameters

If you are sending your first request with this engine, start here. Requiredness is based on properties.<field>.must, not the top-level required array.

Field	Type	Group	Description
`q`	`string`	Search Query	The keyword or phrase you want this search engine to look up.

Available Parameters

The sections below follow the same parameter groups as the backend, but the field descriptions have been rewritten into shorter, user-facing wording so they are easier to scan.

Search Query

Field	Type	Required	Description
`q`	`string`	Yes	The keyword or phrase you want this search engine to look up.

Localization

Field	Type	Required	Description
`cr`	`string`	No	Limit results to one or more countries.
`gl`	`string`	No	Country or region code used to localize the results.
`hl`	`string`	No	Interface language used for the search and returned SERP labels.
`lr`	`string`	No	Limit results to one or more languages.
`google_domain`	`string`	No	Google domain to query, such as `google.com` or `google.co.uk`.

Additional Constraints

gl：Options: 243 options. Examples: af, al, dz, as, ad
hl：Options: 157 options. Examples: af, ak, sq, ws, am
google_domain：Options: 47 options. Examples: google.com, google.com.hk, google.co.uk, google.co.jp, google.us

Advanced Parameters

Field	Type	Required	Description
`si`	`string`	No	Reuse a Google result-state token to open a specific search layout or tab.
`ibp`	`string`	No	Google layout token used to expand or render certain result modules.
`uds`	`string`	No	Google refinement token used to apply a specific suggested filter.
`lsig`	`string`	No	Additional Google place token sometimes needed for local or knowledge panels.
`kgmid`	`string`	No	Google Knowledge Graph entity ID used to target a specific entity.
`ludocid`	`string`	No	Google place or business CID used to target a specific local entity.

Advanced Filters

Field	Type	Required	Description
`tbs`	`string`	No	Advanced Google filter string, often used for time or content filters.
`nfpr`	`boolean`	No	Try to turn off auto-corrected results and keep the original query.
`filter`	`boolean`	No	Turn similar-result or duplicate-result filtering on or off.

Additional Constraints

nfpr：Default: false
filter：Default: false

Geographic Location

Field	Type	Required	Description
`uule`	`string`	No	Encoded Google location string for more precise geo-targeting.
`location`	`string`	No	Location hint used to make results closer to a target place.

Additional Constraints

location：Options: 10 options. Examples: IN, US, BR, ID, MX

Pagination

Field	Type	Required	Description
`start`	`number`	No	Result offset used for Google-style pagination.

Additional Constraints

start：Default: 0

Request Controls

Field	Type	Required	Description
`no_cache`	`boolean`	No	Skip cached results and force a fresh fetch.

Additional Constraints

no_cache：Default: false

Engines

Google Search