Local SEO Data

Official

Overview Schema Source Related Servers Discussions(1)Admin

ai_mode

Read-only

Fetches Google AI Mode (SGE) answers for a keyword and location, returning generated response text, local business recommendations, reference links, and shopping items.

Instructions

Use when getting the Google AI Mode (SGE) generated answer for a keyword. Returns ai_response text, local_businesses, reference links, and shopping items. Costs 2 credits. May take 10-30 seconds; Google generates the answer per request.

LOCAL BUSINESSES: on a local question Google recommends businesses inside the answer and we return them as local_businesses — rank, name, category, rating, reviews_count, address, website, domain, cid. Field names shared with /v1/serp/local-pack mean the same things; the sets differ in that this adds category and domain and has no hours. cid is an empty string when the Directions link was unreadable. Two differences from ai_scraper on chat_gpt: phone is always empty (Google renders a Call button and never sends the number), and cid is populated — Google's own identifier for the business, in decimal, which /v1/business/profile also takes. Match on cid rather than on name where you can.

REVIEW COUNTS ARE ROUNDED: Google abbreviates above a thousand, so reviews_count is 1200 where the exact figure is 1194. Do not compare it to a count from another endpoint and read the difference as change.

parse_status reports whether the businesses could be read: "ok", "no_businesses" when the answer named none, or "unparsed" when business cards were present and none could be read — which means Google changed the format. references is unreliable for citations: on some answers it carries real domains, on others every entry collapses to a google.com redirect, and it never names the businesses either way.

Input Schema

Name	Required	Description
`fresh`	No	Bypass the hour of caching and run the query again. Use when sampling the same prompt repeatedly to measure how the answer varies — a cached hit would return the earlier run and hide the variance. Always billed at the normal price, since there is no cache hit to be free.
`keyword`	Yes	Search keyword (e.g. "best plumber near me")
`location`	Yes	City and state (e.g. "Orchard Park, NY")

Output Schema

Name	Required	Description	Default
`keyword`	Yes
`location`	Yes
`references`	Yes
`ai_response`	Yes
`parse_status`	No
`location_used`	No
`shopping_items`	Yes
`local_businesses`	No
`location_alternatives`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.1.0Oct 22, 2026

addedInput schema / properties / fresh

Added value: +{
+  "description": "Bypass the hour of caching and run the query again. Use when sampling the same prompt repeatedly to measure how the answer varies — a cached hit would return the earlier run and hide the variance. Always billed at the normal price, since there is no cache hit to be free.",
+  "type": "boolean"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {
+    "ai_response": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "keyword": {
+      "type": "string"
+    },
+    "local_businesses": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {
+          "address": {
+            "type": "string"
+          },
+          "category": {
+            "type": "string"
+          },
+          "cid": {
+            "type": "string"
+          },
+          "domain": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "phone": {
+            "type": "string"
+          },
+          "rank": {
+            "type": "number"
+          },
+          "rating": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "reviews_count": {
+            "type": "number"
+          },
+          "website": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "rank",
+          "name",
+          "category",
+          "rating",
+          "reviews_count",
+          "address",
+          "phone",
+          "website",
+          "domain"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "location": {
+      "type": "string"
+    },
+    "location_alternatives": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {
+          "code": {
+            "type": "number"
+          },
+          "name": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "name",
+          "code",
+          "type"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "location_used": {
+      "type": "string"
+    },
+    "parse_status": {
+      "enum": [
+        "ok",
+        "no_businesses",
+        "unparsed"
+      ],
+      "type": "string"
+    },
+    "references": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {
+          "domain": {
+            "type": "string"
+          },
+          "position": {
+            "type": "number"
+          },
+          "title": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "title",
+          "url",
+          "domain"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "shopping_items": {
+      "items": {},
+      "type": "array"
+    }
+  },
+  "required": [
+    "ai_response",
+    "references",
+    "shopping_items",
+    "keyword",
+    "location"
+  ],
+  "type": "object"
+}

First observedv0.1.0May 11, 2026

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the readOnly/openWorld/destructive annotations: discloses the 2-credit cost, the 10-30 second latency and why (Google generates per request), that results are cached for an hour, the meaning of each parse_status value, that reviews_count is rounded, and that references is unreliable. These are exactly the non-obvious traits an agent needs to interpret results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, cost, and latency, which is good. However, most of the remaining length enumerates return-field semantics and caveats, and since an output schema exists some of this is redundant; the dense field-by-field commentary is not as tight as it could be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with an output schema, two required params, and cost/latency involved, the description covers everything an agent needs to call it correctly and to avoid misreading results (rounding, empty cid, unreliable references, parse_status failures).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the fresh parameter is already fully explained including the billing caveat in the schema. The description adds invocation-level cost/latency context but no per-parameter syntax or semantics beyond what the schema provides, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('getting the Google AI Mode (SGE) generated answer for a keyword') and then names what comes back. It also distinguishes itself from siblings by explicitly contrasting field sets with /v1/serp/local-pack and calling out two differences from ai_scraper on chat_gpt (phone always empty, cid populated).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use when getting the Google AI Mode (SGE) generated answer for a keyword' is an explicit trigger condition, and the fresh parameter guidance tells the caller when bypassing cache matters. There is no explicit 'when not to use' or routing to ai_overview/ai_scraper, so it stops short of 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.