Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cloro.dev/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
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.
Sponsored ads in Google Search

​
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:
SurfaceblockPositioncategory examples
Right-hand-side PLA carouselrhsSponsored products
Top-of-page PLA carouseltopSponsored products
Top-of-page sponsored shopping-card carouseltopSponsored 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.
Fields shared across all ad types:
FieldTypeDescription
positionnumberPosition within the ad block (1-indexed)
blockPositionstringWhere the ad appeared: top, bottom, middle, or rhs (see “Ad types”)
typestringRESULT for text ads; SHOPPING_CARD for shopping-style cards
titlestringAd title
urlstringDestination URL of the ad (Google aclk? redirect for SHOPPING_CARD)
pagenumberPage number where the ad was found
descriptionstringAd 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:
FieldTypeDescription
displayedUrlstringFormatted URL as displayed in the ad
domainstringDomain name of the advertiser
sitelinksarraySitelinks displayed under the ad
Fields specific to type: SHOPPING_CARD ads:
FieldTypeDescription
categorystringCarousel header label (e.g. Sponsored products, Sponsored vehicles)
priceobjectProduct price, shape { value: number, currency: string }
oldPriceobjectOriginal price before discount / MSRP, same shape as price
storestringMerchant or dealer name
imageUrlstringHero image URL served by Google’s encrypted-tbn CDN
FieldTypeDescription
urlstringSitelink URL
titlestringSitelink title
descriptionstringSitelink 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": "$" },
        "oldPrice": { "value": 35900, "currency": "$" },
        "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": "$" },
        "store": "Nike.com",
        "imageUrl": "https://encrypted-tbn0.gstatic.com/images?q=tbn:..."
      }
    ]
  }
}