Search Result Response Structure and Schema

The Custom Search JSON API returns a single JSON object for every successful GET request to https://www.googleapis.com/customsearch/v1. Before you parse individual results, take a moment to understand the full shape of that object — knowing where totalResults lives versus where each result’s URL lives will save you debugging time later.

Top-Level Response Object

Every response contains the following top-level fields regardless of whether results were found.

string

required

Identifies the resource type. Always "customsearch#search" for Custom Search API responses.

object

Describes the OpenSearch URL template for this API. Primarily used by OpenSearch-compatible clients to construct queries dynamically.

Show url fields

string

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

string

The OpenSearch-compatible URL template string including all supported query parameters.

object

Contains metadata about the current search query, the next page of results, and the previous page of results. See Queries Object below for full field details.

object

Reflects configuration from your Programmable Search Engine, including the engine’s human-readable title and any custom facet labels you have defined.

Show context fields

string

The name of your Programmable Search Engine as configured in the Control Panel.

array

An array of facet label objects if you have defined refinement labels in your engine. Each element has an anchor (display name) and a label (machine name).

object

Contains aggregate statistics about the search, such as how long it took and the estimated number of results. See Search Information below.

array

An array of search result objects. Each element represents one matching page or image. The array contains between 1 and 10 elements per page (controlled by the num parameter). This field is absent from the response when there are no results — always check for its existence before iterating.

Queries Object

The queries object contains up to three keys: request, nextPage, and previousPage. Each key holds an array with exactly one element — an object describing that query context.

array

Always present. Describes the query that produced the current response.

Show request element fields

string

The title of the search engine, matching context.title.

string

Estimated total number of results as a string (e.g., "1410000000"). Note this is a string, not a number.

string

The query string exactly as submitted in the q parameter.

integer

The number of results returned in this response. Between 1 and 10.

integer

The 1-based index of the first result in this response. For the first page this is 1; for the second page it is 11.

string

The language restriction applied, if any (e.g., "lang_en"). Corresponds to the lr request parameter.

string

The character encoding of the request. Always "utf8".

string

The character encoding of the response. Always "utf8".

string

The SafeSearch setting in effect: "active" or "off".

string

The Programmable Search Engine ID used for this request.

array

Present when there is a subsequent page of results. Contains one element with the same fields as request, but with startIndex advanced by count. Absent when the current page is the last page or when startIndex + count > 100.

array

Present when the current page is not the first page (startIndex > 1). Contains one element with the same fields as request, but with startIndex decremented by count.

Search Information

number

The time, in seconds, that the backend search took to execute. This is a floating-point number such as 0.237891.

string

A locale-formatted string version of searchTime, for display purposes (e.g., "0.24").

string

The estimated total number of results matching the query, as a string. This number is an approximation and may differ from page to page.

string

A locale-formatted, comma-separated string of totalResults for display (e.g., "1,410,000,000").

Item Fields

Each object in the items array represents one search result. The fields present depend on whether the result is a web page or an image (searchType=image).

string

Always "customsearch#result".

string

The plain-text title of the result page, as shown in search results.

string

The title with HTML markup. Query terms that appear in the title are wrapped in <b> tags. Use this field when rendering results in an HTML context.

string

The full canonical URL of the result. Use this as the href for the result link.

string

A shortened, human-readable version of the URL suitable for display beneath the title (e.g., "docs.example.com").

string

A plain-text excerpt from the page that summarizes its content in relation to the query. See Snippets for full details.

string

The same excerpt as snippet but with matching query terms wrapped in <b> tags and line breaks replaced with <br> tags. See Snippets for full details.

string

Google’s cached copy identifier. Combine with https://webcache.googleusercontent.com/search?q=cache:<cacheId> to link to the cached version. Not always present.

string

The URL with spaces and special characters decoded for display.

string

The formatted URL with query terms highlighted in <b> tags.

object

A structured data map extracted from the page. Contains keys such as metatags, cse_image, cse_thumbnail, article, product, person, and others depending on the structured data present on the page. The presence and shape of this object vary widely between results.

Show Common pagemap keys

array

An array (usually one element) of objects containing <meta> tag values from the page’s <head>. Common keys include og:title, og:description, og:image, twitter:card, and viewport.

array

Images Google has associated with this result. Each element has a src URL.

array

Smaller thumbnail images associated with the result. Each element has src, width, and height.

object

Present only for image search results (searchType=image). Contains details about the image itself.

Show image fields

string

The URL of the page that hosts the image.

integer

The height of the image in pixels.

integer

The width of the image in pixels.

integer

The file size of the image in bytes.

string

URL of a thumbnail version of the image served by Google.

integer

Height of the thumbnail in pixels.

integer

Width of the thumbnail in pixels.

Complete Annotated Example

The following is a representative response for the query "open source vector database" with num=2. Fields are annotated with inline comments for clarity.

{
  // Identifies this as a Custom Search response
  "kind": "customsearch#search",

  // OpenSearch URL template descriptor
  "url": {
    "type": "application/json",
    "template": "https://www.googleapis.com/customsearch/v1?q={searchTerms}&num={count?}&start={startIndex?}&lr={language?}&safe={safe?}&cx={cx?}&sort={sort?}&filter={filter?}&gl={gl?}&cr={cr?}&googlehost={googleHost?}&c2coff={disableCnTwTranslation?}&hq={hq?}&hl={hl?}&siteSearch={siteSearch?}&siteSearchFilter={siteSearchFilter?}&exactTerms={exactTerms?}&excludeTerms={excludeTerms?}&linkSite={linkSite?}&orTerms={orTerms?}&dateRestrict={dateRestrict?}&lowRange={lowRange?}&highRange={highRange?}&searchType={searchType}&fileType={fileType?}&rights={rights?}&imgSize={imgSize?}&imgType={imgType?}&imgColorType={imgColorType?}&imgDominantColor={imgDominantColor?}&alt=json"
  },

  "queries": {
    // Describes this exact request
    "request": [
      {
        "title": "My App Search Engine",
        "totalResults": "142000000",   // String, not integer
        "searchTerms": "open source vector database",
        "count": 2,                    // Results on this page
        "startIndex": 1,               // 1-based; first page
        "inputEncoding": "utf8",
        "outputEncoding": "utf8",
        "safe": "off",
        "cx": "017576662512468239146:omuauf_lfve"
      }
    ],
    // Pagination cursor — use startIndex=11 for the next page
    "nextPage": [
      {
        "title": "My App Search Engine",
        "totalResults": "142000000",
        "searchTerms": "open source vector database",
        "count": 2,
        "startIndex": 3,
        "inputEncoding": "utf8",
        "outputEncoding": "utf8",
        "safe": "off",
        "cx": "017576662512468239146:omuauf_lfve"
      }
    ]
  },

  // Engine-level metadata
  "context": {
    "title": "My App Search Engine"
  },

  // Aggregate search statistics
  "searchInformation": {
    "searchTime": 0.391248,
    "formattedSearchTime": "0.39",
    "totalResults": "142000000",
    "formattedTotalResults": "142,000,000"
  },

  // The actual result items
  "items": [
    {
      "kind": "customsearch#result",
      "title": "Milvus — Open-Source Vector Database",
      "htmlTitle": "Milvus — <b>Open-Source</b> <b>Vector</b> <b>Database</b>",
      "link": "https://milvus.io/",
      "displayLink": "milvus.io",
      "snippet": "Milvus is an open-source vector database built for scalable similarity search. Power your AI applications with high-performance, cloud-native infrastructure.",
      "htmlSnippet": "Milvus is an <b>open-source</b> <b>vector</b> <b>database</b> built for scalable similarity search. Power your AI applications with high&#8209;performance, cloud&#8209;native infrastructure.",
      "cacheId": "abc123XYZ",
      "formattedUrl": "https://milvus.io/",
      "htmlFormattedUrl": "https://milvus.io/",
      "pagemap": {
        "metatags": [
          {
            "og:title": "Milvus — Open-Source Vector Database",
            "og:description": "Build AI applications with the world's most advanced open-source vector database.",
            "og:image": "https://milvus.io/images/og-image.png",
            "viewport": "width=device-width, initial-scale=1"
          }
        ],
        "cse_image": [
          { "src": "https://milvus.io/images/hero.png" }
        ]
      }
    },
    {
      "kind": "customsearch#result",
      "title": "Weaviate: The AI-Native Vector Database",
      "htmlTitle": "Weaviate: The AI-Native <b>Vector</b> <b>Database</b>",
      "link": "https://weaviate.io/",
      "displayLink": "weaviate.io",
      "snippet": "Weaviate is an open-source vector database that stores both objects and vectors. Run locally or fully managed in the cloud.",
      "htmlSnippet": "Weaviate is an <b>open-source</b> <b>vector</b> <b>database</b> that stores both objects and vectors. Run locally or fully managed in the cloud.",
      "formattedUrl": "https://weaviate.io/",
      "htmlFormattedUrl": "https://weaviate.io/",
      "pagemap": {
        "metatags": [
          {
            "og:title": "Weaviate: The AI-Native Vector Database",
            "og:description": "Open-source vector database for AI-powered search and semantic retrieval.",
            "viewport": "width=device-width, initial-scale=1"
          }
        ]
      }
    }
  ]
}

The items field is omitted entirely from the response when no results are found. Always guard against its absence in your code before iterating:

const results = response.items ?? [];

Use queries.nextPage[0].startIndex as the value for your next start parameter to paginate through results. The API supports pagination up to start=91 (results 91–100), giving you a maximum of 100 results per query.

​Top-Level Response Object

​Queries Object

​Search Information

​Item Fields

​Complete Annotated Example

Top-Level Response Object

Queries Object

Search Information

Item Fields

Complete Annotated Example