Endpoints API
Endpoints API
Interact with the GEOCitation API to launch audits and retrieve structured semantic data.
POST /v1/audits — Launch a New Audit
Initiates a new AEO/GEO semantic audit. This is an asynchronous operation — you receive a 202 immediately, and the actual analysis runs in the background.
Request Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
audit_type | string | Yes | Type of audit. Enum: "market", "gap". |
keyword | string | Yes | The primary keyword or topic for the audit. |
user_url | string | No | URL of the page to analyze. Required when audit_type="gap". |
language | string | Yes | Target language (e.g. "fr", "en"). |
country | string | Yes | Target country code (e.g. "FR", "US"). |
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": "gap",
"keyword": "agence seo bordeaux",
"user_url": "https://example.com/seo-page",
"language": "fr",
"country": "FR"
}'json
HTTP/1.1 202 Accepted
{
"audit_id": "3227a3e3-1a2b-4c5d-8e9f-000000000000",
"status": "pending",
"created_at": "2026-07-11T14:32:00Z"
}GET /v1/audits/{audit_id} — Retrieve Status and Result
Returns the current status of an audit. Once the audit is completed, the same response includes the full structured output — no separate call needed.
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": { "...": "..." } }
}GET /v1/audits/{audit_id}/status — Lightweight Status Check
A lighter endpoint if you only need the current status (without the full output payload) — useful for polling without downloading the full result on every check.
bash
curl -X GET https://api.geocitation.io/v1/audits/3227a3e3-1a2b-4c5d-8e9f-000000000000/status \
-H "X-API-Key: geo_citation_YOUR_KEY"json
HTTP/1.1 200 OK
{
"status": "running",
"audit_id": "3227a3e3-1a2b-4c5d-8e9f-000000000000"
}