Custom Search JSON API Reference Overview

The Custom Search JSON API gives your application access to Google-quality web, image, video, and news search results over a simple REST interface. Every request is a plain HTTP GET to a single endpoint — no SDKs required. You authenticate with an API key, target your Programmable Search Engine with a Search Engine ID, and supply a query string. Google returns a structured JSON response you can parse, display, or pipe into downstream processing.

Base URL and HTTP Method

All requests go to one endpoint, and the only supported HTTP method is GET:

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

Pass every parameter as a URL query string. The API does not accept POST bodies or other HTTP methods.

API Version

The current stable version is v1, reflected in the path. Google does not use version negotiation headers — the version is fixed in the URL. There is no beta or alpha path for the Custom Search JSON API; all production traffic uses v1.

Required Parameters

Every request must include the following three query parameters. Omitting any one of them returns a 400 Bad Request error.

string

required

Your Google API key. Create one in the Google Cloud Console. See the Authentication page for how to scope and restrict your key.

string

required

Your Programmable Search Engine ID (formerly “Custom Search Engine ID”). Create and manage engines at programmablesearchengine.google.com.

string

required

The search query. URL-encode spaces and special characters. Maximum length is 2,048 characters. Supports the same operators as Google Search (e.g., site:, filetype:, quoted phrases).

Common Optional Parameters

These parameters appear in most real-world requests. A full parameter reference follows in the sections below.

integer

Number of results to return. Accepted values: 1–10. Defaults to 10. To retrieve more than 10 results, use the start parameter for pagination.

integer

Zero-indexed offset for pagination. Accepted values: 1–91. Combined with num, the last addressable result is position 100 (start=91&num=10).

string

Set to image to restrict results to image search. Omit this parameter for web search (default).

string

SafeSearch setting. Use active to filter explicit content, or off to disable filtering. Defaults to off.

string

Restrict results to a specific language. Example: lr=lang_en for English, lr=lang_fr for French.

string

Geolocation of the end user. A two-letter ISO 3166-1 country code (e.g., us, gb, de). Influences result ranking for local relevance.

Content Type

The API always returns Content-Type: application/json; charset=UTF-8. There is no XML mode, JSONP callback, or alternate content type available for the Custom Search JSON API.

Minimal Working Example

The example below searches for "machine learning" using a real endpoint call. Replace YOUR_API_KEY and YOUR_CX with your credentials.

curl -G "https://www.googleapis.com/customsearch/v1" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "cx=YOUR_CX" \
  --data-urlencode "q=machine learning" \
  --data-urlencode "num=2"

import requests

params = {
    "key": "YOUR_API_KEY",
    "cx":  "YOUR_CX",
    "q":   "machine learning",
    "num": 2,
}

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

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

import fetch from "node-fetch";

const params = new URLSearchParams({
  key: "YOUR_API_KEY",
  cx:  "YOUR_CX",
  q:   "machine learning",
  num: "2",
});

const res = await fetch(
  `https://www.googleapis.com/customsearch/v1?${params}`
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();

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

Example Response

A successful response returns HTTP 200 OK with a JSON body structured like this:

{
  "kind": "customsearch#search",
  "url": {
    "type": "application/json",
    "template": "https://www.googleapis.com/customsearch/v1?q={searchTerms}&..."
  },
  "queries": {
    "request": [
      {
        "title": "Google Custom Search - machine learning",
        "totalResults": "4180000000",
        "searchTerms": "machine learning",
        "count": 2,
        "startIndex": 1,
        "inputEncoding": "utf8",
        "outputEncoding": "utf8",
        "safe": "off",
        "cx": "YOUR_CX"
      }
    ],
    "nextPage": [
      {
        "title": "Google Custom Search - machine learning",
        "totalResults": "4180000000",
        "searchTerms": "machine learning",
        "count": 2,
        "startIndex": 3,
        "inputEncoding": "utf8",
        "outputEncoding": "utf8",
        "safe": "off",
        "cx": "YOUR_CX"
      }
    ]
  },
  "searchInformation": {
    "searchTime": 0.248132,
    "formattedSearchTime": "0.25",
    "totalResults": "4180000000",
    "formattedTotalResults": "4,180,000,000"
  },
  "items": [
    {
      "kind": "customsearch#result",
      "title": "Machine Learning  |  Google for Developers",
      "htmlTitle": "<b>Machine Learning</b> | Google for Developers",
      "link": "https://developers.google.com/machine-learning",
      "displayLink": "developers.google.com",
      "snippet": "Explore Google's machine learning resources, courses, and tools...",
      "htmlSnippet": "Explore Google&#39;s <b>machine learning</b> resources, courses, and tools...",
      "cacheId": "abc123XYZ",
      "formattedUrl": "https://developers.google.com/machine-learning",
      "htmlFormattedUrl": "https://developers.google.com/<b>machine-learning</b>",
      "pagemap": {
        "metatags": [
          {
            "og:title": "Machine Learning | Google for Developers",
            "og:description": "Explore Google's machine learning resources..."
          }
        ]
      }
    }
  ]
}

Response Top-Level Fields

string

Always "customsearch#search". Identifies the resource type.

object

A URL template that describes the OpenSearch-compatible query structure for this API.

object

Metadata about the current request and adjacent pages. Contains request (current page) and optionally nextPage and previousPage arrays, each with one element describing pagination offsets.

object

Metadata about your Programmable Search Engine, including its name and any custom facets you have configured.

object

Timing and total result count. Key sub-fields: searchTime (seconds, float), formattedSearchTime, totalResults (string), formattedTotalResults.

array

The list of search result objects. Present only when results exist. Each element is a customsearch#result object — see the table below for per-item fields.

`items[]` Object Fields

string

Always "customsearch#result".

string

The plain-text page title.

string

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

string

The canonical URL of the result page.

string

A human-readable version of the URL (hostname only, no path).

string

A plain-text excerpt from the result page relevant to the query.

string

The snippet with query terms highlighted in <b> tags.

string

Google’s cached version identifier. May be absent for some results.

string

A formatted version of link for display.

string

A formatted URL with query terms highlighted.

object

Structured metadata extracted from the page: Open Graph tags, schema.org markup, thumbnails, and more. Contents vary by page.

object

Present only for searchType=image results. Contains contextLink, height, width, byteSize, thumbnailLink, thumbnailHeight, thumbnailWidth.

Pagination

The API exposes a maximum of 100 results per query (10 pages of 10 results). Use start to move through pages:

Page	`start`	`num`
1	1	10
2	11	10
3	21	10
…	…	…
10	91	10

Setting start higher than 91 or requesting results beyond position 100 returns an error. The totalResults figure in searchInformation is an estimate and may exceed 100; only the first 100 are addressable.

Rate Limits and Quotas

The free tier allows 100 queries per day per project. The paid tier supports up to 10,000 queries per day per project (billed per 1,000 additional queries beyond the free tier). Exceeding your quota returns a 403 error. See the Errors page for handling strategies.

Authentication

How to create, restrict, and rotate your API key. Includes header-based and query-parameter authentication examples.

Error Codes

Full reference for every HTTP error the API returns, with resolution steps and example error bodies.

​Base URL and HTTP Method

​API Version

​Required Parameters

​Common Optional Parameters

​Content Type

​Minimal Working Example

​Example Response

​Response Top-Level Fields

​items[] Object Fields

​Pagination

​Rate Limits and Quotas

​Related Pages

Authentication

Error Codes

Base URL and HTTP Method

API Version

Required Parameters

Common Optional Parameters

Content Type

Minimal Working Example

Example Response

Response Top-Level Fields

`items[]` Object Fields

Pagination

Rate Limits and Quotas

Related Pages