API Reference › Google › Sponsored ads

Sponsored ads

Paid ad placements that Google mixes into its search results, returned as part of the Google Search response — covering both text ads and shopping-style sponsored cards.

Overview

Sponsored ads are not a standalone endpoint. Whenever you call the Google Search endpoint, any paid placements Google served for that query are parsed and returned inside a single ads array on the result. You never issue a separate request for them.

The array holds two kinds of entries: conventional text ads that appear above or below the main column, and shopping-oriented sponsored cards that appear in the right-hand carousel or in the carousels at the top of the page. Every entry carries a type field, and you branch on that value to know which shape to expect.

Ad types

The type discriminator takes one of two values:

Value	Meaning
`RESULT`	A standard text ad in the main column, with headline copy, an optional set of sitelinks, and a direct destination URL.
`SHOPPING_CARD`	A product card with an image, a price (and sometimes a prior price), a merchant name, and a Google `aclk?` redirect URL.

For SHOPPING_CARD entries, the blockPosition and category fields together tell you which carousel the card came from: the right-hand product carousel (rhs), the top-of-page product carousel (top), or a top-of-page sponsored carousel that may hold vehicles, hotels, or products. Switch on type first, then read blockPosition and category to resolve the exact surface.

Do not confuse a SHOPPING_CARD ad with the organic shoppingCards field. Sponsored cards are paid, live in ads, and use Google-redirected aclk? links. Organic shopping cards live in their own shoppingCards array and use hydrated product links.

Shared ad fields

These fields appear on every entry regardless of type:

Field	Type	Description
position	number	Rank of the ad inside its block, starting at 1.
blockPosition	string	Where the block sat on the page: `top`, `bottom`, `middle`, or `rhs`.
type	string	`RESULT` for text ads, `SHOPPING_CARD` for product cards.
title	string	The ad's headline text.
url	string	Destination link. For shopping cards this is a Google `aclk?` redirect.
page	number	Result page the ad was captured on.
description	string	Ad body copy for text ads; for shopping cards, category-specific subtitle fragments joined with `·`.

Text ad fields

Present only on type: RESULT entries:

Field	Type	Description
displayedUrl	string	The tidy URL shown to the user in the ad.
domain	string	The advertiser's domain.
sitelinks	array	Extra links rendered beneath the ad (see below).

Shopping card fields

Present only on type: SHOPPING_CARD entries:

Field	Type	Description
category	string	Header label of the carousel, such as `Sponsored products` or `Sponsored vehicles`.
price	object	Current product price (see Price shape).
oldPrice	object	Prior or list price before any discount, same shape as `price`.
store	string	Name of the merchant or dealer.
imageUrl	string	Product image served from Google's image CDN.

Price shape

Both price and oldPrice expose a parsed and a verbatim view of the price:

Field	Type	Description
value	number	Numeric amount, set only when the visible text parses cleanly into a number.
currency	string	Currency symbol (`$`, `£`, `€`) when one is recognized.
raw	string	The price string exactly as displayed, e.g. `"$1,199"` or `"$0 down with 24 monthly payments"`.

raw is always populated whenever a price is emitted, while value and currency appear only on an unambiguous parse. Installment or down-payment labels can parse a leading "$0" as value: 0, so lean on raw to tell a genuinely free item from financing copy.

Ad sitelinks

Each entry in a text ad's sitelinks array has this shape:

Field	Type	Description
url	string	Link target of the sitelink.
title	string	Sitelink label.
description	string	Short supporting text for the sitelink.

Response example

{
  "success": true,
  "result": {
    "ads": [
      {
        "position": 1,
        "blockPosition": "top",
        "type": "RESULT",
        "title": "Trail Running Shoes - Free Shipping",
        "url": "https://www.summitgear.com/trail",
        "page": 1,
        "displayedUrl": "www.summitgear.com/trail",
        "domain": "summitgear.com",
        "description": "Grip-tested trail shoes with free returns and next-day delivery.",
        "sitelinks": [
          {
            "url": "https://www.summitgear.com/trail/mens",
            "title": "Men's Trail",
            "description": "Rugged models built for loose terrain."
          },
          {
            "url": "https://www.summitgear.com/trail/womens",
            "title": "Women's Trail",
            "description": "Lightweight fits for long distances."
          }
        ]
      },
      {
        "position": 1,
        "blockPosition": "top",
        "type": "SHOPPING_CARD",
        "category": "Sponsored vehicles",
        "title": "2022 Toyota Tacoma SR5",
        "url": "https://www.google.com/aclk?sa=L&ai=...",
        "page": 1,
        "description": "Used - 61k miles · Boulder",
        "price": { "value": 28450, "currency": "$", "raw": "$28,450" },
        "oldPrice": { "value": 30990, "currency": "$", "raw": "$30,990" },
        "store": "Front Range Toyota",
        "imageUrl": "https://encrypted-tbn0.gstatic.com/images?q=tbn:..."
      },
      {
        "position": 2,
        "blockPosition": "rhs",
        "type": "SHOPPING_CARD",
        "category": "Sponsored products",
        "title": "Meridian Glide 7 Running Shoe",
        "url": "https://www.google.com/aclk?sa=L&ai=...",
        "page": 1,
        "price": { "value": 129.95, "currency": "$", "raw": "$129.95" },
        "store": "meridianrun.com",
        "imageUrl": "https://encrypted-tbn0.gstatic.com/images?q=tbn:..."
      }
    ]
  }
}

Notes

Because sponsored placements are auction-driven, the contents of ads vary between identical queries and may be empty. Treat every type-specific field as optional and branch on type before reading it. Questions about parsing edge cases can go to [email protected].