Skip to main content
Glama
localseodata

Local SEO Data

Official
by localseodata
OverviewSchemaSourceRelated ServersDiscussions(1)Admin
TypeScript
Remote

geogrid_scan

Read-only

Map where a business ranks across a geographic grid by checking public Google Maps rankings at each point, with optional competitor listings.

Instructions

Use when mapping where a business ranks across a geographic area. Read-only: it checks public Google Maps rankings at each point of a grid and changes nothing. Ranks count organic listings only (ads are skipped), top 20. Returns: grid (2D array, 0 = not found), grid_points (flat array with row, col, lat, lng, rank, status -- use for map plotting), center, average_rank (ARP), atrp (not found = 21), solv (% of points in the top 3), found_in, failed_points, total_points. Set include_listings to also get the top 20 businesses at every point (competitor analysis). Expensive: 2 cr per point -- 18 cr (3x3), 50 cr (5x5, the default), 98 cr (7x7), 162 cr (9x9); confirm with user first. Points that could not be checked are refunded. Usually takes 30-60 seconds; this tool waits for the result.

IF THE RESULT IS NOT READY IN TIME: a 9x9 can take longer than the wait. You then get a job_id instead of a grid -- fetch the grid with geogrid_status, which is free. Calling geogrid_scan again with the same inputs returns that same lookup at 0 credits rather than running a second one, and a finished grid is cached for 24 hours -- but geogrid_status is the way to get the grid.

Input Schema

NameRequiredDescriptionDefault
zoomNoMaps zoom each point searches at. Default: auto (14). Fix it only to match an existing series.
centerNoExact grid center. Use the business's own coordinates to track it over time; overrides location.
keywordYesSearch keyword to check rankings for
businessNoBusiness name to track. Required unless place_id is given.
locationNoCenter location for the grid, e.g. "Buffalo, NY". Required unless center is given.
place_idNoGoogle Place ID for precise matching (e.g. ChIJ...). When provided, the business is matched by Place ID instead of name, which is far more reliable.
grid_sizeNoGrid dimensions. Default: 5x5. Larger grids cost more (2 cr per point).
radius_milesNoRadius in miles from center. Default: 3
include_listingsNoAlso return the top 20 organic listings at every point. Default: false. Same price; larger response.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv1.1.0
    • changedInput schema / properties / business / description
      Previous value: -"Business name to track"New value: +"Business name to track. Required unless place_id is given."
    • addedInput schema / properties / center
      Added value: +{
+  "additionalProperties": false,
+  "description": "Exact grid center. Use the business's own coordinates to track it over time; overrides location.",
+  "properties": {
+    "lat": {
+      "type": "number"
+    },
+    "lng": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "lat",
+    "lng"
+  ],
+  "type": "object"
+}
    • changedInput schema / properties / grid_size / description
      Previous value: -"Grid dimensions. Default: 5x5"New value: +"Grid dimensions. Default: 5x5. Larger grids cost more (2 cr per point)."
    • changedInput schema / properties / grid_size / enum
      Previous value: -[
-  "5x5",
-  "7x7",
-  "9x9"
-]New value: +[
+  "3x3",
+  "5x5",
+  "7x7",
+  "9x9"
+]
    • addedInput schema / properties / include_listings
      Added value: +{
+  "description": "Also return the top 20 organic listings at every point. Default: false. Same price; larger response.",
+  "type": "boolean"
+}
    • changedInput schema / properties / location / description
      Previous value: -"Center location for the grid"New value: +"Center location for the grid, e.g. \"Buffalo, NY\". Required unless center is given."
    • addedInput schema / properties / zoom
      Added value: +{
+  "anyOf": [
+    {
+      "const": "auto",
+      "type": "string"
+    },
+    {
+      "maximum": 21,
+      "minimum": 3,
+      "type": "integer"
+    }
+  ],
+  "description": "Maps zoom each point searches at. Default: auto (14). Fix it only to match an existing series."
+}
    • changedInput schema / required
      Previous value: -[
-  "business",
-  "location",
-  "keyword"
-]New value: +[
+  "keyword"
+]
  2. First observedv0.1.0

TDQS

A4.4/5.0
Behavior3/5

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint, destructiveHint), so the lower bar applies. The description adds substantial beyond-schema context — organic-only ranking, credit pricing per grid size, refunds for failed points, 30-60s wait, job_id fallback, and 24h caching — making it unusually transparent for a read tool.

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

Conciseness4/5

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

Front-loaded with the use case, then cost, then the timeout/retry path — every section earns its place. It is dense and long, but the density is functional rather than padding; only the return-field enumeration is more verbose than strictly necessary.

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?

No output schema exists, yet the description fully enumerates the return fields (grid, grid_points, center, average_rank, atrp, solv, etc.), plus cost, timing, and the async fallback — everything an agent needs to call and interpret the tool.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3. The description adds real value by mapping grid sizes to credit costs (18/50/98/162 cr) and explaining include_listings triggers the top-20 competitor listings, beyond what the schema field text states.

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?

Opens with a specific use condition (mapping where a business ranks across a geographic area) and clarifies scope: public Google Maps organic rankings only, top 20, ads skipped. An agent can distinguish it from geogrid_status, which is explicitly named as the follow-up tool.

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

Usage Guidelines5/5

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

States when to use it, when to instead call geogrid_status ('if the result is not ready in time'), and that re-calling with same inputs returns a cached lookup rather than a duplicate run. Also mandates confirming cost with the user first.

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

Deploy Server

Other Tools