# Local Map Rank

> Run a local grid and read rankings for each coordinate.

Canonical: https://docs.georanker.com/docs/seo-tools-api-local-map-rank

Local Map Rank measures where a target domain ranks at points around a street address or service area. Choose the centre coordinates, grid spacing and search engine. GeoRanker looks up an address for each grid point and queues one search per keyword at each point.

## Create a grid around a location

Set `PROJECT_ID` to your project UUID and `SEO_TOOLS_API_KEY` to your API key. Local Map Rank calls the project field `campaignId`. This example requests a 3 x 3 grid in New York with one keyword, for a total of nine searches. Replace the target domain with the one you want to track.

```bash
curl -sS --fail-with-body https://seoapi.georanker.com/api/localmaprank \
  -H "Authorization: Bearer $SEO_TOOLS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<JSON
{
  "payload": {
    "campaignId": "$PROJECT_ID",
    "reportName": "Pizza visibility near City Hall",
    "domain": "example.com",
    "gridSize": 3,
    "cellSize": 1,
    "cellUnit": "km",
    "searchEngine": "googlelocal",
    "centerLat": 40.7128,
    "centerLng": -74.0060,
    "device": "mobile",
    "keywords": ["pizza near me"]
  }
}
JSON
```

| Input                    | Accepted values                                                                 |
| ------------------------ | ------------------------------------------------------------------------------- |
| `campaignId`, `domain`   | Required project UUID and target domain.                                        |
| `centerLat`, `centerLng` | Required numeric latitude and longitude.                                        |
| `gridSize`               | Required side length of 3, 6 or 9, giving 9, 36 or 81 points per keyword.       |
| `cellSize`, `cellUnit`   | Distance between adjacent points. Defaults to 1 kilometre. Use `km` or `miles`. |
| `keywords`               | Required array of up to 200 strings.                                            |
| `searchEngine`, `device` | `google` (default) or `googlelocal`, and `desktop` (default) or `mobile`.       |

On HTTP 200, save the returned `id` as `REPORT_ID`. The report fills in as searches return.

## Read a keyword's grid

```bash
curl -sS --fail-with-body "https://seoapi.georanker.com/api/localmaprank/$REPORT_ID" \
  -H "Authorization: Bearer $SEO_TOOLS_API_KEY"
```

The response includes `report.status`. For `pending` or `running`, check the same report again after a pause. A `completed` report is ready to compare. Treat `failed` as a failed run.

`report.results` maps each keyword string to an array of cells. An illustrative excerpt for one cell looks like this.

```json
{
  "row": 1,
  "col": 1,
  "lat": 40.7128,
  "lng": -74.006,
  "address": "New York, NY",
  "position": 2,
  "results": [
    {"rank": 2, "url": "https://example.com/pizza", "title": "Pizza menu", "domain": "example.com", "isTarget": true}
  ]
}
```

`position` is the target domain's rank at this point. A completed cell with a null position means the domain did not rank in the captured results. The address can fall back to coordinates. For a location-level summary, count points ranked in the top three and report that count against the full grid size. For example, six top-three points on a completed 3 x 3 grid cover six of the nine sampled locations.

## Find or remove grids

* `GET /api/projects/{projectId}/localmaprank-reports` returns `items`, `total` and `nextCursor`. Summary rows include `reportName`, `domain`, `gridSize`, `centerAddress`, `keywords`, `status` and timestamps. The default `limit` is 20, maximum 50. Pass the returned `nextCursor` as `cursor` for the next page.
* `DELETE /api/localmaprank/{id}` removes the report and returns `{"ok":true}`. Members can delete reports they created.

[Explore the interactive Local Map Rank example](https://docs.georanker.com/docs/ranktracker-local-222)

[SEO Tools API overview](https://docs.georanker.com/docs/seo-tools-api)
