Endpoints API
Endpoints API
Interagissez avec l'API GEOCitation pour lancer des audits et récupérer des données sémantiques structurées.
POST /v1/audits — Lancer un Nouvel Audit
Initialise un nouvel audit sémantique AEO/GEO. C'est une opération asynchrone — vous recevez un 202 immédiatement, et l'analyse s'exécute en arrière-plan.
Paramètres du Corps de la Requête
| Paramètre | Type | Requis | Description |
|---|---|---|---|
audit_type | string | Oui | Type d'audit. Enum : "market", "gap". |
keyword | string | Oui | Le mot-clé ou sujet principal de l'audit. |
user_url | string | Non | URL de la page à analyser. Requis si audit_type="gap". |
language | string | Oui | Langue cible (ex. "fr", "en"). |
country | string | Oui | Code pays cible (ex. "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} — Récupérer le Statut et le Résultat
Retourne le statut actuel d'un audit. Une fois l'audit terminé, la même réponse inclut directement l'output structuré complet — aucun appel séparé n'est nécessaire.
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 — Vérification Légère du Statut
Un endpoint plus léger si vous n'avez besoin que du statut courant (sans le payload complet) — utile pour interroger le statut sans télécharger tout le résultat à chaque vérification.
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"
}