GET /customsearch/v1 — Web Search Endpoint Reference

The Custom Search JSON API exposes a single GET endpoint that accepts your query and returns structured web results. Every request must include your API key, a Search Engine ID (cx), and a query string. All other parameters are optional and let you filter, page, localize, and sort the results your users receive.

Endpoint

GET https://www.googleapis.com/customsearch/v1

Request Parameters

Required Parameters

string

required

Your Google API key. Create one in the Google Cloud Console. Every request must include this parameter.

string

required

The Search Engine ID (also called Programmable Search Engine ID) that defines the scope and configuration of your search. Create and manage search engines at programmablesearchengine.google.com.

string

required

The search query. Supports the same query operators as google.com — for example site:, filetype:, -term, and quoted phrases. Maximum length is 2,048 characters.

Pagination Parameters

integer

default:"10"

Number of results to return in a single page. Accepted values are 1 through 10. To retrieve more results, use the start parameter to page through them.

integer

default:"1"

The index of the first result to return. Use in combination with num to paginate. The maximum value is 91; combined with num=10 this gives you access to up to 100 results per query.

Language and Region Parameters

string

Restricts results to documents written in a specific language. Pass a Google language code such as lang_en (English), lang_fr (French), or lang_de (German). See the full list of supported language codes.

string

Boosts results relevant to a specific country. Accepts a two-letter country code (ISO 3166-1 alpha-2), such as us, gb, or de. This biases results toward that country without hard-filtering them.

string

Restricts results to documents originating from a particular country. Uses Google country codes such as countryUS or countryGB. Unlike gl, this parameter hard-filters by the country of origin of the result page.

Safety Parameters

string

default:"off"

SafeSearch setting for the query. Accepted values:

active — filters explicit adult content from results.
off — disables SafeSearch filtering.

Date and Freshness Parameters

string

Restricts results to pages indexed within a specified time period. Format: [d|w|m|y][number] where the prefix is the unit:

d5 — last 5 days
w2 — last 2 weeks
m3 — last 3 months
y1 — last year

string

Controls the sort order of results. Pass date to sort by recency. You can also specify a structured data field such as sort=date:r:20230101:20231231 to restrict by date range.

Content Filtering Parameters

string

Limits results to a specific site or domain, for example siteSearch=docs.example.com. Use with siteSearchFilter to include or exclude the site.

string

Controls whether siteSearch includes or excludes the specified site. Accepted values:

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

string

Requires every result to contain this exact phrase. Equivalent to wrapping the phrase in quotes in the query string. Only one phrase is allowed per request.

string

Ensures that results do not contain this word or phrase. Equivalent to prefixing a term with - in the query string.

string

Adds additional search terms that are joined with OR. Results must contain at least one of the terms in q OR at least one term in orTerms.

string

Restricts results to files with a specific extension. Common values: pdf, doc, xls, ppt, txt. You can combine multiple types with a pipe: pdf|doc.

string

Filters results by Creative Commons license type. Accepted values include cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived, and combinations thereof separated by |. For example: cc_publicdomain|cc_attribute.

string

default:"1"

Toggles duplicate content filtering. Pass 0 to disable the filter and receive more raw results. Pass 1 (default) to enable it.

Example Request

The following request searches for “climate change policy” in English, filtered to the last 3 months, returning the first 5 results.

cURL

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_SEARCH_ENGINE_ID\
&q=climate+change+policy\
&num=5\
&lr=lang_en\
&dateRestrict=m3\
&safe=active"

import requests

params = {
    "key": "YOUR_API_KEY",
    "cx": "YOUR_SEARCH_ENGINE_ID",
    "q": "climate change policy",
    "num": 5,
    "lr": "lang_en",
    "dateRestrict": "m3",
    "safe": "active",
}

response = requests.get(
    "https://www.googleapis.com/customsearch/v1",
    params=params
)
data = response.json()

for item in data.get("items", []):
    print(item["title"], item["link"])

const params = new URLSearchParams({
  key: "YOUR_API_KEY",
  cx: "YOUR_SEARCH_ENGINE_ID",
  q: "climate change policy",
  num: "5",
  lr: "lang_en",
  dateRestrict: "m3",
  safe: "active",
});

const response = await fetch(
  `https://www.googleapis.com/customsearch/v1?${params}`
);
const data = await response.json();

for (const item of data.items ?? []) {
  console.log(item.title, item.link);
}

Example Response

{
  "kind": "customsearch#search",
  "url": {
    "type": "application/json",
    "template": "https://www.googleapis.com/customsearch/v1?q={searchTerms}&..."
  },
  "queries": {
    "request": [
      {
        "title": "Google Custom Search - climate change policy",
        "totalResults": "4820000000",
        "searchTerms": "climate change policy",
        "count": 5,
        "startIndex": 1,
        "inputEncoding": "utf8",
        "outputEncoding": "utf8",
        "safe": "active",
        "cx": "YOUR_SEARCH_ENGINE_ID",
        "language": "lang_en",
        "dateRestrict": "m3"
      }
    ],
    "nextPage": [
      {
        "title": "Google Custom Search - climate change policy",
        "totalResults": "4820000000",
        "searchTerms": "climate change policy",
        "count": 5,
        "startIndex": 6,
        "inputEncoding": "utf8",
        "outputEncoding": "utf8",
        "safe": "active",
        "cx": "YOUR_SEARCH_ENGINE_ID"
      }
    ]
  },
  "searchInformation": {
    "searchTime": 0.432891,
    "formattedSearchTime": "0.43",
    "totalResults": "4820000000",
    "formattedTotalResults": "4,820,000,000"
  },
  "items": [
    {
      "kind": "customsearch#result",
      "title": "Global Climate Change Policy Report 2024",
      "htmlTitle": "Global <b>Climate Change Policy</b> Report 2024",
      "link": "https://www.example.org/climate-policy-2024",
      "displayLink": "www.example.org",
      "snippet": "A comprehensive overview of international climate change policy developments in early 2024, covering COP agreements and national commitments.",
      "htmlSnippet": "A comprehensive overview of international <b>climate change policy</b> developments...",
      "cacheId": "abc123XYZ",
      "formattedUrl": "https://www.example.org/climate-policy-2024",
      "htmlFormattedUrl": "https://www.example.org/<b>climate</b>-<b>policy</b>-2024",
      "pagemap": {
        "metatags": [
          {
            "og:title": "Global Climate Change Policy Report 2024",
            "og:description": "International policy overview",
            "og:type": "article"
          }
        ]
      }
    }
  ]
}

Response Fields

string

The type identifier for this response object. Always "customsearch#search".

object

Describes the URL template used to construct the request. Useful for constructing follow-up queries programmatically.

Show url fields

string

MIME type of the URL template. Always "application/json".

string

The OpenSearch URL template string.

object

Metadata about the current page of results and adjacent pages.

Show queries fields

array

A single-element array describing the current query page.

Show request[] fields

string

Human-readable description of the search, including the query term.

string

Estimated total number of results for the query, returned as a string.

string

The exact search query that was used.

integer

Number of results returned on this page.

integer

Index of the first result on this page (1-based).

string

Character encoding of the query. Typically "utf8".

string

Character encoding of the response. Typically "utf8".

string

The SafeSearch setting applied. Either "active" or "off".

string

The Search Engine ID used for the request.

array

A single-element array describing the next page of results. Absent when you are on the last page.

Show nextPage[] fields

integer

The start value to pass in the next request to fetch this page.

integer

Number of results on the next page.

object

Statistics about the search execution.

Show searchInformation fields

number

Wall-clock time the search took to execute, in seconds.

string

Human-readable version of searchTime, e.g. "0.43".

string

Estimated total number of matching documents, returned as a string.

string

Locale-formatted version of totalResults, e.g. "4,820,000,000".

array

The list of search result objects for this page. May contain up to num entries (default 10).

Show items[] fields

string

Always "customsearch#result".

string

The plain-text title of the result page.

string

The title with query-match terms wrapped in <b> tags.

string

The canonical URL of the result page.

string

A shortened, human-readable version of the URL suitable for display, e.g. "www.example.org".

string

A plain-text excerpt from the result page describing the content.

string

The snippet with matching terms wrapped in <b> tags.

string

The identifier used to retrieve the Google-cached version of this page. May be absent for some results.

string

Plain-text breadcrumb URL shown to the user.

string

The formatted URL with matching terms bolded.

object

Structured data extracted from the page, including Open Graph tags, schema.org entities, and other metatags. Keys vary by page; common keys include metatags, article, person, product, and videoobject.

Error Codes

HTTP Status	Meaning
`400`	Bad request — a required parameter is missing or malformed.
`401`	Invalid API key — check that `key` is correct and enabled for this API.
`403`	Quota exceeded or access forbidden — you may have hit the daily limit.
`429`	Rate limited — slow down requests and implement exponential backoff.
`500`	Internal server error — retry after a short delay.

The free tier allows 100 queries per day per project. Paid usage supports up to 10,000 queries per day. Monitor your quota in the Google Cloud Console.

Use queries.nextPage[0].startIndex from the response to fetch the next page rather than manually incrementing start. This ensures you stay within bounds and handles edge cases automatically.

​Endpoint

​Request Parameters

​Required Parameters

​Pagination Parameters

​Language and Region Parameters

​Safety Parameters

​Date and Freshness Parameters

​Content Filtering Parameters

​Example Request

​Example Response

​Response Fields

​Error Codes

Endpoint

Request Parameters

Required Parameters

Pagination Parameters

Language and Region Parameters

Safety Parameters

Date and Freshness Parameters

Content Filtering Parameters

Example Request

Example Response

Response Fields

Error Codes