GETapi.synup.com/api/v4/locations/{locationId}/grid-reports
Fetch All Grid Reports for Location
This API generates a new rank grid report to analyze business rankings for specified keywords across a grid specified by the user using grid distance and the number of grid coordinates to be analyzed. Behavior:
- Returns a list of reports generated for the given location.
- Includes report IDs, keywords analyzed, and timestamps.
- Can be used to track ranking trends over time.
Requires an API key. Send it as
Authorization: API <your-key> — see Getting started.Parameters
Path
| Name | Type | Required | Description |
|---|---|---|---|
locationId | string | required | Location ID should be provided in Base64 encoded format. Must be in the format Location:<Location ID> |
Request
Request
curl -X GET 'https://api.synup.com/api/v4/locations/:locationId/grid-reports' \
-H 'Authorization: API YOUR_API_KEY' \
-H 'Content-Type: application/json'const res = await fetch('https://api.synup.com/api/v4/locations/:locationId/grid-reports', {
method: 'GET',
headers: {
Authorization: 'API YOUR_API_KEY',
'Content-Type': 'application/json',
},
});
const data = await res.json();import requests
res = requests.get(
"https://api.synup.com/api/v4/locations/:locationId/grid-reports",
headers={
"Authorization": "API YOUR_API_KEY",
"Content-Type": "application/json",
},
)
data = res.json()req, _ := http.NewRequest("GET", "https://api.synup.com/api/v4/locations/:locationId/grid-reports", nil)
req.Header.Set("Authorization", "API YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)Responses
| Status | Description |
|---|---|
200 | Grid rank reports retrieved successfully |
400 | Bad Request - Invalid location ID format |
401 | Unauthorized - Valid API key required |
403 | Forbidden - Insufficient permissions |
404 | Location not found |
Example response
{
"data": {
"gridrankReportsByLocationId": [
{
"id": "df996f3d-1c0e-48da-be74-8cfec452984b",
"locationId": "84703",
"accountId": "15004",
"keyword": "italian restaurant",
"businessName": "Chianti, Koramangala",
"businessStreet": "No 12, 5th Block, Koramangala",
"businessCity": "Bengaluru",
"businessState": "Karnataka",
"businessCountry": "India",
"gridSize": 3,
"gridDistance": 20,
"gridDistanceUnit": "km",
"gridDistanceInKm": 20,
"ranks": [
{
"rank": 6,
"latitude": 12.80803271879746,
"longitude": 77.4894662571528
}
],
"averageRank": 8.25,
"topOneShare": 0,
"topTwoShare": 0,
"status": "COMPLETED",
"latitude": 12.935216,
"longitude": 77.619961,
"placeId": null,
"createdAt": "1719372126514"
}
]
}
}Response body
| Name | Type | Required | Description |
|---|---|---|---|
data | object | optional | |
data.gridrankReportsByLocationId | array of object | optional | |
data.gridrankReportsByLocationId[].id | string | optional | Report ID |
data.gridrankReportsByLocationId[].locationId | string | optional | Location ID |
data.gridrankReportsByLocationId[].accountId | string | optional | Account ID |
data.gridrankReportsByLocationId[].keyword | string | optional | Keyword used for rank analysis |
data.gridrankReportsByLocationId[].businessName | string | optional | Exact name of the business in Google Maps |
data.gridrankReportsByLocationId[].businessStreet | string | optional | Street address of the business |
data.gridrankReportsByLocationId[].businessCity | string | optional | City of the business |
data.gridrankReportsByLocationId[].businessState | string | optional | State of the business |
data.gridrankReportsByLocationId[].businessCountry | string | optional | Country of the business |
data.gridrankReportsByLocationId[].gridSize | integer | optional | Size of the grid used for analysis357 |
data.gridrankReportsByLocationId[].gridDistance | number | optional | Grid distance value |
data.gridrankReportsByLocationId[].gridDistanceUnit | string | optional | Unit of grid distance measurementmikm |
data.gridrankReportsByLocationId[].gridDistanceInKm | number | optional | Grid distance converted to kilometers |
data.gridrankReportsByLocationId[].ranks | array of object | optional | Array of ranking results for each coordinate |
data.gridrankReportsByLocationId[].ranks[].rank | number | optional | Rank at this coordinate (-1 if not ranked) |
data.gridrankReportsByLocationId[].ranks[].latitude | number | optional | Latitude of the grid point |
data.gridrankReportsByLocationId[].ranks[].longitude | number | optional | Longitude of the grid point |
data.gridrankReportsByLocationId[].averageRank | number | optional | Average rank across all grid points |
data.gridrankReportsByLocationId[].topOneShare | number | optional | Percentage of coordinates with rank <= 3 |
data.gridrankReportsByLocationId[].topTwoShare | number | optional | Percentage of coordinates with rank <= 10 |
data.gridrankReportsByLocationId[].status | string | optional | Current status of the reportPROCESSINGCOMPLETED |
data.gridrankReportsByLocationId[].latitude | number | optional | Business latitude coordinate |
data.gridrankReportsByLocationId[].longitude | number | optional | Business longitude coordinate |
data.gridrankReportsByLocationId[].placeId | string | optional | Google Place ID of the business |
data.gridrankReportsByLocationId[].createdAt | string | optional | Epoch timestamp in milliseconds |