Fetch Local Keyword Rankings via API

Track local search rankings on a geo grid with the Synup API, add keywords for a location, and read the rank trend once the background scan lands.

Em resumo

O que este guia realiza

Start tracking keywords for a location on a search-point grid and read the rank results back.

APIs utilizadas

post/api/v1/seo/keywordsAdicionar palavras-chave monitoradas a um local
get/api/v1/seo/keywordsObter a visão geral de classificação de um local
get/api/v1/seo/rollupObter o resumo de classificação de todos os locais

Referência

SEO

Pré-requisitos

An API key with write access to add keywords
The locationId to track

Casos de uso típicos

Adding a rank-tracking tab to your product
Monitoring how a location ranks around its address
Reporting keyword movement to a business owner

Local rank tracking is a write to start it and a read to see it. POST /api/v1/seo/keywords begins tracking up to 25 keywords per location on a grid of search points around the business. The grid geometry (3, 5 or 7 points per side, a set distance apart) is fixed the first time a location is configured.

curl -X POST https://ai.synup.com/api/v1/seo/keywords \
  -H "Authorization: Bearer $SYNUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "LOCATION_ID",
    "keywords": ["dentist san francisco", "teeth whitening near me"],
    "gridSize": 5,
    "distanceKm": 1.5
  }'

Results do not come back on that call. A scan runs in the background for each new keyword, so the first read right after adding will show the keywords with no ranks yet. Poll GET /api/v1/seo/keywords until they land.

curl "https://ai.synup.com/api/v1/seo/keywords?locationId=LOCATION_ID" \
  -H "Authorization: Bearer $SYNUP_API_KEY"

GET /api/v1/seo/keywords returns the tracked keywords, the monthly rank trend, the grid and the stat cards. For a client dashboard, GET /api/v1/seo/rollup gives one row per location instead of one location's full detail. Because the scan is asynchronous, treat rank data as something you read on a schedule, not something you block a page render on.

Rankings sit alongside profile analytics and AI visibility in the local marketing guide. The AI agent guide uses these same reads as the signal an agent acts on.