API GeoGenee — Documentation

L'API REST GeoGenee vous donne accès à vos données de visibilité dans les IA génératives (scores, audits techniques GEO, concurrents, sources) et vous permet de lancer des analyses à la demande. Elle est disponible pour tous les comptes. Cette page documente chaque endpoint avec un exemple de réponse complet.

1. Authentification

Générez une clé API dans Réglages → API & développeurs. La clé (format gg_live_…) n'est affichée qu'une seule fois. Envoyez-la sur chaque requête :

curl https://api-geo.genee.tech/api/v1/me \
  -H "Authorization: Bearer gg_live_VOTRE_CLE"

Alternative : en-tête X-API-Key: gg_live_….

2. URL de base

https://api-geo.genee.tech/api/v1

Toutes les réponses sont en JSON (UTF-8). Les dates sont au format ISO 8601 (UTC).

3. Endpoints

Compte & usage

GET/me

Votre compte, vos limites effectives (plan + overrides) et votre consommation du mois.

Codes de réponse

200Succès
401Clé API manquante, invalide ou révoquée
429Trop de requêtes (limite de débit dépassée)

Réponse (200)

{
  "email": "vous@exemple.fr",
  "plan": "pro",
  "limits": {
    "max_sites": 1,
    "max_tracked_prompts": 30,
    "max_competitors": 10,
    "ai_runs_per_month": 3000,
    "history_days": 365,
    "audit_pages": 100
  },
  "usage": {
    "sites": { "used": 1, "limit": 1, "remaining": 0 },
    "ai_runs_month": {
      "used": 420, "limit": 3000, "remaining": 2580, "bonus_credits": 0
    }
  }
}

GET/usage

Identique à la partie « usage » de /me : quota et consommation, crédits IA bonus restants.

Codes de réponse

200Succès
401Clé API manquante, invalide ou révoquée
429Trop de requêtes (limite de débit dépassée)

Réponse (200)

{
  "plan": "pro",
  "limits": { "max_sites": 1, "ai_runs_per_month": 3000, "...": "..." },
  "usage": {
    "sites": { "used": 1, "limit": 1, "remaining": 0 },
    "ai_runs_month": {
      "used": 420, "limit": 3000, "remaining": 2580, "bonus_credits": 0
    }
  }
}

Sites

GET/sites

La liste de vos sites suivis.

Codes de réponse

200Succès
401Clé API manquante, invalide ou révoquée
429Trop de requêtes (limite de débit dépassée)

Réponse (200)

{
  "data": [
    {
      "id": "site_8f2…",
      "url": "https://exemple.fr",
      "label": "Exemple",
      "is_active": true,
      "created_at": "2026-06-01T10:00:00+00:00"
    }
  ]
}

Audit technique GEO

POST/sites/{id}/audit/run

Lance un audit GEO de la page d'accueil et renvoie le résultat (synchrone).

Renvoie 201 Created.

Codes de réponse

201Audit créé et renvoyé
404Site introuvable ou n'appartenant pas à votre compte
401Clé API manquante, invalide ou révoquée
429Trop de requêtes (limite de débit dépassée)

Réponse (201)

{
  "data": {
    "total": 78,
    "grade": "B",
    "final_url": "https://exemple.fr/",
    "checks": {
      "schema": { "score": 10, "max": 15, "label": "Données structurées" },
      "llms": { "score": 0, "max": 10, "label": "llms.txt" },
      "...": "..."
    },
    "created_at": "2026-06-21T12:00:00+00:00"
  }
}

GET/sites/{id}/audit

Dernier audit technique GEO. Renvoie data: null si aucun audit.

Codes de réponse

200Succès
404Site introuvable ou n'appartenant pas à votre compte
401Clé API manquante, invalide ou révoquée
429Trop de requêtes (limite de débit dépassée)

Réponse (200)

{
  "data": {
    "total": 78,
    "grade": "B",
    "final_url": "https://exemple.fr/",
    "checks": { "schema": { "score": 10, "max": 15 }, "...": "..." },
    "created_at": "2026-06-21T12:00:00+00:00"
  }
}

Visibilité IA

POST/sites/{id}/visibility/run

Lance une analyse IA de toutes les questions suivies du site (asynchrone, traitée en file).

Renvoie 202 Accepted. Consomme le quota mensuel de runs IA (plan + crédits bonus).

Codes de réponse

202Analyse acceptée (traitée en file, asynchrone)
403Quota de runs IA du mois atteint
404Site introuvable ou n'appartenant pas à votre compte
401Clé API manquante, invalide ou révoquée
429Trop de requêtes (limite de débit dépassée)

Réponse (202)

{
  "queued": true,
  "mode": "rq"
}

GET/sites/{id}/visibility

Synthèse de visibilité IA : KPIs, par moteur, par thème/ville, classement concurrents, sentiment, sources, citations récentes.

Codes de réponse

200Succès
404Site introuvable ou n'appartenant pas à votre compte
401Clé API manquante, invalide ou révoquée
429Trop de requêtes (limite de débit dépassée)

Réponse (200)

{
  "kpis": {
    "citation_rate": 62,
    "share_of_voice": 34.5,
    "avg_position": 2.1,
    "engines_cited": 6,
    "engines_total": 8,
    "mentions": 41,
    "sentiment_positive": 71,
    "prompts": 30
  },
  "timeseries": [{ "date": "2026-06-01", "value": 55 }],
  "per_engine": [
    { "engine": "openai", "label": "ChatGPT", "color": "#10a37f", "pct": 70 }
  ],
  "per_theme":    [{ "name": "plomberie", "pct": 60, "count": 12 }],
  "per_location": [{ "name": "Lyon", "pct": 58, "count": 10 }],
  "ranking": [
    { "name": "Votre marque", "share": 34, "you": true },
    { "name": "Concurrent A", "share": 21, "you": false }
  ],
  "sentiment": { "positive": 71, "neutral": 24, "negative": 5 },
  "top_sources": [{ "domain": "pagesjaunes.fr", "count": 9 }],
  "recent_mentions": [
    {
      "engine": "openai", "label": "ChatGPT", "color": "#10a37f",
      "prompt": "meilleur plombier à Lyon", "mentioned": true,
      "position": 2, "sentiment": "positive",
      "created_at": "2026-06-21T08:00:00+00:00"
    }
  ]
}

GET/sites/{id}/runs

Les 100 derniers passages IA bruts (un par question × moteur).

Codes de réponse

200Succès
404Site introuvable ou n'appartenant pas à votre compte
401Clé API manquante, invalide ou révoquée
429Trop de requêtes (limite de débit dépassée)

Réponse (200)

{
  "data": [
    {
      "engine": "perplexity",
      "mentioned": true,
      "position": 1,
      "share_of_voice": 40.0,
      "sentiment": "positive",
      "cited_sources": [{ "domain": "exemple.fr", "url": "https://exemple.fr/" }],
      "created_at": "2026-06-21T08:00:00+00:00"
    }
  ]
}

Concurrents

GET/sites/{id}/competitors

Les concurrents suivis pour ce site.

Codes de réponse

200Succès
404Site introuvable ou n'appartenant pas à votre compte
401Clé API manquante, invalide ou révoquée
429Trop de requêtes (limite de débit dépassée)

Réponse (200)

{
  "data": [
    { "name": "Concurrent A", "domain": "concurrent-a.fr" }
  ]
}

4. Paramètres de chemin

{id} = l'identifiant du site (champ id renvoyé par GET /sites, ex. site_8f2…).

5. Codes d'état & erreurs

Code	Signification
`200`	Succès (lecture).
`201`	Ressource créée (audit lancé).
`202`	Accepté — traitement asynchrone lancé (analyse IA).
`401`	Clé API manquante ou invalide / révoquée.
`403`	Quota atteint (ex. runs IA du mois épuisés).
`404`	Ressource introuvable (site inexistant ou non vous appartenant).
`429`	Trop de requêtes (voir limites ci-dessous).

Toutes les erreurs suivent le même format :

{
  "error": {
    "code": "quota_exceeded",
    "message": "Quota de runs IA atteint ce mois-ci (3000/3000).",
    "details": { "used": 3000, "limit": 3000 },
    "request_id": "a1b2c3…"
  }
}

6. Limites de débit

Lecture : 120 requêtes/minute par clé. Lancement d'audit : 30/heure. Lancement d'analyse IA : 20/heure (et limité par votre quota mensuel de runs IA, visible via GET /usage).

Générer ma clé API →

Mentions légales · CGV / CGU · Confidentialité