Synup
Create a key
v1Resources/Listings Published/getGet Share of Voice

Get Share of Voice

Your Grid Rank share vs. named competitors, your best-performing keywords ranked by top-3 share, and a monthly avg-rank trend over the window — for one location.

get/api/v1/seo/share-of-voice
seo:read
Query parameters
locationIdstringrequired
The location to look up. Look it up with GET /api/v1/locations.
clientIdstringoptional
The location's client. Only needed to disambiguate when your key is scoped to specific clients.
fromstringoptional
Window start (ISO date). Defaults to 30 days ago.
tostringoptional
Window end (ISO date). Defaults to now.
keywordIdstringoptional
A tracked keyword id from maps.keywords to read Top 3 on Google Maps for. Omit to use the newest keyword with a measured scan.
Response
dataobjectoptional
comparisonobjectoptional
You vs. named competitors by grid top-3 share.
availablebooleanoptional
Whether this location has grid-rank data to compute Share of Voice from.
rowsarray of objectoptional
One row per business in the comparison — you and your named competitors.
namestringoptional
The business name, or your own client name for your own row.
top3Pctnumberoptional
Share of tracked keywords where this business ranks in the top 3 (0–100), or null if not enough data.
isYoubooleanoptional
True on the row for your own location. Omitted (never false) on competitor rows.
keywordsobjectoptional
This location's keywords, ranked by latest top-3 share.
availablebooleanoptional
Whether this location has grid-rank data to compute Share of Voice from.
rowsarray of objectoptional
One row per tracked keyword.
keywordstringoptional
The tracked keyword.
top3Pctnumberoptional
Share of tracked keywords where this business ranks in the top 3 (0–100), or null if not enough data.
avgRanknumberoptional
Average rank across the window, or null if not enough data.
performanceobjectoptional
Monthly average-rank trend per keyword, bounded by from/to.
availablebooleanoptional
Whether this location has grid-rank data to compute Share of Voice from.
seriesarray of objectoptional
One series per tracked keyword.
keywordstringoptional
The tracked keyword.
pointsarray of objectoptional
Monthly average-rank data points for this keyword.
mapsobjectoptional
Top 3 on Google Maps for one keyword, from one stored grid scan.
availablebooleanrequired
False when the location isn't one your key can read.
keywordsarray of objectrequired
The location's active tracked keywords, newest first.
idstringrequired
The tracked keyword's id.
keywordstringrequired
The tracked keyword.
measuredbooleanrequired
True when a stored scan with at least one measured spot exists for this keyword.
selectedKeywordIdstringrequired
The keyword every maps number is for. Null when the location tracks no keywords.
selectionstring (requested | default)required
requested: you named the keyword with keywordId. default: the newest keyword with a measured scan, else the newest keyword.
reportobjectrequired
The selected keyword's newest scan with a measured spot. Null means no measured scan, never 0%.
idstringrequired
The stored report's id.
keywordIdstringrequired
The tracked keyword's id.
keywordstringrequired
The tracked keyword.
yearMonthstringrequired
The month this point covers, as "YYYY-MM".
gridSizeintegerrequired
The grid's configured side length when it was scanned. points holds the actual spots.
completedAtstringrequired
When the full-grid collection behind these exact results was completed. Null unless that is proven.
generatedAtstringrequired
The report's recorded date, set when it was first finalized. Not a collection time, a last-update time or a live check.
evidencestring (proven | unverified)required
proven: every counted spot matches the current keyword and grid. unverified: a legacy scan whose keyword and grid can't be confirmed.
pointsarray of objectrequired
Every stored grid spot, in row and column order, with its state.
missingPointsintegerrequired
Grid spots with no stored result at all.
withheldPointsintegerrequired
Stored spots from an earlier keyword or grid setup. Shown as withheld and not counted.
countedintegerrequired
Stored spots this location counts, leaving out water and excluded spots.
measuredintegerrequired
Counted spots with a measured answer (ranked or outside). The denominator for top3.
noDataintegerrequired
Counted spots whose check failed. Not a ranking.
top3integerrequired
Measured spots where you ranked in the top 3.
outsideintegerrequired
Measured spots where you weren't in the tracked top 20.
top3Pctnumberrequired
Share of tracked keywords where this business ranks in the top 3 (0–100), or null if not enough data.
avgRanknumberrequired
Average rank over the measured spots, with outside counted as 21. Null when nothing was measured.
bestRankintegerrequired
Best measured position, 1 to 20. Null when every measured spot is outside.
businessPointobjectrequired
The sampled spot closest to the location's own coordinates. A search point, not the address itself. Null when the location has no coordinates.
newerUnmeasuredobjectrequired
A newer scan for the keyword that measured nothing countable, disclosed beside report rather than in its place. Null when there is none.
yearMonthstringrequired
The month this point covers, as "YYYY-MM".
generatedAtstringrequired
The report's recorded date, set when it was first finalized. Not a collection time, a last-update time or a live check.
competitorsarray of objectrequired
You plus the top competitors, counted over the report's measured spots. Empty without a report.
idstringrequired
A stable id for the business: id: followed by its Google place id, else its name plus address. "you" on your own row.
namestringrequired
The business name as recorded. May be empty, and is empty on your own row.
addressstringrequired
The address as recorded, when the scan captured one. Tells same-name branches apart.
isYoubooleanrequired
True on the row for your own location. Omitted (never false) on competitor rows.
top3Spotsintegerrequired
Measured spots where this business ranked in the top 3. Businesses share spots, so rows don't add up to the total.
scanInProgressbooleanrequired
True while a grid scan is running for this location. Location-wide: it doesn't say which keywords the scan covers.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
429Too many requests. Retry after the number of seconds in the Retry-After header.
get/api/v1/seo/share-of-voice
Your API key
locationId *
clientId
from
to
keywordId
{
  "data": {
    "comparison": {
      "available": true,
      "rows": [
        {
          "name": "Acme Dental — Downtown",
          "top3Pct": 62,
          "isYou": true
        },
        {
          "name": "Bright Smiles Dental",
          "top3Pct": 74
        }
      ]
    },
    "keywords": {
      "available": true,
      "rows": [
        {
          "keyword": "dentist near me",
          "top3Pct": 62,
          "avgRank": 3.2
        }
      ]
    },
    "performance": {
      "available": true,
      "series": [
        {
          "keyword": "dentist near me",
          "points": [
            {
              "yearMonth": "2026-01",
              "avgRank": 3.6
            },
            {
              "yearMonth": "2026-02",
              "avgRank": 3.2
            }
          ]
        }
      ]
    }
  }
}

Guides that use this endpoint