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}}}'

Request options

* required. Nested fields are written with a dot, e.g. include.markdown.

What you get back

Full field definitions are in the API reference.

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, 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/",
        "displayedLink": "https://www.exampleboard.com",
        "snippet": "Plan, track and deliver projects...",
        "page": 1,
        "sitelinks": { "inline": [{ "title": "Pricing", "link": "https://www.exampleboard.com/pricing" }] }
      }
    ],
    // 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": []
    }
    // localResults, peopleAreSaying, knowledgeGraph and shoppingCards are omitted
    // when the page has no such module.
  }
}

Details that matter in code:

• localResults, peopleAreSaying, knowledgeGraph, shoppingCards and recipes 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.
• 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.

Synchronous calls

A synchronous call returns the structured page and waits up to five minutes. One page costs $0.00103, the same as a task.

Python (requests)

import os
import requests

API = "https://api.answerline.dev"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}
MY_DOMAIN = "exampleboard.com"

resp = requests.post(
    f"{API}/v1/monitor/google",
    headers=HEADERS,
    json={
        "query": "project management software",
        "country": "US",
        "include": {"aioverview": {"markdown": True}},
    },
    timeout=330,
)
if resp.status_code != 200:
    raise RuntimeError(f"{resp.status_code} {resp.headers.get('X-Request-Id')} {resp.text}")

result = resp.json()["result"]
rank = next((r["position"] for r in result.get("organicResults", []) if MY_DOMAIN in r.get("link", "")), None)
aio = result.get("aioverview")
cited = aio is not None and any(MY_DOMAIN in s.get("url", "") for s in aio.get("sources", []))
print("organic rank:", rank)
print("AI Overview:", "absent" if aio is None else ("cites us" if cited else "shown, not citing us"))
print("charged (USD):", resp.headers.get("X-Credits-Charged"))

TypeScript (fetch)

const API = "https://api.answerline.dev";

const res = await fetch(`${API}/v1/monitor/google`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ query: "emergency plumber denver", gl: "us", pages: 2 }),
  signal: AbortSignal.timeout(330_000),
});
if (!res.ok) throw new Error(`${res.status} ${res.headers.get("X-Request-Id")} ${await res.text()}`);

const { result } = await res.json();
for (const place of result.localResults ?? []) {
  console.log(place.position, place.title, place.rating, place.reviews, place.phone ?? "");
}
const topAds = (result.ads ?? []).filter((ad: any) => ad.blockPosition === "top");
console.log("top ads:", topAds.map((ad: any) => ad.domain));
console.log("charged (USD):", res.headers.get("X-Credits-Charged"));

Batches: async tasks and a webhook

Rank tracking runs as batches. Tasks queue and post to your webhook. POST /v1/async/task/batch takes 1 to 500 tasks; each is admitted independently and answered by index.

Python: a daily keyword batch

import datetime
import os
import requests

API = "https://api.answerline.dev"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}
day = datetime.date.today().isoformat()

keywords = ["project management software", "kanban tool", "gantt chart software"]
countries = ["US", "GB"]

tasks = [
    {
        "taskType": "GOOGLE",
        "payload": {"query": kw, "country": cc, "pages": 2, "include": {"aioverview": {}}},
        "idempotencyKey": f"serp-{i}-{cc.lower()}-{day}",
        "webhook": {"url": "https://your-app.example/hooks/serps"},
    }
    for i, kw in enumerate(keywords)
    for cc in countries
]

# Chunk to the 500-task batch limit.
for start in range(0, len(tasks), 500):
    chunk = tasks[start:start + 500]
    resp = requests.post(f"{API}/v1/async/task/batch", headers=HEADERS, json=chunk, timeout=60)
    resp.raise_for_status()
    print(resp.json()["summary"])

Each task above reserves $0.00103 + $0.00071 (second page) + $0.00071 (AI Overview) = $0.00245 and is charged for the pages fetched and the overview if Google showed one.

Python: receive and verify deliveries (Flask)

Deliveries carry the GET /v1/async/task/{taskId} body. Verify Webhook-Signature over the raw bytes before parsing.

import hashlib
import hmac
import json
import os
import time
from flask import Flask, abort, request

app = Flask(__name__)
MY_DOMAIN = "exampleboard.com"

def verify(raw: bytes, header: str | None, secret: str, tolerance: int = 300) -> bool:
    pairs = [part.split("=", 1) for part in (header or "").split(",") if "=" in part]
    stamps = [v for k, v in pairs if k == "t"]
    sigs = [v for k, v in pairs if k == "v1"]
    if len(stamps) != 1 or not stamps[0].isdigit() or not sigs:
        return False
    if abs(time.time() - int(stamps[0])) > tolerance:
        return False
    expected = hmac.new(secret.encode(), stamps[0].encode() + b"." + raw, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, s) for s in sigs)

@app.post("/hooks/serps")
def serps():
    raw = request.get_data()
    if not verify(raw, request.headers.get("Webhook-Signature"), os.environ["WEBHOOK_SECRET"]):
        abort(400)
    delivery = json.loads(raw)
    if delivery.get("test"):
        return "", 204
    task = delivery["task"]
    if task["status"] != "COMPLETED":
        print(task["idempotencyKey"], "failed:", delivery["response"]["error"]["code"])
        return "", 204
    result = delivery["response"]["result"]
    ranks = [(r.get("page"), r.get("position")) for r in result.get("organicResults", []) if MY_DOMAIN in r.get("link", "")]
    aio = result.get("aioverview")
    print(task["idempotencyKey"], ranks, "aio:", None if aio is None else len(aio.get("sources", [])),
          "charged:", delivery["credits"]["creditsCharged"])
    return "", 204

Deliveries can repeat; deduplicate on task.id. See webhooks and batching a rank tracking pipeline.

Market targeting

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. Date and SafeSearch filtering through the URL are coming; use Google News for news results.

Include flags and what they cost

Google Search costs $1.03 per 1,000 one-page tasks on every tier, deducted from your balance.

The AI Overview costs +$0.00071 only when Google shows one; paaAioverview is free. include.aioverview is enabled by the key being present, so {"markdown": false} still turns it on. The maximum is $0.00103 + 9 × $0.00071 + $0.00071 = $0.00813 for a task; a request reserves its maximum and is charged for the pages fetched. Responses with paaAioverview take longer.

Common workloads

• Rank tracking by keyword and market. See rank tracking and local rank tracking.
• AI Overview monitoring: presence, cited domains and chip grouping. See monitoring Google AI Overviews and AI Overviews with async batches and webhooks.
• Keyword research from peopleAlsoAsk and relatedSearches. See keyword research and People Also Ask keyword research.
• Competitor and ad intelligence: advertisers per keyword and block position. See competitor analysis.
• Search grounding for agents: structured results as a tool call. See web search API.
• Brand SERP monitoring: knowledge panel fields and peopleAreSaying threads. See brand protection and tracking SERP feature changes.

Pitfalls

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.00742 per task, $0.00813 with the AI Overview. Most rank tracking needs the first page or two; fetch deeper pages only for keywords where you rank there.

Large keyword sets belong in tasks, which queue. Watch for 429 QUEUE_LIMIT_EXCEEDED on very large submissions. See rate limits.

How failures are billed

A request reserves its maximum possible cost and is charged the actual cost on success: base, AI Overview add-on if requested, and the pages fetched. A failed request is charged nothing and releases its reservation. A completed request with aioverview: null is a success and is charged, including the add-on. Tasks that never start within 4 hours fail uncharged (QUEUE_WAIT_EXCEEDED). See credits.

Other engines