Getting Started
Getting Started
Make your first API call in 4 steps.
1
Step 1 — Create an API Key
Go to your dashboard API Keys page and create a new key. Copy it — it's shown only once. You can optionally set a webhook URL at this step to be notified when audits complete.
Free Trial
Free plan includes 1 audit. Upgrade on the billing page for more quota.
2
Step 2 — Launch an Audit
Send a POST request with your keyword, language, and country. You'll receive a 202 with an audit_id.
bash
curl -X POST https://api.geocitation.io/v1/audits \
-H "X-API-Key: geo_citation_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"audit_type": "market",
"keyword": "agence seo paris",
"language": "fr",
"country": "FR"
}'json
HTTP/1.1 202 Accepted
{
"audit_id": "3227a3e3-1a2b-4c5d-8e9f-000000000000",
"status": "pending"
}3
Step 3 — Retrieve the Result
Once the audit is completed, retrieve the full structured JSON payload with a single GET request on the same audit_id.
bash
curl -X GET https://api.geocitation.io/v1/audits/3227a3e3-1a2b-4c5d-8e9f-000000000000 \
-H "X-API-Key: geo_citation_YOUR_KEY"json
HTTP/1.1 200 OK
{
"audit_id": "3227a3e3-1a2b-4c5d-8e9f-000000000000",
"status": "completed",
"audit_type": "market",
"keyword": "agence seo paris",
"created_at": "2026-07-11T14:32:00Z",
"completed_at": "2026-07-11T14:39:05Z",
"output": { "metadata": { "...": "..." }, "market_serp": { "...": "..." } }
}4
Step 4 — Get Notified (Webhooks)
If you configured a webhook URL on your API key, you'll receive a POST notification the moment your audit completes or fails — no polling required. See the Webhooks section for details.
json
// Webhook payload received on your endpoint
{
"event": "audit.completed",
"audit_id": "3227a3e3-1a2b-4c5d-8e9f-000000000000",
"status": "completed",
"quality_status": "success",
"total_ms": 305000
}