Synup
Schlüssel erstellen
GuideAnleitungen/Rezepte/Fetch local keyword rankings

Diese Anleitung ist auf Englisch verfügbar.

How do I track and fetch local keyword rankings through the API?

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.

Auf einen Blick

Was diese Anleitung leistet
Start tracking keywords for a location on a search-point grid and read the rank results back.
Verwendete APIs
Referenz
SEO
Voraussetzungen
  • An API key with write access to add keywords
  • The locationId to track
Typische Anwendungsfälle
  • 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.