# Local Rank Tracker Grid API Documentation

<p><strong>Local Rank Tracker Grid API Documentation</strong> 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.</p>

- **Documentation:** [https://scrappa.co/docs/local-rank-tracker-api/local_rank_tracker_grid](https://scrappa.co/docs/local-rank-tracker-api/local_rank_tracker_grid)
- **API group:** Local Rank Tracker API
- **Endpoint:** `GET https://scrappa.co/api/local-rank-tracker/grid`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | Yes | Search keyword, 2 to 200 characters. Example: pizza. Do not add a city: the grid sets the place. |
| `place_id` | string | No | Google place id of the target, starts with ChIJ. Best way to name the target. Example: ChIJgW-n6g1ZwokRwPVvsDWxpMo. |
| `data_id` | string | No | Google data id of the target, like 0x89c2590deaa76f81:0xcaa4b135b06ff5c0. Used when no place_id is sent. |
| `cid` | string | No | Google customer id of the target, a decimal number. Used when neither place_id nor data_id finds it. |
| `business_name` | string | No | 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. |
| `lat` | number | Yes | Latitude of the grid centre, -85 to 85. Example: 40.7484. |
| `lon` | number | Yes | Longitude of the grid centre, -180 to 180. Example: -73.9857. |
| `grid_size` | integer | No | Points per side, 3 to 9. A 5 searches 25 points. Odd sizes keep the centre point. Default: 3. |
| `spacing` | number | No | Distance between two neighbour points. 0.25 to 3 for km, 0.15 to 1.8 for mi. Default: 1. |
| `unit` | string | No | Unit of the spacing: km or mi. Default: km. |
| `hl` | string | No | Two-letter interface language, for example en or de. Default: en. |
| `gl` | string | No | Country of the search: us, de, gb or fr. Default: us. |

## Example response

```json
{
    "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

| Status | Error | Description |
| --- | --- | --- |
| 422 | 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. |
| 503 | Service Unavailable | No grid point could be searched. This response is not billable. Retry in a few minutes. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)