> ## Documentation Index
> Fetch the complete documentation index at: https://cloro.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Extract Google AI Mode
> Extract structured data from AI Mode about your brand, products, or any topic across various regions
## Overview
The Google AI Mode endpoint extracts structured data from Google AI Mode with automatic detection of [places](/api-reference/endpoint/aimode/places), [shopping cards](/api-reference/endpoint/aimode/shopping-cards), [ads](/api-reference/endpoint/aimode/ads), [inline products](/api-reference/endpoint/aimode/inline-products), [videos](/api-reference/endpoint/aimode/videos), and [map entries](/api-reference/endpoint/aimode/map).
**Web search enabled**
This endpoint uses AI Mode's default interface, which combines web search results with AI-generated responses.
## Request parameters
**Required parameters:**
* `prompt` (string): The query to send to AI Mode (1-10,000 characters)
**Optional parameters:**
* `country` (string): ISO 3166-1 alpha-2 country code for localized results. Defaults to `US`
* `location` (string): Google canonical location name for geo-targeted results (e.g., `New York,New York,United States`). See [Google's geo target list](https://developers.google.com/google-ads/api/reference/data/geotargets) for all \~100,000 supported locations. Mutually exclusive with `uule`
* `uule` (string): Pre-encoded Google UULE string for precise geo-targeting. Use this when you have a pre-built UULE value instead of a location name. Mutually exclusive with `location`
* `device` (string): Device type for search results. Options: `desktop` (default), `mobile`
* `include.markdown` (boolean): Include markdown-formatted response. Defaults to `false`
* `include.html` (boolean): Include raw HTML response. Defaults to `false`
## Response objects
The response includes the following sections. See each subpage for the full schema and examples.
| Section | Description |
| ----------------------------------------------------------------- | --------------------------------------------------------------- |
| [Sources](/api-reference/endpoint/aimode/sources) | Source citations referenced in the response |
| [Places](/api-reference/endpoint/aimode/places) | Inline place cards when location intent is detected |
| [Shopping cards](/api-reference/endpoint/aimode/shopping-cards) | Product carousel when shopping intent is detected |
| [Ads](/api-reference/endpoint/aimode/ads) | Sponsored ad section when commercial intent is detected |
| [Inline products](/api-reference/endpoint/aimode/inline-products) | Individual product references embedded in the response text |
| [Videos](/api-reference/endpoint/aimode/videos) | Inline video cards (currently YouTube) embedded in the response |
| [Map](/api-reference/endpoint/aimode/map) | GPS-enriched location data when map-aware results are surfaced |
## Response schema
Includes [common response fields](/guides/making-requests/sync#common-response-fields) plus:
### Core response fields
| Field | Type | Description |
| ----------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `result.text` | string | AI Mode's response text |
| `result.markdown` | string | Response formatted in Markdown (included when `include.markdown` is true). **Note:** this field is generated by converting Google's live DOM to markdown — order can shift as Google updates its DOM. |
| `result.sources` | array | Array of [sources](/api-reference/endpoint/aimode/sources) referenced in the response |
| `result.places` | array | Array of [places](/api-reference/endpoint/aimode/places) (when location intent detected) |
| `result.shoppingCards` | array | Array of [shopping cards](/api-reference/endpoint/aimode/shopping-cards) (when shopping intent detected) |
| `result.ads` | object | [Ad section](/api-reference/endpoint/aimode/ads) wrapper with title and ads array (when commercial intent detected) |
| `result.inlineProducts` | array | Array of [inline products](/api-reference/endpoint/aimode/inline-products) found within the response text |
| `result.videos` | array | Array of [videos](/api-reference/endpoint/aimode/videos) embedded in the response (currently YouTube) |
| `result.map` | array | Array of [map entries](/api-reference/endpoint/aimode/map) with GPS coordinates (when map-aware results surfaced) |
## Usage examples
### City-level geo-targeting
Use `location` with `country` to get AI Mode results targeted to a specific city or region. The `location` parameter accepts [Google canonical location names](https://developers.google.com/google-ads/api/reference/data/geotargets):
```json theme={null}
{
"prompt": "best restaurants nearby",
"country": "US",
"location": "New York,New York,United States"
}
```
### UULE geo-targeting
For advanced geo-targeting, use `uule` with a pre-encoded Google UULE string instead of `location`. This is useful when you generate your own UULE values for precise location control:
```json theme={null}
{
"prompt": "best restaurants nearby",
"country": "US",
"uule": "w+CAIQICIeV2VzdCBOZXcgWW9yayxOZXcgSmVyc2V5"
}
```
`location` and `uule` are mutually exclusive: provide one or the other, not both. Use `location` for city-level targeting with canonical names, and `uule` when you need to supply a pre-encoded UULE string.
## OpenAPI
````yaml api-reference/openapi.json POST /v1/monitor/aimode
openapi: 3.1.0
info:
title: cloro
description: API for monitoring AI responses across different providers and regions
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.cloro.dev
description: Production server
security:
- bearerAuth: []
paths:
/v1/monitor/aimode:
post:
summary: Monitor AI Mode Responses
description: >-
Extract structured data from AI Mode about your brand, products, or any
topic across various regions
operationId: monitorAiMode
requestBody:
description: Request parameters for monitoring AI Mode responses
content:
application/json:
schema:
$ref: '#/components/schemas/AiModeMonitorRequest'
required: true
responses:
'200':
description: successful AI Mode monitoring response
headers:
X-Concurrent-Limit:
description: Maximum number of concurrent requests allowed
schema:
type: integer
example: 10
X-Concurrent-Current:
description: Current number of concurrent requests
schema:
type: integer
example: 3
X-Concurrent-Remaining:
description: Number of remaining concurrent slots available
schema:
type: integer
example: 7
X-Credits-Remaining:
description: Number of credits remaining in user account
schema:
type: integer
example: 4
X-Credits-Charged:
description: Number of credits charged for this request
schema:
type: integer
example: 5
content:
application/json:
schema:
$ref: '#/components/schemas/AiModeMonitorResponse'
'400':
description: Bad Request - Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'401':
description: Unauthorized - Authentication error
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationError'
'403':
description: Forbidden - Insufficient permissions or credits
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Not Found - Route not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: Conflict - Resource conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'429':
description: Too Many Requests
headers:
X-Concurrent-Limit:
description: Maximum number of concurrent requests allowed
schema:
type: integer
example: 10
X-Concurrent-Current:
description: Current number of concurrent requests
schema:
type: integer
example: 11
X-Concurrent-Remaining:
description: Number of remaining concurrent slots available
schema:
type: integer
example: 0
X-Credits-Remaining:
description: Number of credits remaining in user account
schema:
type: integer
example: 4
X-Credits-Charged:
description: Number of credits charged for this request
schema:
type: integer
example: 0
content:
application/json:
schema:
$ref: '#/components/schemas/ConcurrentLimitError'
'499':
description: Client Closed Request - Request was canceled
content:
application/json:
schema:
$ref: '#/components/schemas/CanceledError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'502':
description: Bad Gateway - External service error
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalServiceError'
components:
schemas:
AiModeMonitorRequest:
required:
- prompt
- country
type: object
properties:
prompt:
description: The prompt to send to AI Mode
type: string
minLength: 1
maxLength: 10000
example: What are the best laptops for programming?
country:
description: Country/region code for localized response
type: string
example: US
location:
description: >-
Google canonical location name for geo-targeted results, in
comma-separated format: 'City,Region,Country' (see
https://developers.google.com/google-ads/api/reference/data/geotargets
for all ~100,000 supported locations). Use alongside 'country' for
city-level precision. Mutually exclusive with 'uule' — provide one
or the other, not both.
type: string
example: New York,New York,United States
uule:
description: >-
Pre-encoded Google UULE string for precise geo-targeting. Use this
when you have a pre-built UULE value instead of a location name.
Mutually exclusive with 'location' — provide one or the other, not
both.
type: string
example: w+CAIQICIeV2VzdCBOZXcgWW9yayxOZXcgSmVyc2V5
device:
description: Device type for search results
type: string
enum:
- desktop
- mobile
default: desktop
example: desktop
include:
description: Optional flags for including additional response formats
type: object
properties:
html:
description: Include a URL to the full HTML of the response
type: boolean
default: false
example: true
markdown:
description: Include markdown-formatted response in the result
type: boolean
default: false
example: true
default:
html: false
markdown: false
additionalProperties: false
additionalProperties: false
AiModeMonitorResponse:
required:
- success
- result
type: object
properties:
success:
type: boolean
example: true
result:
description: AI Mode response data
type: object
properties:
text:
type: string
description: AI Mode's response text
example: >-
Here are some excellent laptop recommendations for
programming...
html:
type: string
format: uri
description: A URL to the full HTML of the response.
example: >-
https://storage.cloro.dev/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html
sources:
type: array
description: Array of sources referenced in the response
items:
type: object
properties:
position:
type: number
description: The position index of the source in the response
example: 1
url:
type: string
description: The URL of the source
example: https://example.com/article
label:
type: string
description: The display label for the source
example: AI Source
description:
type: string
description: A description of the source content
example: AI-generated recommendations
example:
- position: 1
url: https://example.com/ai-recommendations
label: AI Source
description: AI-curated laptop recommendations
citationPills:
type: array
description: >-
Inline citation pills extracted from the AI Mode answer. Each
entry is one (pill, source) pair: when a pill cites N sources
(Google's `[Label +N]` chips), the array contains N entries
sharing the same `citationPillId` but carrying per-source
`label`, `url`, and `domain`. Group by `citationPillId` to
recover the pill-level structure. Omitted from `result` when the
answer carries no pills.
items:
type: object
required:
- label
- citationPillId
- url
- domain
- position
properties:
label:
type: string
description: >-
Per-source title from the sources rail (for example `"Best
Laptops 2026 — Reuters"`). Empty string when the rail has
no title for this source — consumers should read `domain`
/ `url` for source identity in that case. Entries grouped
under the same `citationPillId` carry different per-source
labels.
example: Best Laptops 2026 — Reuters
citationPillId:
type: integer
description: >-
1-based ordinal shared by all entries from the same chip.
Group by `citationPillId` to reconstruct the visible chip;
the per-source `label` differs across entries within a
chip.
example: 1
url:
type: string
description: Direct URL of the cited source.
example: https://example.com/best-laptops-2026
domain:
type: string
description: Host extracted from `url`, for grouping and display.
example: example.com
description:
type: string
description: >-
Source description from the sources rail when Google ships
one. Omitted when the source carries no snippet.
example: >-
A guide to the top laptops for software development this
year.
position:
type: integer
description: >-
1-based position of this source in the sibling
`result.sources` array.
example: 1
example:
- label: Best Laptops 2026 — Reuters
citationPillId: 1
url: https://example.com/best-laptops-2026
domain: example.com
description: >-
A guide to the top laptops for software development this
year.
position: 1
- label: MacBook Pro M4 Hands-On Review
citationPillId: 1
url: https://example.com/macbook-pro-review
domain: example.com
position: 3
markdown:
type: string
description: >-
AI Mode's response formatted in Markdown (included when
include.markdown is true)
example: >-
Here are some excellent laptop recommendations for
programming...
places:
type: array
description: Inline place cards extracted from the response
items:
type: object
properties:
title:
type: string
description: Place name
example: Gion District
link:
type: string
format: uri
description: Google viewer URL for the place
example: https://www.google.com/viewer/place?mid=/g/11bw3yq9kp
placeId:
type: string
description: Google Places ID
example: /g/11bw3yq9kp
index:
type: integer
description: Position index of the place in the results
example: 0
thumbnail:
type: string
format: uri
description: Place thumbnail image URL
example: https://lh5.googleusercontent.com/p/example
rating:
type: number
description: Star rating (0-5)
example: 4.5
reviews:
type: integer
description: Number of reviews
example: 2900
type:
type: string
description: Place type or category
example: Tourist attraction
priceLevel:
type: string
description: Price level indicator
example: $$
address:
type: string
description: Full address
example: Gionmachi, Higashiyama Ward, Kyoto
status:
type: string
description: Operating status
example: Open now
shoppingCards:
type: array
description: Shopping product information extracted from the response
items:
type: object
properties:
title:
type: string
description: Product title
example: Wireless Headphones
price:
type: object
description: Structured pricing information
properties:
value:
type: number
description: Numeric price
example: 99.99
currency:
type: string
description: Currency symbol
example: $
raw:
type: string
description: >-
Raw price string as returned by the upstream provider
(e.g. "$129.99").
example: $129.99
store:
type: string
description: Merchant/store name
example: Amazon
rating:
type: number
description: Product rating
example: 4.2
reviews:
type: string
description: Review count
example: 2.3k
thumbnail:
type: string
format: uri
description: Product image
example: https://example.com/product.jpg
productLink:
type: string
format: uri
description: Direct product URL
example: https://www.google.com/example
oldPrice:
type: object
description: Original price before discount
properties:
value:
type: number
description: Numeric price
example: 129.99
currency:
type: string
description: Currency symbol
example: $
raw:
type: string
description: >-
Raw price string as returned by the upstream provider
(e.g. "$129.99").
example: $129.99
snippet:
type: string
description: Product description snippet
example: >-
Noise-canceling wireless headphones with 30-hour battery
life
snippet_links:
type: array
description: Links found within the product snippet
items:
type: object
properties:
text:
type: string
description: Link text
example: noise canceling
link:
type: string
format: uri
description: Link URL
example: https://www.google.com/search?q=noise+canceling
position:
type: integer
description: >-
Position of the product card in the shopping carousel
(0-indexed).
example: 0
ads:
type: object
description: Sponsored ad section extracted from the response
properties:
title:
type: string
description: Section title for the ads
example: Here are some 3D printers to consider
ads:
type: array
description: Array of sponsored ads
items:
type: object
properties:
title:
type: string
description: Ad product title
example: Bambu Lab X2D
url:
type: string
format: uri
description: Ad click-through URL
example: https://www.google.com/aclk?sa=L&ai=abc
position:
type: integer
description: Position index of the ad
example: 1
price:
type: object
description: Structured pricing information
properties:
value:
type: number
description: Numeric price
example: 899
currency:
type: string
description: Currency symbol
example: $
store:
type: string
description: Merchant/store name
example: Bambu Lab US
rating:
type: number
description: Product rating
example: 4.7
reviews:
type: string
description: Review count
example: '584'
inlineProducts:
type: array
description: Inline product cards found within the AI response text
items:
type: object
properties:
title:
type: string
description: Product title
example: Sony WH-1000XM5
position:
type: integer
description: >-
1-indexed rank across the `inline_products` array in
DOM/render order.
example: 1
price:
type: object
description: Structured pricing information
properties:
value:
type: number
description: Numeric price
example: 298
currency:
type: string
description: Currency symbol
example: $
oldPrice:
type: object
description: Original price before discount
properties:
value:
type: number
description: Numeric price
example: 399.99
currency:
type: string
description: Currency symbol
example: $
store:
type: string
description: Merchant/store name
example: Amazon
thumbnail:
type: string
format: uri
description: Product image URL
example: https://encrypted-tbn0.gstatic.com/images?q=example
productLink:
type: string
format: uri
description: Direct product URL
example: https://www.google.com/shopping/product/example
videos:
type: array
description: >-
Inline video cards embedded in the AI response (currently
YouTube)
items:
type: object
required:
- title
- link
properties:
title:
type: string
description: Video title
example: The BEST 3D Printer for YOU - Don't Buy the Wrong One!
link:
type: string
format: uri
description: Canonical watch URL (timestamp parameters stripped)
example: https://www.youtube.com/watch?v=g0DZnQdI-xQ
platform:
type: string
description: Hosting platform parsed from the card byline
example: YouTube
channel:
type: string
description: Channel or uploader name
example: 3D Print Dood
duration:
type: string
description: Visible duration label (mm:ss or hh:mm:ss)
example: '08:49'
thumbnail:
type: string
format: uri
description: Public thumbnail URL
example: >-
https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcS5Bntg3F0Y7P3YgTPgdyillyeCguV_YQJ99KFUmNYxmQtVt1f2
map:
type: array
description: GPS-enriched location data extracted from the response
items:
type: object
properties:
title:
type: string
description: Place name
example: Central Park Cafe
link:
type: string
format: uri
description: Google viewer URL for the place
example: https://www.google.com/viewer/place?mid=/g/11bw3yq9kp
placeId:
type: string
description: Google Places ID
example: /g/11bw3yq9kp
index:
type: integer
description: Position index of the place in the results
example: 0
gps_coordinates:
type: object
description: Geographic coordinates of the place
properties:
latitude:
type: number
description: Latitude coordinate
example: 40.7831
longitude:
type: number
description: Longitude coordinate
example: -73.9712
thumbnail:
type: string
format: uri
description: Place thumbnail image URL
example: https://lh5.googleusercontent.com/p/example
rating:
type: number
description: Star rating (0-5)
example: 4.5
reviews:
type: integer
description: Number of reviews
example: 1234
type:
type: string
description: Place type or category
example: Coffee shop
address:
type: string
description: Full address
example: 123 Broadway, New York
status:
type: string
description: Operating status
example: Open now
ValidationError:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Request validation failed
details:
type: array
items:
type: object
properties:
field:
type: string
example: prompt
message:
type: string
example: Prompt cannot be empty
AuthenticationError:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- MISSING_API_KEY
- INVALID_API_KEY_FORMAT
- INVALID_OR_EXPIRED_API_KEY
example: MISSING_API_KEY
message:
type: string
example: Missing or invalid API key
timestamp:
type: string
format: date-time
example: '2025-01-15T12:00:00.000Z'
ForbiddenError:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- INSUFFICIENT_PERMISSIONS
- INSUFFICIENT_CREDITS
example: INSUFFICIENT_PERMISSIONS
message:
type: string
example: Insufficient permissions
details:
type: object
properties:
requiredScopes:
type: array
items:
type: string
example:
- read:monitor
- write:monitor
required: []
timestamp:
type: string
format: date-time
example: '2025-01-15T12:00:00.000Z'
NotFoundError:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: RESOURCE_NOT_FOUND
message:
type: string
example: Route not found
details:
type: object
properties:
id:
type: string
example: /v1/invalid-endpoint
timestamp:
type: string
format: date-time
example: '2025-01-15T12:00:00.000Z'
ConflictError:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: RESOURCE_CONFLICT
message:
type: string
example: Resource conflict
timestamp:
type: string
format: date-time
example: '2025-01-15T12:00:00.000Z'
ConcurrentLimitError:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: CONCURRENT_LIMIT_EXCEEDED
message:
type: string
example: Concurrent limit exceeded
details:
type: object
properties:
limit:
type: number
example: 10
timestamp:
type: string
format: date-time
example: '2025-01-15T12:00:00.000Z'
CanceledError:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Request was canceled
InternalError:
type: object
oneOf:
- properties:
success:
type: boolean
example: false
error:
type: string
example: Maximum retries exceeded
- properties:
error:
type: object
properties:
code:
type: string
example: INTERNAL_SERVER_ERROR
message:
type: string
example: Internal server error
timestamp:
type: string
format: date-time
example: '2025-01-15T12:00:00.000Z'
ExternalServiceError:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: EXTERNAL_SERVICE_ERROR
message:
type: string
example: 'External service error: OpenAI'
details:
type: object
properties:
service:
type: string
example: OpenAI
timestamp:
type: string
format: date-time
example: '2025-01-15T12:00:00.000Z'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````