Google AI Mode API

Request

curl -X POST "https://api.answerline.dev/v1/monitor/aimode" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Family-friendly hotels in Lisbon","country":"PT","hl":"en"}'

import { Client } from "@answerline/sdk";

const client = new Client({ apiKey: process.env.API_KEY! });
const answer = await client.monitor.aimode({
  "prompt": "Family-friendly hotels in Lisbon",
  "country": "PT",
  "hl": "en"
});

import os
from answerline import Client

with Client(os.environ["API_KEY"]) as client:
    answer = client.monitor.aimode(
        prompt="Family-friendly hotels in Lisbon",
        country="PT",
        hl="en",
    )

Every request option is on the Google AI Mode reference page.

What you get back

Full field definitions are on the Google AI Mode reference page.

AI Mode answers versus Google’s developer APIs

Google AI Mode is Google Search’s conversational answer surface. This endpoint returns that answer for a prompt, market, city and language, with citation pills, places, map pins, shopping cards, videos and, when Google shows sponsored products, ads as structured fields. inlineProducts is in the schema and comes back empty: Google shows an inline product mention without a name or price.

Google’s long-standing developer route to search results is the Custom Search JSON API. Its overview (checked 2026-09-17, developers.google.com) says it returns web and image results from a Programmable Search Engine, offers 100 free queries per day and $5 per 1,000 beyond that up to 10,000 per day, is closed to new customers, and gives existing customers until January 1, 2027 to transition. Its cse.list reference (checked 2026-09-17, developers.google.com) documents gl, hl, cr and lr parameters and does not mention AI Overviews, ads, local packs or knowledge panels.

In AI Mode users read a composed response instead of scanning ten links, so whether your brand is named, and in which sentence, is the visibility metric. Citations appear as [Label +N] chips that bundle several sources; citationPills records every source behind every chip, so you can measure both “cited at all” and “cited first in a chip”. Products (shoppingCards), sponsored products (ads), local businesses (places, map) and videos sit inside the answer and vary by location and device.

An annotated response

The excerpt follows the result schema for POST /v1/monitor/aimode. Values are illustrative.

{
  "success": true,
  "result": {
    "text": "For families, look for hotels near the riverfront with interconnecting rooms...",
    "sources": [
      {
        "position": 1,
        "url": "https://www.example-travel.com/lisbon/family-hotels",
        "label": "Best family hotels in Lisbon",
        "description": "Rooms for four, pools and quiet streets..."
      }
    ],
    // One entry per (chip, source). citationPillId is 1-based; position points
    // into result.sources. redirectLink appears only when Google served a /goto link.
    "citationPills": [
      {
        "label": "Best family hotels in Lisbon",
        "citationPillId": 1,
        "url": "https://www.example-travel.com/lisbon/family-hotels",
        "domain": "example-travel.com",
        "position": 1
      }
    ],
    "places": [
      {
        "title": "Example Riverside Hotel",
        "link": "https://www.google.com/viewer/place?example",
        "placeId": "ChIJexampleLisbon",
        "index": 0,
        "rating": 4.6,
        "reviews": 2140,
        "type": "Hotel",
        "priceLevel": "€€€",
        "address": "Rua Exemplo 10, Lisboa"
      }
    ],
    "map": [
      {
        "title": "Example Riverside Hotel",
        "placeId": "ChIJexampleLisbon",
        "gps_coordinates": { "latitude": 38.707, "longitude": -9.136 },
        "rating": 4.6
      }
    ],
    // position is 0-indexed within the shopping carousel.
    "shoppingCards": [],
    // ads is an object: a section title plus the ads in it.
    "ads": { "title": "Sponsored", "ads": [] },
    "videos": [
      {
        "title": "Lisbon with kids: where to stay",
        "link": "https://www.youtube.com/watch?v=example",
        "platform": "YouTube",
        "channel": "Example Family Travel",
        "duration": "12:04"
      }
    ]
  }
}

Notes for this engine

Geo and language targeting

For a region or city below the country, use location (for example Texas,United States). A US state is accepted and answered for the whole US; only ChatGPT and Gemini answer from inside a state (states).

Handling the results

• ads is an object with title and ads[], not an array, and null when the answer shows no sponsored products. Each ad has title, url, position and store.
• shoppingCards[].position is 0-indexed; inlineProducts[].position is 1-indexed. Prices are objects: price.value is numeric, and price.raw keeps the displayed string on shopping cards.
• reviews is a string on shopping cards and ads, but an integer on places and map.
• redirectLink sits beside resolved links on sources, pills, snippet links, ads and videos. Resolve one yourself with POST /v1/monitor/google/goto, which is free and runs at most 4 calls per account at once.
• include.googleGoto is deprecated and ignored; redirect links are returned without it.

location expects Google’s canonical City,Region,Country names from the Google Ads geotargets list. Copy names from that list instead of typing them, and keep a vetted list per client.

hl overrides the language derived from the country. When comparing markets, set hl explicitly; see multilingual AI answers.

shoppingCards[].position starts at 0 and inlineProducts[].position at 1. Normalize before storing ranks.

A city grid grows fast: 2 prompts × 3 cities is 6 tasks per day before repeated samples, and answers vary enough between runs that you want several per combination (AI answer volatility).

Related: the best AI Mode scrapers compared, the AI Mode API post, every request field, AI visibility tracking, local rank tracking, rank tracking, competitor analysis, monitoring Google AI Overviews.

From the blog

Docs

• Quickstart
• API reference
• Engine features
• Async tasks and batches
• Webhooks
• Coverage
• Pricing and failures
• Rate limits

Other engines