Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/geogridapi-io:geogridapi-io-grids-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: GeoGrid Grids API
version: 1.0.0
description: 'Geo-grid rank tracking API for Google Maps (local SEO). Send a Google Business Profile and a keyword: GeoGridAPI measures the listing''s rank in the Google Maps results at every point of a grid around it (square 3×3 to 9×9, or circle, diamond, hexagon, cross, ellipse, rectangle), and returns the rank matrix, the competitors ranking ahead, the change since the previous grid and a PNG heatmap. 1 credit = 1 grid point. Test keys (gga_test_) return free mock grids.'
termsOfService: https://geogridapi.io/en/legal/terms
contact:
name: GeoGridAPI
url: https://geogridapi.io
email: sav@localnord.fr
servers:
- url: https://api.geogridapi.io
security:
- bearerAuth: []
tags:
- name: Grids
description: Run and read geo-grids.
paths:
/v1/grids:
post:
operationId: createGrid
tags:
- Grids
summary: Run a geo-grid
description: Measures the Google Maps rank of a listing for a keyword at every point of a grid around it. Answers right away (202, status pending); the grid completes in 20 seconds to 2 minutes. Read it with GET /v1/grids/{id} or receive it on webhook_url. 1 credit per grid point.
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
maxLength: 200
description: Optional. The same key returns the grid already created, with no new charge.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateGridRequest'
responses:
'202':
description: Grid created, status pending.
content:
application/json:
schema:
$ref: '#/components/schemas/Grid'
'200':
description: Idempotent replay of a grid already created.
content:
application/json:
schema:
$ref: '#/components/schemas/Grid'
'400':
description: Invalid body.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: Not enough credits.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No listing matches.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Idempotency-Key reused with other parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Engine temporarily unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
get:
operationId: listGrids
tags:
- Grids
summary: List grids
description: Your grids, newest first, without point details.
parameters:
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: before
in: query
schema:
type: string
format: date-time
description: next_before of the previous page.
- name: place_id
in: query
schema:
type: string
- name: keyword
in: query
schema:
type: string
description: Exact keyword, case-insensitive.
responses:
'200':
description: Grids.
content:
application/json:
schema:
$ref: '#/components/schemas/GridList'
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/grids/estimate:
post:
operationId: estimateGrid
tags:
- Grids
summary: Exact price of a grid
description: Same body as POST /v1/grids. Returns the number of points and credits, without reserving or charging anything. Free.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateGridRequest'
responses:
'200':
description: Estimate.
content:
application/json:
schema:
$ref: '#/components/schemas/Estimate'
'400':
description: Invalid body.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No listing matches.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/grids/{id}:
get:
operationId: getGrid
tags:
- Grids
summary: Get a grid
description: 'Status and result of a grid: ranks at every point, summary, competitors ahead and change since the previous grid.'
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: Grid id.
responses:
'200':
description: The grid.
content:
application/json:
schema:
$ref: '#/components/schemas/Grid'
example:
id: 3f2c9b1e-6a7d-4c1e-9f0a-2b8d7e6c5a41
object: grid
status: completed
mode: live
place:
place_id: ChIJ…
name: Joe's Pizza
address: 7 Carmine St, New York
lat: 40.7305
lng: -74.0021
keyword: pizza
shape: square
size: 7
rows: 7
cols: 7
radius_km: 3
points_total: 49
summary:
average_rank: 4.3
average_rank_with_misses: 4.6
top3_points: 28
found_points: 48
ranks:
- - 4
- 3
- 2
- 2
- 3
- 5
- 8
- - 3
- 2
- 1
- 1
- 2
- 4
- 7
- - 2
- 1
- 1
- 1
- 1
- 3
- 6
- - 2
- 1
- 1
- 1
- 1
- 2
- 5
- - 3
- 2
- 1
- 1
- 2
- 3
- 7
- - 6
- 4
- 3
- 2
- 3
- 6
- 12
- - 11
- 8
- 6
- 5
- 9
- 15
- null
created_at: '2026-10-16T10:00:00Z'
completed_at: '2026-10-16T10:00:41Z'
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Unknown grid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/grids/{id}/image:
get:
operationId: getGridImage
tags:
- Grids
summary: Heatmap image of a grid
description: 'PNG image (1200 × 1092) of a completed grid: map, rank dots, keyword, listing, date and key figures. Free.'
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: Grid id.
- name: lang
in: query
schema:
type: string
enum:
- en
- fr
responses:
'200':
description: PNG image.
content:
image/png:
schema:
type: string
format: binary
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Unknown grid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Grid still running (grid_not_ready) or failed (grid_failed).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/history:
get:
operationId: getHistory
tags:
- Grids
summary: Ranking trend of a listing
description: Every completed grid of the same map, oldest first, and the change between the first and the last. Name the map with grid_id, or with place_id and keyword. Free.
parameters:
- name: grid_id
in: query
schema:
type: string
format: uuid
- name: place_id
in: query
schema:
type: string
- name: keyword
in: query
schema:
type: string
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 50
responses:
'200':
description: Trend.
content:
application/json:
schema:
$ref: '#/components/schemas/History'
'400':
description: Invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No grid for this map.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
GridSummary:
type:
- object
- 'null'
properties:
average_rank:
type:
- number
- 'null'
description: Mean rank over the points where the listing appears.
average_rank_with_misses:
type:
- number
- 'null'
description: Mean rank with misses counted as 21.
top3_points:
type: integer
found_points:
type: integer
PreviousGrid:
type:
- object
- 'null'
description: Change since the previous grid of the same map (same listing, keyword, format, radius and center).
properties:
grid_id:
type: string
format: uuid
created_at:
type: string
format: date-time
average_rank:
type:
- number
- 'null'
top3_points:
type: integer
found_points:
type: integer
changes:
type: object
properties:
average_rank:
type:
- number
- 'null'
description: Negative = better.
top3_points:
type: integer
found_points:
type: integer
ranks:
type: array
items:
type: array
items:
type:
- integer
- 'null'
rank_changes:
type: array
items:
type: array
items:
type:
- integer
- 'null'
description: Places gained per cell (positive = better, a miss counts as 21).
points:
type: object
properties:
improved:
type: integer
worsened:
type: integer
unchanged:
type: integer
GridTarget:
type: object
required:
- keyword
properties:
place_id:
type: string
minLength: 3
maxLength: 256
description: Google place id of the listing (ChIJ…). Send place_id or query, never both.
query:
type: string
minLength: 2
maxLength: 200
description: Listing name and city; the first match is measured. Send place_id or query, never both.
center:
$ref: '#/components/schemas/Center'
keyword:
type: string
minLength: 1
maxLength: 120
description: Keyword searched on Google Maps.
example: plumber
Grid:
type: object
properties:
id:
type: string
format: uuid
object:
type: string
enum:
- grid
status:
type: string
enum:
- pending
- running
- completed
- failed
mode:
type: string
enum:
- live
- test
source:
type: string
enum:
- api
- mcp
- console
api_key_id:
type:
- string
- 'null'
place:
$ref: '#/components/schemas/Place'
keyword:
type: string
shape:
type: string
density:
type:
- string
- 'null'
size:
type: integer
rows:
type: integer
cols:
type: integer
radius_km:
type: number
language:
type: string
country:
type:
- string
- 'null'
points_total:
type: integer
description: Grid points measured (points at sea are neither measured nor charged).
points_charged:
type: integer
description: Credits charged to the GeoGridAPI balance (0 with a test key or through RapidAPI).
summary:
$ref: '#/components/schemas/GridSummary'
ranks:
type:
- array
- 'null'
description: rows × cols matrix, row 0 = north, column 0 = west. null = not in the top 20 (or outside the shape).
items:
type: array
items:
type:
- integer
- 'null'
points:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/GridPoint'
competitors:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/Competitor'
description: 'Who ranks ahead: the top 3 listings summed over the map.'
previous:
$ref: '#/components/schemas/PreviousGrid'
error:
$ref: '#/components/schemas/GridError'
webhook:
type:
- object
- 'null'
description: Delivery of the webhook_url, when one was given.
properties:
status:
type:
- string
- 'null'
attempts:
type: integer
created_at:
type: string
format: date-time
completed_at:
type:
- string
- 'null'
format: date-time
Place:
type: object
properties:
place_id:
type: string
example: ChIJN1t_tDeuEmsRUsoyG83frY4
name:
type:
- string
- 'null'
address:
type:
- string
- 'null'
lat:
type: number
example: 50.6292
lng:
type: number
example: 3.0573
CreateGridRequest:
allOf:
- $ref: '#/components/schemas/GridTarget'
- $ref: '#/components/schemas/GridFormat'
example:
query: Joe's Pizza, New York
keyword: pizza
size: 7
radius_km: 3
GridError:
type:
- object
- 'null'
description: Why a grid (or a batch item) failed; null otherwise.
required:
- code
- message
properties:
code:
type: string
example: place_not_found
message:
type: string
example: No Google Business Profile matches this place, or it has no public address.
PlaceRef:
type: object
properties:
place_id:
type: string
name:
type:
- string
- 'null'
address:
type:
- string
- 'null'
Competitor:
type: object
properties:
place_id:
type: string
name:
type: string
top3_points:
type: integer
description: Points where it is in the top 3.
first_points:
type: integer
description: Points where it ranks first.
ahead_points:
type: integer
description: Points where it ranks ahead of your listing.
HistoryEntry:
type: object
properties:
grid_id:
type: string
format: uuid
created_at:
type: string
format: date-time
average_rank:
type:
- number
- 'null'
top3_points:
type: integer
found_points:
type: integer
points_total:
type: integer
Estimate:
type: object
properties:
object:
type: string
enum:
- estimate
shape:
type: string
size:
type: integer
density:
type:
- string
- 'null'
rows:
type: integer
cols:
type: integer
radius_km:
type: number
points:
type: integer
description: Points that will be measured (points at sea removed).
points_at_sea:
type: integer
exact:
type: boolean
description: 'false: the listing could not be located, points is an upper bound.'
credits:
type: integer
description: Credits (or RapidAPI Points) the grid will cost.
balance:
type: integer
description: Credits balance (not returned through RapidAPI).
balance_after:
type: integer
description: Not returned through RapidAPI.
enough:
type: boolean
description: Not returned through RapidAPI.
place:
type:
- object
- 'null'
allOf:
- $ref: '#/components/schemas/Place'
description: Located listing (other shapes only), else null.
GridPoint:
type: object
properties:
row:
type: integer
description: 0 = north.
col:
type: integer
description: 0 = west.
lat:
type: number
lng:
type: number
rank:
type:
- integer
- 'null'
description: Position in the Google Maps results at this point; null = not in the top 20.
top:
type: array
items:
$ref: '#/components/schemas/TopListing'
description: Top 3 listings at this point.
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
example: invalid_body
message:
type: string
example: 'keyword: Too small: expected string to have >=1 characters'
additionalProperties: true
GridFormat:
type: object
properties:
shape:
type: string
enum:
- square
- circle
- diamond
- hexagon
- cross
- ellipse
- rectangle
default: square
description: Grid shape.
size:
type: integer
enum:
- 3
- 5
- 7
- 9
description: 'Square only (default 7): side of the grid. Cost: size × size points. Not allowed with another shape.'
density:
type: string
enum:
- low
- medium
- high
description: 'Other shapes only (default medium). Points: circle 13/29/49, diamond 13/25/41, hexagon 17/27/47, cross 21/33/45, ellipse 19/35/45, rectangle 15/35/45.'
radius_km:
type: number
minimum: 0.5
maximum: 30
description: 'Distance from center to edge. Square: 0.5 to 30 km (defaults 1.5 / 2.5 / 3.5 / 4.5 km by size). Other shapes: 1 to 30 km.'
language:
type: string
pattern: ^[a-zA-Z]{2}$
description: Search language (2-letter code). Defaults to the account language.
example: en
country:
type: string
pattern: ^[a-zA-Z]{2}$
description: Search country (2-letter ISO code), optional.
example: US
webhook_url:
type: string
maxLength: 500
description: Public HTTPS URL called with the grid when it ends (grid.completed or grid.failed).
TopListing:
type: object
properties:
rank:
type: integer
place_id:
type: string
name:
type: string
GridList:
type: object
properties:
object:
type: string
enum:
- list
data:
type: array
items:
$ref: '#/components/schemas/Grid'
has_more:
type: boolean
next_before:
type:
- string
- 'null'
description: Pass as before to read the next page.
History:
type: object
properties:
object:
type: string
enum:
- history
reference_grid_id:
type: string
format: uuid
mode:
type: string
place:
$ref: '#/components/schemas/PlaceRef'
keyword:
type: string
shape:
type: string
density:
type:
- string
- 'null'
size:
type: integer
rows:
type: integer
cols:
type: integer
radius_km:
type: number
data:
type: array
items:
$ref: '#/components/schemas/HistoryEntry'
description: Completed grids of the same map, oldest first.
has_more:
type: boolean
change:
type:
- object
- 'null'
properties:
since:
type: string
format: date-time
average_rank:
type:
- number
- 'null'
description: Negative = better.
top3_points:
type: integer
found_points:
type: integer
Center:
type: object
required:
- lat
- lng
properties:
lat:
type: number
minimum: -90
maximum: 90
lng:
type: number
minimum: -180
maximum: 180
additionalProperties: false
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: gga_live_… or gga_test_… key from the console.
externalDocs:
description: Documentation
url: https://geogridapi.io/en/docs