This page explains how to use our API to run Local Grids and fetch grid results.
All requests to our API should be authenticated. Our API is RESTful and communicates using JSON.
Start a new Local Grid run
Method: POST
Endpoint: https://api.insites.com/api/v1/local-grid
Local Grid runs are asynchronous. Starting a run returns immediately with a grid ID and a pending status. You can then either:
Poll the grid using its ID until it completes
Supply an
on_completionURL to receive the completed result by webhook
Request body should be JSON encoded, and can include the following fields:
Property | Definition | Required |
business_name | String – The name of the business to analyse. | Yes |
keyword | String – The keyword to search for. | Yes |
latitude | Number – Latitude of the centre point of the grid. | Yes |
longitude | Number – Longitude of the centre point of the grid. | Yes |
grid_size | Integer – Number of points across the grid. | Yes |
distance | Integer – Distance between grid points in metres. | Yes |
on_completion | String – An HTTPS URL we will POST the completed grid to when finished. | No |
Example
curl "https://api.insites.com/api/v1/local-grid"\
--header "api-key:[YOUR API KEY]"\
--header "Content-Type: application/json"\
--data
'{
"business_name": "Acme Plumbing",
"keyword": "plumber",
"latitude": 53.8008,
"longitude": -1.5491,
"grid_size": 5,
"distance": 1000
}'
Expected response
If successful, you would expect a 202 response, with a body like this:
{"id": "b7c3a912f4e54e6aa98f67b42d91a1b3",
"status": "pending"}
All possible responses
Code | Reason |
202 | Accepted. The grid run has started. |
402 | The account doesn’t have enough credits to start the run. |
403 | This action is not permitted with the API credentials you are using. |
422 | The request could not be processed. |
Refresh an existing Local Grid
Method: POST
Endpoint: https://api.insites.com/api/v1/local-grid/[ID]/refresh
Example
curl "https://api.insites.com/api/v1/local-grid/b7c3a912f4e54e6aa98f67b42d91a1b3/refresh" \
--header "api-key:[YOUR API KEY]"
All possible responses
Code | Reason |
202 | Accepted. The grid refresh has started. |
404 | Grid not found. |
Fetch a Local Grid run
Method: GET
Endpoint: https://api.insites.com/api/v1/local-grid/[ID]
Example
curl "https://api.insites.com/api/v1/local-grid/b7c3a912f4e54e6aa98f67b42d91a1b3" \
--header "api-key:[YOUR API KEY]"
Expected response
If the grid is still processing, you would expect a 202 response. If the grid has completed, you would expect a 200 response with the full Local Grid data.
All possible responses
Code | Reason |
200 | Grid details returned. |
202 | The grid is still processing. |
404 | Grid not found. |
Fetch a list of Local Grid runs
Method: GET
Endpoint: https://api.insites.com/api/v1/local-grid
Returns a list of Local Grid runs for your account, newest first. The request can include the following filters:
Property | Definition | Required |
keyword | String – Partial match on the keyword. | No |
status | String – Filter by status. | No |
created_after | String – Only return runs created at or after this date-time. | No |
created_before | String – Only return runs created before this date-time. | No |
limit | Integer – Number of runs per page. Defaults to 25. | No |
offset | Integer – Number of runs to skip. Defaults to 0. | No |
Example
curl
"https://api.insites.com/api/v1/local-grid?status=completed&limit=10"\
--header "api-key:[YOUR API KEY]"
All possible responses
Code | Reason |
200 | List of Local Grid runs. |
400 | An invalid filter was supplied. |
Delete a Local Grid
Method: DELETE
Endpoint: https://api.insites.com/api/v1/local-grid/[ID]
Example
curl --request DELETE
"https://api.insites.com/api/v1/local-grid/b7c3a912f4e54e6aa98f67b42d91a1b3"\
--header "api-key:[YOUR API KEY]"
All possible responses
Code | Reason |
204 | Grid deleted successfully. |
404 | Grid not found. |
Webhooks
If an on_completion URL is supplied when starting a grid, we will POST the completed grid to that URL once it reaches a final status.
Example payload
{"id": "evt_b7c3a912f4e54e6aa98f67b42d91a1b3",
"type": "grid.completed",
"timestamp": "2026-06-30T14:17:48Z",
"data": {
"...": "the full Local Grid result"
}}
Webhook event types
Type | Reason |
grid.completed | The Local Grid run has completed. |
grid.failed | The Local Grid run failed. |
Idempotency
To make retries safe, send an Idempotency-Key header when starting a grid.
If we receive a repeated request carrying the same key within 24 hours, we return the original grid instead of starting a new one.
Pagination
The list endpoints support pagination using limit and offset.
Property | Definition |
limit | The number of runs to return per page. Defaults to 25. |
offset | The number of runs to skip. Defaults to 0. |
Errors
Errors are returned as JSON.
Example error
{"type": "about:blank",
"title": "Grid already in progress",
"status": 409,
"detail": "This Local Grid already has a run in progress.",
"code": "grid_in_progress" }
Completed grid data
A completed Local Grid includes the following sections:
Property | Definition |
id | The Local Grid run ID. |
status | The current run status. |
keyword | The keyword used for the search. |
grid_size | The size of the grid. |
distance | The spacing between points. |
results | Ranking results for each grid point. |
competitors | Competitor businesses found in the grid. |
Run statuses
Status | Definition |
pending | The grid has been created and is waiting to start. |
processing | The grid is in progress. |
completed | The grid has completed successfully. |
failed | The grid could not be completed. |
OpenAPI specification
A full machine-readable OpenAPI specification is available for this API.
You can import it into tools like Postman or Insomnia to explore the endpoints and generate client code.