Web Search: Query the Open Web via API

The Custom Search JSON API lets you embed Google-quality web search directly in your application. Every request is a plain HTTPS GET call that returns a JSON payload containing ranked results, pagination cursors, and rich metadata — no browser, scraping, or headless automation required.

How web search works

When you call the API, Google runs your query against the index defined by your Programmable Search Engine (identified by cx). By default the engine searches the entire open web; you can restrict or boost specific domains through the Search Engine control panel or via per-request parameters. Results come back in the items[] array, ordered by relevance, with up to 10 results per page.

Key parameters

string

required

The search query. Supports all standard Google search operators (site:, intitle:, filetype:, -term, "exact phrase", OR, etc.).

string

required

Your Programmable Search Engine ID. Find it in the Control Panel under Search engine ID.

string

required

Your Google API key. Create one in the Google Cloud Console.

integer

Number of results to return per page. Accepts 1–10. Defaults to 10. To retrieve more results, use start to paginate.

integer

Index of the first result to return (1-based). Maximum value is 91, which means you can page through at most 100 results (ten pages of 10). Defaults to 1.

string

Restrict or exclude results from a specific domain. Pair with siteSearchFilter to control whether the domain is included or excluded.Example: siteSearch=developer.mozilla.org

string

Controls how siteSearch is applied. Accepts:

i — include only results from the specified site
e — exclude all results from the specified site

Defaults to i when siteSearch is set.

string

Limit results to pages indexed within a recent time window. Format: d[N] (days), w[N] (weeks), m[N] (months), y[N] (years).Examples: d7 (last 7 days), m3 (last 3 months), y1 (last year)

string

Override relevance ranking. Set to date to sort by the most recently indexed results first. Combine with dateRestrict to surface fresh content reliably.

Pagination

The API exposes up to 100 results per query (10 pages × 10 results). Use start to move through pages:

Page	`start` value
1	1 (default)
2	11
3	21
…	…
10	91

Setting start above 91 returns a 400 Bad Request error. To retrieve beyond 100 results, rephrase the query or apply tighter filters.

Make your first web search request

Obtain your credentials

You need two values before making any request:

API key — create one at console.cloud.google.com/apis/credentials and enable the Custom Search API.
Search Engine ID (cx) — create a Programmable Search Engine at programmablesearchengine.google.com and copy the Search engine ID.

Send the request

Replace YOUR_API_KEY and YOUR_CX with your real values, then run:

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_CX\
&q=open+source+javascript+frameworks\
&num=5"

Inspect the response

A successful response returns HTTP 200 with a JSON body. The items[] array contains your results; queries.nextPage[0].startIndex tells you the start value for the next page.

Full curl example

The example below fetches the five most recent results about “climate policy” from bbc.com, published within the last month:

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_CX\
&q=climate+policy\
&num=5\
&siteSearch=bbc.com\
&siteSearchFilter=i\
&dateRestrict=m1\
&sort=date"

Sample JSON response

The following is a trimmed but structurally complete response showing two result items:

{
  "kind": "customsearch#search",
  "url": {
    "type": "application/json",
    "template": "https://www.googleapis.com/customsearch/v1?q={searchTerms}&..."
  },
  "queries": {
    "request": [
      {
        "title": "Google Custom Search - climate policy",
        "totalResults": "4180000000",
        "searchTerms": "climate policy",
        "count": 5,
        "startIndex": 1,
        "inputEncoding": "utf8",
        "outputEncoding": "utf8",
        "safe": "off",
        "cx": "YOUR_CX",
        "sort": "date",
        "siteSearch": "bbc.com",
        "siteSearchFilter": "i",
        "dateRestrict": "m1"
      }
    ],
    "nextPage": [
      {
        "startIndex": 6
      }
    ]
  },
  "searchInformation": {
    "searchTime": 0.312,
    "formattedSearchTime": "0.31",
    "totalResults": "4180000000",
    "formattedTotalResults": "4,180,000,000"
  },
  "items": [
    {
      "kind": "customsearch#result",
      "title": "World leaders reach landmark climate deal",
      "htmlTitle": "World leaders reach landmark <b>climate</b> <b>policy</b> deal",
      "link": "https://www.bbc.com/news/world/climate-deal-2024",
      "displayLink": "www.bbc.com",
      "snippet": "Delegates from 190 countries have agreed to a new framework that sets binding emissions targets for 2035...",
      "htmlSnippet": "Delegates from 190 countries have agreed to a new framework that sets binding <b>emissions</b> targets for 2035...",
      "cacheId": "abc123XYZ",
      "formattedUrl": "https://www.bbc.com/news/world/climate-deal-2024",
      "htmlFormattedUrl": "https://www.bbc.com/news/world/<b>climate</b>-deal-2024",
      "pagemap": {
        "metatags": [
          {
            "og:title": "World leaders reach landmark climate deal",
            "og:description": "Delegates from 190 countries have agreed...",
            "article:published_time": "2024-11-14T09:00:00Z"
          }
        ]
      }
    },
    {
      "kind": "customsearch#result",
      "title": "New climate policy framework explained",
      "htmlTitle": "New <b>climate</b> <b>policy</b> framework explained",
      "link": "https://www.bbc.com/news/science-environment/climate-explainer",
      "displayLink": "www.bbc.com",
      "snippet": "Here is everything you need to know about the latest round of international climate negotiations...",
      "htmlSnippet": "Here is everything you need to know about the latest round of international <b>climate</b> negotiations...",
      "formattedUrl": "https://www.bbc.com/news/science-environment/climate-explainer",
      "htmlFormattedUrl": "https://www.bbc.com/news/science-environment/<b>climate</b>-explainer",
      "pagemap": {
        "metatags": [
          {
            "og:title": "New climate policy framework explained",
            "article:published_time": "2024-11-10T14:30:00Z"
          }
        ]
      }
    }
  ]
}

Understand the response fields

string

Always "customsearch#search" for search responses.

object

Metadata about the search execution, including searchTime (seconds) and totalResults (estimated count as a string).

object

Contains request[] (echoes your query parameters) and optionally nextPage[] and previousPage[] objects. Use nextPage[0].startIndex as your next start value.

array

The ranked list of results. Each item contains title, link, snippet, displayLink, formattedUrl, cacheId, and pagemap. See Result Item Structure for the full schema.

Common patterns

Paginate through all results

Call the API in a loop, incrementing start by num each time, until items is absent from the response or start would exceed 91:

# Page 1
curl "https://www.googleapis.com/customsearch/v1?key=YOUR_API_KEY&cx=YOUR_CX&q=serverless+architecture&num=10&start=1"

# Page 2
curl "https://www.googleapis.com/customsearch/v1?key=YOUR_API_KEY&cx=YOUR_CX&q=serverless+architecture&num=10&start=11"

# Page 3
curl "https://www.googleapis.com/customsearch/v1?key=YOUR_API_KEY&cx=YOUR_CX&q=serverless+architecture&num=10&start=21"

Restrict search to a single domain

Use siteSearch with siteSearchFilter=i to replicate the site: operator at the API level:

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_CX\
&q=react+hooks\
&siteSearch=reactjs.org\
&siteSearchFilter=i"

Exclude a domain from results

Set siteSearchFilter=e to strip results from an unwanted domain:

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_CX\
&q=javascript+tutorial\
&siteSearch=w3schools.com\
&siteSearchFilter=e"

Error reference

HTTP status	Meaning	Common cause
`400`	Bad request	Missing `q`, invalid `start` value, malformed parameter
`401`	Unauthorized	Invalid or missing `key`
`403`	Forbidden	Quota exceeded or API not enabled for this project
`429`	Too many requests	Short-burst rate limit hit; apply exponential back-off
`500`	Server error	Transient Google-side issue; retry with back-off

On 429 responses, wait at least one second before retrying. Implement exponential back-off with jitter for production workloads to stay within the 100 queries/day free tier or your paid project quota.

Get Started

Core Concepts

Search Features

Guides

Help

Web Search: Query the Open Web via API

How web search works

Key parameters

Make your first web search request

Full curl example

Sample JSON response

Understand the response fields

Common patterns

Error reference

​How web search works

​Key parameters

​Pagination

​Make your first web search request

​Full curl example

​Sample JSON response

​Understand the response fields

​Common patterns

​Error reference

How web search works

Key parameters

Pagination

Make your first web search request

Full curl example

Sample JSON response

Understand the response fields

Common patterns

Error reference