Local Rank Tracker Grid API Documentation Find out where a business ranks on Google Maps for a keyword at every point of a geographic grid. Send the keyword q, a target (place_id, data_id, cid or business_name), the centre lat and lon, grid_size (3 to 9, default 3), spacing (default 1) and unit (km or mi). Each grid point runs one Google Maps search with up to 20 results. Each point has its status (found, not_found or failed), the rank of the target (1 to 20, or null), its coordinates, the target as seen at that point, the top 10 competitors and the result count. A competitor has rank, name, place_id, data_id, cid, category, categories, rating, review_count, address, website, phone, latitude and longitude. The summary has average_rank (ARP, only points where the target is found), average_total_rank (ATRP, not found counts as 21), share_of_local_voice (SoLV, percent of searched points with the target in the top 3), found_percentage, a rank distribution and a leaderboard of the 10 strongest competitors. The target is matched by place_id first, then data_id, then cid, then business_name. A name match is flagged in target.match and is the weakest. Send an identifier when you have one. Odd grid sizes keep the centre point. Spacing is 0.25 to 3 km or 0.15 to 1.8 mi. The map view altitude follows the spacing: 1.5 times the spacing in metres, at least 500 m and at most 3000 m (1 km gives 1500 m, 2 km gives 3000 m). The value is returned in meta.view_altitude_m. Countries (gl): us, de, gb, fr. Another country answers 422. Language (hl) is a two-letter code. Ranks 1 to 3 are stable. Ranks 4 and below can differ by one place between two runs. A point that cannot be read is failed, never not_found. Failed points are in no metric and are not charged. Cost: 1 credit per searched point, found or not found. A 9x9 grid costs up to 81 credits, a 3x3 grid up to 9. A request with no searched point answers 503 and costs nothing. The whole grid has a 45 second budget. Points not finished in time are failed and free.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
3 required parameters needed before sending a request.
9 optional filters available.
string
Required
Search keyword, 2 to 200 characters. Example: pizza. Do not add a city: the grid sets the place.
coffee shops
number
Required
Latitude of the grid centre, -85 to 85. Example: 40.7484.
10
number
Required
Longitude of the grid centre, -180 to 180. Example: -73.9857.
10
string
Optional
Google place id of the target, starts with ChIJ. Best way to name the target. Example: ChIJgW-n6g1ZwokRwPVvsDWxpMo.
1234567890
string
Optional
Google data id of the target, like 0x89c2590deaa76f81:0xcaa4b135b06ff5c0. Used when no place_id is sent.
1234567890
string
Optional
Google customer id of the target, a decimal number. Used when neither place_id nor data_id finds it.
example
string
Optional
Name of the target. Matched in the result lists and flagged match=name. Send at least one of place_id, data_id, cid or business_name.
example
integer
Optional
Points per side, 3 to 9. A 5 searches 25 points. Odd sizes keep the centre point. Default: 3.
10
number
Optional
Distance between two neighbour points. 0.25 to 3 for km, 0.15 to 1.8 for mi. Default: 1.
10
string
Optional
Unit of the spacing: km or mi. Default: km.
example
string
Optional
Two-letter interface language, for example en or de. Default: en.
en
string
Optional
Country of the search: us, de, gb or fr. Default: us.
us
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
meta
points
target
summary
search_parameters
Common points fields
col
lat
lon
row
{
"meta": {
"spacing_m": 1000,
"credits_charged": 8,
"view_altitude_m": 1500,
"response_time_ms": 2140,
"credits_per_point": 1,
"results_per_point": 20
},
"points": [
{
"col": 0,
"lat": 40.757182,
"lon": -73.997455,
"row": 0,
"rank": 3,
"index": 0,
"status": "found",
"target": {
"cid": "14585713945970579479",
"name": "Quality Pizza Co. Midtown",
"rank": 3,
"phone": "(646) 858-0048",
"rating": 4.8,
"address": "888 6th Ave, New York, NY 10001",
"data_id": "0x89c2590deaa76f81:0xcaa4b135b06ff5c0",
"website": "http://orderqualitypizzaco.com/",
"category": "Pizza restaurant",
"latitude": 40.748154,
"place_id": "ChIJgW-n6g1ZwokRwPVvsDWxpMo",
"longitude": -73.98869,
"categories": [
"Pizza restaurant"
],
"review_count": 2020
},
"competitors": [
{
"cid": null,
"name": "Little Italy Pizza",
"rank": 1,
"phone": null,
"rating": 4.2,
"address": "New York, NY",
"data_id": "0x89c259000000bbbb:0x2222222222222222",
"website": null,
"category": "Pizza restaurant",
"latitude": 40.7571,
"place_id": "ChIJexample1littleitaly",
"longitude": -73.9975,
"categories": [
"Pizza restaurant"
],
"review_count": 4384
},
{
"cid": null,
"name": "Madison Pizza NYC",
"rank": 2,
"phone": null,
"rating": 4.8,
"address": "New York, NY",
"data_id": "0x89c259000000aaaa:0x1111111111111111",
"website": null,
"category": "Pizza restaurant",
"latitude": 40.7491,
"place_id": "ChIJexample2madisonpizza",
"longitude": -73.9836,
"categories": [
"Pizza restaurant"
],
"review_count": 247
}
],
"result_count": 20
},
{
"col": 1,
"lat": 40.757182,
"lon": -73.9857,
"row": 0,
"rank": null,
"index": 1,
"status": "not_found",
"target": null,
"competitors": [
{
"cid": null,
"name": "Madison Pizza NYC",
"rank": 1,
"phone": null,
"rating": 4.8,
"address": "New York, NY",
"data_id": "0x89c259000000aaaa:0x1111111111111111",
"website": null,
"category": "Pizza restaurant",
"latitude": 40.7491,
"place_id": "ChIJexample2madisonpizza",
"longitude": -73.9836,
"categories": [
"Pizza restaurant"
],
"review_count": 247
}
],
"result_count": 20
},
{
"col": 2,
"lat": 40.757182,
"lon": -73.973945,
"row": 0,
"rank": null,
"index": 2,
"status": "failed",
"target": null,
"failure": "upstream_unavailable",
"competitors": [],
"result_count": 0
}
],
"target": {
"input": {
"place_id": "ChIJgW-n6g1ZwokRwPVvsDWxpMo"
},
"match": "place_id",
"matched": true,
"business": {
"cid": "14585713945970579479",
"name": "Quality Pizza Co. Midtown",
"phone": "(646) 858-0048",
"rating": 4.8,
"address": "888 6th Ave, New York, NY 10001",
"data_id": "0x89c2590deaa76f81:0xcaa4b135b06ff5c0",
"website": "http://orderqualitypizzaco.com/",
"category": "Pizza restaurant",
"latitude": 40.748154,
"place_id": "ChIJgW-n6g1ZwokRwPVvsDWxpMo",
"longitude": -73.98869,
"categories": [
"Pizza restaurant"
],
"review_count": 2020
}
},
"summary": {
"best_rank": 1,
"worst_rank": 8,
"competitors": [
{
"name": "Madison Pizza NYC",
"rating": 4.8,
"data_id": "0x89c259000000aaaa:0x1111111111111111",
"category": "Pizza restaurant",
"place_id": "ChIJexample2madisonpizza",
"appearances": 8,
"average_rank": 2.4,
"review_count": 247,
"share_of_local_voice": 62.5
}
],
"average_rank": 3.2,
"points_found": 5,
"points_total": 9,
"points_failed": 1,
"points_searched": 8,
"found_percentage": 62.5,
"points_not_found": 3,
"rank_distribution": {
"top_3": 3,
"top_10": 5,
"top_20": 5,
"not_found": 3
},
"average_total_rank": 10.75,
"share_of_local_voice": 37.5
},
"search_parameters": {
"q": "pizza",
"gl": "us",
"hl": "en",
"lat": 40.7484,
"lon": -73.9857,
"unit": "km",
"spacing": 1,
"place_id": "ChIJgW-n6g1ZwokRwPVvsDWxpMo",
"grid_size": 3
}
}Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
A parameter is missing or invalid: no target, grid size outside 3 to 9, spacing outside the range, an unsupported country or a centre out of range. This response is not billable.
{
"errors": {
"spacing": [
"The spacing must be between 0.25 and 3 km."
]
},
"message": "The spacing must be between 0.25 and 3 km."
}Service Unavailable
No grid point could be searched. This response is not billable. Retry in a few minutes.
{
"error": "Local Rank Tracker is temporarily unavailable. No credits were charged.",
"retryable": true,
"error_code": "local_rank_tracker_unavailable"
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.