API & Webhooks

Pull your geo-grid scans, AI visibility runs and keyword rank trends into Zapier, n8n, Looker Studio or your own dashboard. One bearer token works for both the REST API and the MCP server (Claude, Cursor).

Authentication

Create a token in Settings → AI access, then send it as a bearer header. 60 requests/minute per token; every response is scoped to the token's account.

curl https://gbppeak.com/api/v1/scans?limit=5 \
  -H "Authorization: Bearer gbpk_…"

Endpoints

GET/api/v1/locationsSaved locations for the token's account.
GET/api/v1/scans?locationId=&keyword=&limit=Geo-grid rank scan history with avg rank / top-3 / found stats.
GET/api/v1/scans/{id}One scan including every grid point + competitors.
POST/api/v1/scansTrigger scans. Costs points; requires "confirm": true.
DELETE/api/v1/scansCancel the running scan queue.
GET/api/v1/keyword-ranksKeyword × location trends with 7d / 30d / lifetime deltas.
GET/api/v1/geo-runsAI answer-engine run history (ChatGPT, Gemini, Perplexity…).
GET/api/v1/geo-runs/{id}One full AI run — per-engine recommended businesses.
GET/api/v1/openapi.jsonThe OpenAPI 3.1 spec for everything above.

Webhooks (Zapier · n8n)

Register a URL in Settings → Webhooks. When a scan or AI run finishes we POST a JSON payload signed with X-GBPPeak-Signature: sha256=HMAC(secret, timestamp + "." + body) — the same pattern Stripe uses. Events: scan.done, geo_run.done.

{
  "event": "scan.done",
  "created_at": "2026-09-23T09:00:00Z",
  "data": { "scanId": 812, "keyword": "greek yogurt", "avgRank": 3.4, "top3": 12, "totalPoints": 25 }
}

Looker Studio

A ready-made community connector lives in the repo at tools/looker-connector/ — deploy it as an Apps Script, paste your token, and scan/rank tables appear as Looker data sources.