Google Search API

Request

curl -X POST "https://api.answerline.dev/v1/monitor/google" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"project management software","country":"US","include":{"aioverview":{"markdown":true}}}'

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

const client = new Client({ apiKey: process.env.API_KEY! });
const answer = await client.monitor.google({
  "query": "project management software",
  "country": "US",
  "include": {
    "aioverview": {
      "markdown": true
    }
  }
});

import os
from answerline import Client

with Client(os.environ["API_KEY"]) as client:
    answer = client.monitor.google(
        query="project management software",
        country="US",
        include={
            "aioverview": {
                "markdown": True
            }
        },
    )

Every request option is on the Google Search reference page.

What you get back

Full field definitions are on the Google Search reference page.

The results page versus Google’s developer API

This endpoint returns Google’s results page for a query and market, as structured fields. Rank tracking and AI Overview monitoring measure that page, because it is what searchers see.

Google’s JSON API for web search results is the Custom Search JSON API. According to its overview (checked 2026-09-17, developers.google.com) it returns web and image results from a Programmable Search Engine, gives 100 free queries per day, costs $5 per 1,000 further queries up to 10,000 per day, is closed to new customers, and existing customers have until January 1, 2027 to move to an alternative. Its cse.list reference (checked 2026-09-17, developers.google.com) documents gl, hl, cr and lr and does not mention AI Overviews, People Also Ask, ads, local packs or knowledge panels.

Rank here is a page position: organicResults[].position and page describe where a listing appeared after ads, the AI Overview and other modules pushed it down. Those modules (aioverview, peopleAlsoAsk, peopleAreSaying, localResults, knowledgeGraph, shoppingCards, recipes, videos, images, ads) take attention before the first organic link, and tracking them explains traffic changes that rank alone cannot. Being cited in aioverview.sources or aioverview.citationPills is a separate outcome from ranking organically and needs its own tracking.

An annotated response

The excerpt follows the result schema for POST /v1/monitor/google. Values are illustrative; the request set include.aioverview.markdown to true.

{
  "success": true,
  "result": {
    "organicResults": [
      {
        "position": 1,
        "title": "Project Management Software for Teams | ExampleBoard",
        "link": "https://www.exampleboard.com/",
        "source": "ExampleBoard",
        "displayedLink": "https://www.exampleboard.com",
        "snippet": "Plan, track and deliver projects...",
        "page": 1,
        "sitelinks": { "inline": [{ "title": "Pricing", "link": "https://www.exampleboard.com/pricing", "snippet": "Plans for teams of every size..." }] }
      }
    ],
    // Set only when Google corrected the query. type: DID_YOU_MEAN | SHOWING_RESULTS_FOR |
    // INCLUDING_RESULTS_FOR | NO_RESULTS_FOUND_FOR.
    "spelling": { "query": "project management software", "type": "SHOWING_RESULTS_FOR" },
    // blockPosition: top | bottom | middle | rhs. type: RESULT | SHOPPING_CARD.
    "ads": [
      {
        "position": 1,
        "blockPosition": "top",
        "type": "RESULT",
        "title": "SampleTask - Free for Small Teams",
        "url": "https://www.sampletask.example/signup",
        "page": 1,
        "displayedUrl": "www.sampletask.example",
        "domain": "sampletask.example",
        "description": "Kanban, Gantt and time tracking in one tool..."
      }
    ],
    // type is AIOVERVIEW, LINK or UNKNOWN. markdown and sources on AIOVERVIEW
    // items require include.paaAioverview.
    "peopleAlsoAsk": [
      { "question": "What is the easiest project management software?", "type": "LINK", "title": "...", "link": "https://www.example-reviews.com/easy-pm", "snippet": "..." }
    ],
    "relatedSearches": [{ "query": "free project management software", "link": "https://www.google.com/search?q=free+project+management+software" }],
    // null when requested but Google showed no AI Overview.
    "aioverview": {
      "text": "Popular options include ExampleBoard and SampleTask...",
      "markdown": "Popular options include **ExampleBoard** and **SampleTask**...",
      "sources": [
        { "position": 1, "url": "https://www.example-reviews.com/best-pm-software", "label": "Best project management software", "description": "..." }
      ],
      // citationPillId is 1-based; position points into aioverview.sources.
      "citationPills": [
        { "label": "Best project management software", "citationPillId": 1, "url": "https://www.example-reviews.com/best-pm-software", "domain": "example-reviews.com", "position": 1 }
      ],
      // Links under a chip's "related links" flyout that are not in sources. No position.
      "relatedLinks": []
    }
    // Modules the page does not show are omitted (see Handling the results).
  }
}

Notes for this engine

Market targeting

A US state is accepted and answered for the whole US; for a place inside the US use location, for example Texas,United States. Only ChatGPT and Gemini answer from inside a state (states).

With url, the query and gl are read from the URL, which may carry only q, gl, num, hl and uule; any other parameter (start, tbs, safe, tbm and the rest) is refused with a 400. For news results use Google News.

Handling the results

• localResults, peopleAreSaying, knowledgeGraph, shoppingCards, recipes, videos, images and spelling are omitted when absent; aioverview is null when requested but not shown. Distinguish “not requested” (key missing) from “not shown” (null).
• localResults[].reviews is Google’s display string (for example 26K), not a number. peopleAreSaying[].date is relative text such as 5 days ago.
• ads[].price on shopping-card ads carries value, currency and raw; raw distinguishes a genuine price from labels such as installment offers.
• shoppingCards[].productLink is usually an empty string because the card opens a Google overlay.
• recipes holds the cards of Google’s Recipes carousel in the order shown: title, link to the recipe’s page, source (the site), ingredients and totalTime as the card lists them, rating out of 5 and reviews, the number of ratings.
• An organic result with review stars carries rating out of ratingMax (5 for stars) and reviews, the number of votes; one showing a price carries price with raw as Google shows it ($30 to $60, Free delivery over $100), and value and currency only when that text is a single price.
• videos holds the cards of Google’s Videos and Short videos blocks in page order (a video in both appears twice): title, url, source (the channel or creator), and on Videos cards platform (for example YouTube) and date. images holds Google’s Images block: title (the alt text), link and thumbnail.
• redirectLink appears beside a link only when Google served it as a redirect; POST /v1/monitor/google/goto resolves one free of charge. include.googleGoto is deprecated and ignored.

Whether an AI Overview appears can change between runs of the same query. Track presence as a rate over several runs, and store null as an observation.

Results differ by market and time of day. Keep the market fixed within a series and change one dimension at a time.

Many modules are omitted rather than returned empty, so default every module read (result.get("localResults", [])).

Ten pages per keyword is $0.00789 per task, $0.0086 with the AI Overview. Most rank tracking needs the first page or two; fetch deeper pages only for keywords where you rank there.

include.aioverview is enabled by the key being present, so {"markdown": false} still turns it on. It costs +$0.00071 only when Google shows one; a completed request with aioverview: null is still a success. Extra pages cost +$0.00071 each and paaAioverview is free, but responses with it take longer. A task costs at most $0.0086; a request reserves its maximum and is charged for the pages fetched.

Related: the best SERP APIs compared, every request field, pricing and failures, rank tracking, local rank tracking, monitoring Google AI Overviews, keyword research, People Also Ask keyword research, competitor analysis, web search API, brand protection, tracking SERP feature changes.

From the blog

Docs

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

Other engines