Google Search sponsored ads schema

This section documents the sponsored ads data returned by the Google Search endpoint. Sponsored ads are part of the Google response, so no separate API call is needed. For use cases, pricing context, and copy-paste examples, see the Google ads scraper page on the product site.

Example request

{
  "query": "running shoes",
  "country": "US"
}

This produces a response containing the ads array documented below.

Overview

Sponsored ads are paid placements Google injects into the SERP. They cover both classic text ads (top and bottom of the page) and shopping-style sponsored cards (right-hand-side carousel and top-of-page carousels). All sponsored entries share the same ads[] array — the type field discriminates them.

Ad types

Each ad carries a type discriminator with two values:

RESULT — plain text ad. Displayed at the top or bottom of the main column with ad copy, sitelinks, and a normal destination URL.
SHOPPING_CARD — shopping-style sponsored card. Carries a product image, price, optional MSRP / oldPrice, merchant name, and a Google-redirected aclk? destination URL.

SHOPPING_CARD ads surface on three SERP positions, distinguished by blockPosition and category:

Surface	`blockPosition`	`category` examples
Right-hand-side PLA carousel	`rhs`	`Sponsored products`
Top-of-page PLA carousel	`top`	`Sponsored products`
Top-of-page sponsored shopping-card carousel	`top`	`Sponsored vehicles`, `Sponsored products`, `Sponsored hotels`

To discriminate, switch on type first; for SHOPPING_CARD items use blockPosition + category to identify the surface.

Sponsored products carousel on the Google SERP

Do not confuse type: SHOPPING_CARD ads with the organic shoppingCards field. Sponsored cards live in ads[], are paid placements, and use Google aclk?-redirected URLs. Organic shopping cards live in shoppingCards[], come from the “Popular products” / “More products” grids, and use JS-hydrated productLink URLs that are usually empty in the static HTML response.

Sponsored ad structure

Fields shared across all ad types:

Field	Type	Description
`position`	number	Position within the ad block (1-indexed)
`blockPosition`	string	Where the ad appeared: `top`, `bottom`, `middle`, or `rhs` (see “Ad types”)
`type`	string	`RESULT` for text ads; `SHOPPING_CARD` for shopping-style cards
`title`	string	Ad title
`url`	string	Destination URL of the ad (Google `aclk?` redirect for `SHOPPING_CARD`)
`page`	number	Page number where the ad was found
`description`	string	Ad description text (see note below)

For type: RESULT items, description is classic ad copy. For type: SHOPPING_CARD items it carries category-specific subtitle fragments joined with · — for example Used - 94k miles · Greeley on a “Sponsored vehicles” card.

Fields specific to type: RESULT text ads:

Field	Type	Description
`displayedUrl`	string	Formatted URL as displayed in the ad
`domain`	string	Domain name of the advertiser
`sitelinks`	array	Sitelinks displayed under the ad

Fields specific to type: SHOPPING_CARD ads:

Field	Type	Description
`category`	string	Carousel header label (e.g. `Sponsored products`, `Sponsored vehicles`)
`price`	object	Product price (see Price shape below)
`oldPrice`	object	Original price before discount / MSRP, same shape as `price`
`store`	string	Merchant or dealer name
`imageUrl`	string	Hero image URL served by Google’s `encrypted-tbn` CDN

Price shape

price and oldPrice carry both a parsed and a raw representation:

Field	Type	Description
`value`	number	Numeric price. Present when the visible string parses unambiguously into a number.
`currency`	string	Currency symbol (e.g. `$`, `£`, `€`). Present when a recognized symbol is detected.
`raw`	string	Visible price text verbatim (e.g. `"$1,199"`, `"$0 down with 24 monthly payments"`).

raw is always present when price is emitted. value and currency are populated only when the visible string parses unambiguously. Installment / down-payment labels (common on phone-contract cards) parse the leading "$0" as value: 0 — use raw to disambiguate genuine free items from down-payment phrasing.

Ad sitelinks

Field	Type	Description
`url`	string	Sitelink URL
`title`	string	Sitelink title
`description`	string	Sitelink description

Response example

{
  "success": true,
  "result": {
    "ads": [
      {
        "position": 1,
        "blockPosition": "top",
        "type": "RESULT",
        "title": "Running Shoes Sale - Up to 40% Off",
        "url": "https://www.acmeshoes.com/running",
        "page": 1,
        "displayedUrl": "www.acmeshoes.com/running",
        "domain": "acmeshoes.com",
        "description": "Shop top brands of running shoes with free shipping on orders over $50.",
        "sitelinks": [
          {
            "url": "https://www.acmeshoes.com/running/road",
            "title": "Road Running",
            "description": "Lightweight shoes for paved surfaces."
          },
          {
            "url": "https://www.acmeshoes.com/running/trail",
            "title": "Trail Running",
            "description": "Durable shoes for off-road terrain."
          }
        ]
      },
      {
        "position": 1,
        "blockPosition": "top",
        "type": "SHOPPING_CARD",
        "category": "Sponsored vehicles",
        "title": "2021 Ford F-150 XLT",
        "url": "https://www.google.com/aclk?sa=L&ai=...",
        "page": 1,
        "description": "Used - 94k miles · Greeley",
        "price": { "value": 32915, "currency": "$", "raw": "$32,915" },
        "oldPrice": { "value": 35900, "currency": "$", "raw": "$35,900" },
        "store": "Acme Ford",
        "imageUrl": "https://encrypted-tbn0.gstatic.com/images?q=tbn:..."
      },
      {
        "position": 1,
        "blockPosition": "rhs",
        "type": "SHOPPING_CARD",
        "category": "Sponsored products",
        "title": "Nike Pegasus 41",
        "url": "https://www.google.com/aclk?sa=L&ai=...",
        "page": 1,
        "price": { "value": 139.99, "currency": "$", "raw": "$139.99" },
        "store": "Nike.com",
        "imageUrl": "https://encrypted-tbn0.gstatic.com/images?q=tbn:..."
      }
    ]
  }
}

Overview

ChatGPT

Google

Perplexity

Copilot

AI Mode

Grok

Gemini

Google News

Utilities

Google Search sponsored ads schema

Example request

Overview

Ad types

Sponsored ad structure

Price shape

Ad sitelinks

Response example

​Example request

​Overview

​Ad types

​Sponsored ad structure

​Price shape

​Ad sitelinks

​Response example

Example request

Overview

Ad types

Sponsored ad structure

Price shape

Ad sitelinks

Response example