API v1 · offre Pro et au-dessus

Documentation de l'API GEO Monitor

L'API de GEO Monitor donne accès, depuis vos propres outils, à tout ce que vous voyez dans le dashboard : visibilité de vos marques dans ChatGPT, Gemini, Copilot, Claude et l'aperçu IA de Google, réponses complètes des IA, sources et pages citées, concurrents, requêtes de fan-out, et leur évolution dans le temps. Elle permet aussi de créer, modifier et supprimer vos marques, vos prompts et vos concurrents.

Créer une clé API Spécification OpenAPI
Sommaire

Démarrage rapide

  1. Dans le dashboard, ouvrez le menu API (réservé aux administrateurs) et créez une clé. Copiez-la : elle ne sera affichée qu'une fois.
  2. Rangez-la dans une variable d'environnement, jamais dans du code publié ou exécuté dans un navigateur.
  3. Vérifiez qu'elle fonctionne avec GET /me, listez vos marques, puis lisez leurs indicateurs.
Terminal
export GEO_MONITOR_API_KEY="gm_live_..."

curl "https://www.geo-monitor.fr/api/v1/me" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

curl "https://www.geo-monitor.fr/api/v1/brands" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

curl "https://www.geo-monitor.fr/api/v1/brands/<brand_id>/overview?days=30" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"
JavaScript (Node.js 18+)
const res = await fetch('https://www.geo-monitor.fr/api/v1/brands/<brand_id>/visibility?days=90&granularity=week', {
  headers: { Authorization: `Bearer ${process.env.GEO_MONITOR_API_KEY}` },
})
if (!res.ok) throw new Error((await res.json()).error.message)
const { data } = await res.json()
console.log(data.summary.score, data.series)
Python
import os, requests

r = requests.get(
    "https://www.geo-monitor.fr/api/v1/brands/<brand_id>/results",
    headers={"Authorization": f"Bearer {os.environ['GEO_MONITOR_API_KEY']}"},
    params={"llm": "gpt", "mentioned": "false", "include_content": "false"},
)
r.raise_for_status()
for reponse in r.json()["data"]:
    print(reponse["prompt"], reponse["llm"], reponse["competitors"])

Authentification

Chaque requête doit porter une clé API dans l'en-tête Authorization: Bearer gm_live_.... L'en-tête X-API-Key est aussi accepté. Les appels se font en HTTPS uniquement, de serveur à serveur : n'utilisez pas la clé dans une page web ou une application mobile.

  • Une clé appartient à votre organisation et donne accès à toutes ses marques. Elle reste valide si la personne qui l'a créée quitte l'équipe : révoquez-la depuis le dashboard.
  • Deux niveaux de droits : lecture seule (recommandé pour un tableau de bord ou un export), ou lecture et écriture (créer, modifier et supprimer marques, prompts et concurrents).
  • Révocation immédiate : une clé révoquée est refusée dès la requête suivante. Vous pouvez avoir jusqu'à 20 clés actives, une par outil par exemple.
  • Les clés sont stockées sous forme d'empreinte : GEO Monitor ne peut pas vous redonner une clé perdue. Créez-en une nouvelle et révoquez l'ancienne.
  • L'offre est vérifiée à chaque appel : si votre abonnement repasse sous l'offre Pro, l'API répond 403 plan_required.

Conventions

  • Adresse de base : https://www.geo-monitor.fr/api/v1. La version fait partie de l'adresse : une évolution incompatible donnerait une v2, la v1 restant disponible.
  • Format : JSON en UTF-8, champs en snake_case. Une réponse réussie a la forme { "data": ... }, avec pagination pour les listes et parfois meta (totaux). De nouveaux champs peuvent être ajoutés sans changer de version : ignorez ceux que vous ne connaissez pas.
  • Période : start_date et end_date (AAAA-MM-JJ, bornes incluses, heure de Paris) ou days (1 à 180). Par défaut, les 30 derniers jours, aujourd'hui compris.
  • IA : identifiants gpt (ChatGPT), gemini, copilot, claude et ai-overview (aperçu IA de Google), à combiner dans le paramètre llm séparés par des virgules.
  • Filtres de prompts : prompt_id (un ou plusieurs identifiants) et tag (un ou plusieurs tags) limitent les calculs aux prompts concernés.
  • Pagination : page et per_page (100 au plus). Continuez tant que has_more vaut true.
  • Score de visibilité : part des réponses des IA qui citent la marque, en %. Position : rang de la marque dans la réponse quand elle est citée (1 = citée en premier). Sentiment : de 0 (très négatif) à 100 (très positif).
  • Types de mention dans une réponse : recommended (recommandée), listed (citée dans une liste), incidental (citée en passant), negative. Dans une page source (page_analysis), s'y ajoutent directory, peripheral, link et own_site.
  • Types de site des sources : media, forum, social, video, encyclopedia, brand_site, ecommerce, directory, comparator, institutional, other, ou null pour un domaine pas encore classé.
  • Identifiant de requête : chaque réponse porte un en-tête X-Request-Id, à nous transmettre en cas de question.

Données disponibles

  • Chaque prompt est posé tous les jours à chaque IA de votre offre. La dernière réponse de chaque IA est disponible en entier (/results).
  • L'évolution est conservée 6 mois : une photo par jour du score de la marque, par IA et par concurrent, des sources, des pages citées et des requêtes de fan-out.
  • L'évolution par prompt de la mention, de la position et du sentiment (/prompts/{prompt_id}/history, et les filtres prompt_id ou tag sur les indicateurs) est enregistrée depuis le 19 octobre 2026.
  • Les chiffres sont ceux du dashboard et des rapports : même calcul, mêmes données.
  • Un prompt créé est analysé dans les minutes qui suivent (ou dans les 24 heures avec analyze: false) ; il entre dans les historiques dès la fin de son analyse.

Limites

Les limites s'appliquent à votre organisation, toutes clés confondues. La journée commence à minuit UTC.

OffrePar minutePar jour
Pro6010 000
Entreprise et sur mesure12050 000

Chaque réponse indique où vous en êtes :

En-têtes de réponse
X-RateLimit-Limit: 60            # requêtes autorisées par minute
X-RateLimit-Remaining: 57        # restantes dans la minute en cours
X-RateLimit-Reset: 1792428600    # début de la minute suivante (timestamp Unix)
X-RateLimit-Limit-Day: 10000
X-RateLimit-Remaining-Day: 9874
X-RateLimit-Reset-Day: 1792454400
Retry-After: 12                  # seulement avec une erreur 429, en secondes

Les quotas de votre offre s'appliquent aussi à l'API : nombre de marques et de prompts (toutes marques confondues), IA analysées. Les autres limites : 200 prompts par création ou suppression groupée, 1 000 caractères par prompt, 8 tags de 40 caractères par prompt, 180 jours par période, 100 résultats par page.

Erreurs

Les erreurs ont toutes la même forme. Basez votre code sur code (stable), pas sur le message (en français, susceptible d'évoluer).

JSON
{
  "error": {
    "code": "validation_error",
    "message": "days doit être un entier entre 1 et 180.",
    "request_id": "req_5f1c0e9a2b7d4c3e8f6a1b2c3d4e5f60",
    "details": { "parameter": "days" }
  }
}
CodeHTTPSignification
unauthorized401Aucune clé n'a été envoyée.
invalid_api_key401Clé inconnue ou révoquée.
plan_required403Votre offre n'inclut pas l'API (offre Pro et au-dessus).
trial_ended403Essai terminé sans abonnement.
insufficient_scope403Clé en lecture seule utilisée pour une écriture.
quota_exceeded403Quota de marques ou de prompts de votre offre atteint. Les détails donnent le quota et ce qui reste.
not_found404Marque, prompt ou concurrent introuvable dans votre organisation.
validation_error400Paramètre ou corps invalide. details indique le paramètre ou le champ en cause.
conflict409Doublon : marque, prompt ou concurrent déjà suivi.
rate_limited429Limite de débit atteinte. Attendez le nombre de secondes indiqué par Retry-After.
internal_error500Erreur de notre côté. Réessayez ; si elle persiste, écrivez-nous en citant le request_id.

Compte

Votre organisation, votre offre, vos quotas et les IA suivies.

Votre compte

GET/me

Organisation propriétaire de la clé, offre, quotas de marques et de prompts, IA suivies, limites de débit restantes et clé utilisée. Pratique pour vérifier qu'une clé fonctionne.

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/me" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": {
    "organization": {
      "id": "6d1e2f3a-4b5c-4d6e-8f70-819203a4b5c6",
      "name": "Literie Martin SAS"
    },
    "plan": {
      "type": "pro",
      "name": "Pro"
    },
    "limits": {
      "max_brands": 999,
      "brands_used": 2,
      "max_prompts": 100,
      "prompts_used": 48,
      "prompts_remaining": 52
    },
    "llms": [
      "gpt",
      "claude",
      "copilot",
      "gemini",
      "ai-overview"
    ],
    "rate_limit": {
      "per_minute": 60,
      "per_day": 10000,
      "remaining_minute": 59,
      "remaining_day": 9874
    },
    "api_key": {
      "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "Looker Studio",
      "prefix": "gm_live_Ab12Cd",
      "scope": "read",
      "created_at": "2026-10-19T09:12:00.000Z"
    }
  }
}

IA suivies

GET/llms

Identifiants des IA utilisables dans le paramètre llm. Les IA inactives (Perplexity, DeepSeek) ne sont plus analysées mais restent présentes dans l'historique.

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/llms" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": [
    {
      "id": "gpt",
      "name": "ChatGPT",
      "active": true
    },
    {
      "id": "claude",
      "name": "Claude",
      "active": true
    },
    {
      "id": "copilot",
      "name": "Copilot",
      "active": true
    },
    {
      "id": "gemini",
      "name": "Gemini",
      "active": true
    },
    {
      "id": "ai-overview",
      "name": "AI Overview",
      "active": true
    },
    {
      "id": "perplexity",
      "name": "Perplexity",
      "active": false
    },
    {
      "id": "deepseek",
      "name": "DeepSeek",
      "active": false
    }
  ]
}

Marques

Créer, lire, modifier et supprimer les marques suivies.

Lister les marques

GET/brands

Toutes les marques de votre organisation, avec leur nombre de prompts.

Paramètres

ParamètreTypeDescription
page
requête
integerNuméro de page (1 par défaut).
défaut : 1
per_page
requête
integerRésultats par page, 1 à 100 (50 par défaut).
défaut : 50 · 1 à 100

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/brands" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": [
    {
      "id": "3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90",
      "name": "Literie Martin",
      "display_name": "Martin",
      "label": "Martin",
      "sector": "Literie",
      "country": "FR",
      "website": "https://www.literie-martin.fr",
      "site_domains": [
        "literie-martin.fr"
      ],
      "products": "Matelas, sommiers et oreillers fabriqués en France",
      "target_audience": "Particuliers de 30 à 60 ans",
      "marketing_objective": "Être recommandée par les IA pour les requêtes « meilleur matelas »",
      "name_variants": [
        "Literie-Martin",
        "Martin Literie"
      ],
      "brand_detection_instructions": null,
      "llms": [
        "gpt",
        "claude",
        "copilot",
        "gemini",
        "ai-overview"
      ],
      "prompt_count": 24,
      "created_at": "2026-09-02T08:14:22.000Z",
      "updated_at": "2026-10-12T16:40:03.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 1,
    "has_more": false
  }
}

Créer une marque

Clé avec écriture
POST/brands

Crée une marque avec les mêmes règles que le dashboard : champs obligatoires, quota de marques de votre offre, pays pris en charge. Une marque portant déjà le même nom dans l'organisation est refusée (409). Ajoutez ensuite ses prompts avec POST /brands/{brand_id}/prompts.

Corps de la requête (JSON)

ChampTypeDescription
name
obligatoire
stringNom de la marque.
200 caractères max.
sector
obligatoire
stringSecteur d'activité.
500 caractères max.
country
obligatoire
stringPays des analyses : FR, BE, CH, CA, ES, IT, DE, GB, US, PT, NL, AT, SE, DK, NO, FI, PL, IE, LU, GR, AU ou NZ. Non modifiable ensuite.
websitestringSite de la marque (avec ou sans https://).
500 caractères max.
products
obligatoire
stringProduits et services.
5000 caractères max.
target_audience
obligatoire
stringCible.
5000 caractères max.
marketing_objective
obligatoire
stringObjectif marketing.
5000 caractères max.
display_namestringNom d'affichage facultatif.
100 caractères max.
name_variantsarray<string>Autres écritures du nom.
50 éléments max.
brand_detection_instructionsstringConsignes de détection.
2000 caractères max.

Requête

curl
curl -X POST "https://www.geo-monitor.fr/api/v1/brands" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Literie Martin",
  "sector": "Literie",
  "country": "FR",
  "website": "literie-martin.fr",
  "products": "Matelas, sommiers et oreillers fabriqués en France",
  "target_audience": "Particuliers de 30 à 60 ans",
  "marketing_objective": "Être recommandée par les IA pour les requêtes « meilleur matelas »",
  "name_variants": [
    "Literie-Martin"
  ]
}'

Réponse 201

JSON
{
  "data": {
    "id": "3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90",
    "name": "Literie Martin",
    "display_name": "Martin",
    "label": "Martin",
    "sector": "Literie",
    "country": "FR",
    "website": "https://www.literie-martin.fr",
    "site_domains": [
      "literie-martin.fr"
    ],
    "products": "Matelas, sommiers et oreillers fabriqués en France",
    "target_audience": "Particuliers de 30 à 60 ans",
    "marketing_objective": "Être recommandée par les IA pour les requêtes « meilleur matelas »",
    "name_variants": [
      "Literie-Martin",
      "Martin Literie"
    ],
    "brand_detection_instructions": null,
    "llms": [
      "gpt",
      "claude",
      "copilot",
      "gemini",
      "ai-overview"
    ],
    "prompt_count": 0,
    "created_at": "2026-09-02T08:14:22.000Z",
    "updated_at": "2026-10-12T16:40:03.000Z"
  }
}

Lire une marque

GET/brands/{brand_id}

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": {
    "id": "3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90",
    "name": "Literie Martin",
    "display_name": "Martin",
    "label": "Martin",
    "sector": "Literie",
    "country": "FR",
    "website": "https://www.literie-martin.fr",
    "site_domains": [
      "literie-martin.fr"
    ],
    "products": "Matelas, sommiers et oreillers fabriqués en France",
    "target_audience": "Particuliers de 30 à 60 ans",
    "marketing_objective": "Être recommandée par les IA pour les requêtes « meilleur matelas »",
    "name_variants": [
      "Literie-Martin",
      "Martin Literie"
    ],
    "brand_detection_instructions": null,
    "llms": [
      "gpt",
      "claude",
      "copilot",
      "gemini",
      "ai-overview"
    ],
    "prompt_count": 24,
    "created_at": "2026-09-02T08:14:22.000Z",
    "updated_at": "2026-10-12T16:40:03.000Z"
  }
}

Modifier une marque

Clé avec écriture
PATCH/brands/{brand_id}

Modifie un ou plusieurs champs. Le pays ne se modifie pas : il fixe la langue et la localisation des analyses. display_name ne sert qu'à l'affichage ; la détection dans les réponses utilise name et name_variants. Changer website recalcule les domaines reconnus comme votre site.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).

Corps de la requête (JSON)

Tous les champs sont facultatifs ; seuls ceux envoyés sont modifiés. Une chaîne vide efface display_name, brand_detection_instructions ou website.

ChampTypeDescription
namestring
200 caractères max.
display_namestring
100 caractères max.
name_variantsarray<string>Remplace la liste actuelle.
brand_detection_instructionsstring
2000 caractères max.
websitestring
500 caractères max.
sectorstring
500 caractères max.
productsstring
5000 caractères max.
target_audiencestring
5000 caractères max.
marketing_objectivestring
5000 caractères max.

Requête

curl
curl -X PATCH "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "display_name": "Martin",
  "name_variants": [
    "Literie-Martin",
    "Martin Literie"
  ]
}'

Réponse 200

JSON
{
  "data": {
    "id": "3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90",
    "name": "Literie Martin",
    "display_name": "Martin",
    "label": "Martin",
    "sector": "Literie",
    "country": "FR",
    "website": "https://www.literie-martin.fr",
    "site_domains": [
      "literie-martin.fr"
    ],
    "products": "Matelas, sommiers et oreillers fabriqués en France",
    "target_audience": "Particuliers de 30 à 60 ans",
    "marketing_objective": "Être recommandée par les IA pour les requêtes « meilleur matelas »",
    "name_variants": [
      "Literie-Martin",
      "Martin Literie"
    ],
    "brand_detection_instructions": null,
    "llms": [
      "gpt",
      "claude",
      "copilot",
      "gemini",
      "ai-overview"
    ],
    "prompt_count": 24,
    "created_at": "2026-09-02T08:14:22.000Z",
    "updated_at": "2026-10-12T16:40:03.000Z"
  }
}

Supprimer une marque

Clé avec écriture
DELETE/brands/{brand_id}

Supprime définitivement la marque, ses prompts, ses concurrents et tout son historique. Action irréversible : le paramètre confirm=true est obligatoire.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
confirm
requête, obligatoire
booleanDoit valoir true.

Requête

curl
curl -X DELETE "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90?confirm=true" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": {
    "id": "3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90",
    "deleted": true
  }
}

Prompts

Les questions posées chaque jour aux IA pour chaque marque.

Lister les prompts

GET/brands/{brand_id}/prompts

Prompts de la marque, avec le résumé de leur dernière analyse (latest) : IA qui citent la marque, taux de mention, position et sentiment moyens.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
tag
requête
stringLimiter aux prompts qui portent l'un de ces tags (séparés par des virgules).
status
requête
stringpending (pas encore analysé) ou analyzed.
valeurs : pending, analyzed
search
requête
stringTexte contenu dans le prompt.
include_stats
requête
booleanAjoute le résumé latest de la dernière analyse. Vrai par défaut.
défaut : true
page
requête
integerNuméro de page (1 par défaut).
défaut : 1
per_page
requête
integerRésultats par page, 1 à 100 (50 par défaut).
défaut : 50 · 1 à 100

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/prompts?tag=Comparatif&per_page=20" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": [
    {
      "id": "8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50",
      "brand_id": "3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90",
      "content": "Quel est le meilleur matelas pour le mal de dos ?",
      "tags": [
        "Mal de dos",
        "Comparatif"
      ],
      "status": "analyzed",
      "is_active": true,
      "created_at": "2026-09-02T08:20:11.000Z",
      "updated_at": "2026-09-02T08:20:11.000Z",
      "latest": {
        "analyzed_llms": [
          "gpt",
          "claude",
          "copilot",
          "gemini",
          "ai-overview"
        ],
        "mentioned_llms": [
          "gpt",
          "claude",
          "copilot"
        ],
        "mention_rate": 60,
        "avg_position": 2.3,
        "avg_sentiment": 74,
        "last_analysis_date": "2026-10-19"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 24,
    "has_more": false
  }
}

Créer des prompts

Clé avec écriture
POST/brands/{brand_id}/prompts

Crée un prompt (content, tags) ou un lot de 200 prompts au plus (prompts). Les espaces superflus sont retirés et les prompts déjà suivis par la marque sont ignorés (comparaison sans tenir compte des majuscules) et listés dans skipped. Le quota de prompts de votre offre est vérifié pour l'ensemble du lot : s'il ne reste pas assez de place, rien n'est enregistré (403 quota_exceeded). Par défaut la première analyse démarre immédiatement (analysis: "started") ; passez analyze: false pour attendre les passages suivants.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).

Corps de la requête (JSON)

Soit content (un prompt), soit prompts (un lot).

ChampTypeDescription
contentstringTexte du prompt.
1000 caractères max.
tagsarray<string>Tags du prompt.
8 éléments max.
promptsarray<object>Lot de prompts.
200 éléments max.
analyzebooleanLancer la première analyse tout de suite.
défaut : true

Requête

curl
curl -X POST "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/prompts" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompts": [
    {
      "content": "Quel est le meilleur matelas pour le mal de dos ?",
      "tags": [
        "Mal de dos",
        "Comparatif"
      ]
    },
    {
      "content": "Quelle marque de matelas français choisir ?",
      "tags": [
        "Comparatif"
      ]
    }
  ],
  "analyze": true
}'

Réponse 201

JSON
{
  "data": {
    "created": [
      {
        "id": "8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50",
        "brand_id": "3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90",
        "content": "Quel est le meilleur matelas pour le mal de dos ?",
        "tags": [
          "Mal de dos",
          "Comparatif"
        ],
        "status": "pending",
        "is_active": true,
        "created_at": "2026-09-02T08:20:11.000Z",
        "updated_at": "2026-09-02T08:20:11.000Z"
      }
    ],
    "skipped": [
      "Quelle marque de matelas français choisir ?"
    ],
    "analysis": "started"
  }
}

Supprimer plusieurs prompts

Clé avec écriture
POST/brands/{brand_id}/prompts/delete

Supprime jusqu'à 200 prompts de la marque, avec leurs résultats et leur historique. Les identifiants qui n'appartiennent pas à la marque sont listés dans not_found.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).

Corps de la requête (JSON)

ChampTypeDescription
ids
obligatoire
array<string (uuid)>Identifiants des prompts à supprimer.
200 éléments max.

Requête

curl
curl -X POST "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/prompts/delete" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50"
  ]
}'

Réponse 200

JSON
{
  "data": {
    "deleted": [
      "8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50"
    ],
    "not_found": []
  }
}

Analyser les prompts en attente

Clé avec écriture
POST/brands/{brand_id}/analyze

Lance tout de suite la première analyse des prompts en attente (status: pending), sur toutes les IA de votre offre. Utile si vous avez créé des prompts avec analyze: false. L'analyse tourne en arrière-plan (quelques minutes) ; sans cet appel, les prompts en attente sont analysés lors des passages suivants, dans les 24 heures.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).

Requête

curl
curl -X POST "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/analyze" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 202

JSON
{
  "data": {
    "analysis": "started",
    "pending_prompts": 3
  }
}

Lire un prompt

GET/prompts/{prompt_id}

Paramètres

ParamètreTypeDescription
prompt_id
chemin, obligatoire
string (uuid)Identifiant du prompt.

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/prompts/8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": {
    "id": "8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50",
    "brand_id": "3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90",
    "content": "Quel est le meilleur matelas pour le mal de dos ?",
    "tags": [
      "Mal de dos",
      "Comparatif"
    ],
    "status": "analyzed",
    "is_active": true,
    "created_at": "2026-09-02T08:20:11.000Z",
    "updated_at": "2026-09-02T08:20:11.000Z",
    "latest": {
      "analyzed_llms": [
        "gpt",
        "claude",
        "copilot",
        "gemini",
        "ai-overview"
      ],
      "mentioned_llms": [
        "gpt",
        "claude",
        "copilot"
      ],
      "mention_rate": 60,
      "avg_position": 2.3,
      "avg_sentiment": 74,
      "last_analysis_date": "2026-10-19"
    }
  }
}

Modifier un prompt

Clé avec écriture
PATCH/prompts/{prompt_id}

Modifie le texte et les tags. Changer le texte efface les résultats et l'historique du prompt (une évolution mesurée avec une autre formulation ne serait plus comparable) puis relance l'analyse, sauf si analyze: false. Pour les tags, utilisez soit tags (remplace la liste), soit add_tags / remove_tags.

Paramètres

ParamètreTypeDescription
prompt_id
chemin, obligatoire
string (uuid)Identifiant du prompt.

Corps de la requête (JSON)

ChampTypeDescription
contentstringNouveau texte. Efface les résultats et l'historique du prompt.
1000 caractères max.
tagsarray<string>Remplace tous les tags.
add_tagsarray<string>Tags à ajouter.
remove_tagsarray<string>Tags à retirer.
analyzebooleanAprès un changement de texte : relancer l'analyse tout de suite.
défaut : true

Requête

curl
curl -X PATCH "https://www.geo-monitor.fr/api/v1/prompts/8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "add_tags": [
    "Prioritaire"
  ]
}'

Réponse 200

JSON
{
  "data": {
    "id": "8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50",
    "brand_id": "3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90",
    "content": "Quel est le meilleur matelas pour le mal de dos ?",
    "tags": [
      "Mal de dos",
      "Comparatif",
      "Prioritaire"
    ],
    "status": "analyzed",
    "is_active": true,
    "created_at": "2026-09-02T08:20:11.000Z",
    "updated_at": "2026-09-02T08:20:11.000Z",
    "content_changed": false,
    "analysis": "not_requested"
  }
}

Supprimer un prompt

Clé avec écriture
DELETE/prompts/{prompt_id}

Supprime le prompt, ses résultats et son historique, et libère une place dans votre quota.

Paramètres

ParamètreTypeDescription
prompt_id
chemin, obligatoire
string (uuid)Identifiant du prompt.

Requête

curl
curl -X DELETE "https://www.geo-monitor.fr/api/v1/prompts/8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": {
    "id": "8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50",
    "deleted": true
  }
}

Tags

Les thèmes qui regroupent vos prompts.

Lister les tags

GET/brands/{brand_id}/tags

Tags utilisés par les prompts de la marque, du plus fréquent au plus rare.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/tags" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": [
    {
      "tag": "Comparatif",
      "prompt_count": 9
    },
    {
      "tag": "Mal de dos",
      "prompt_count": 4
    }
  ]
}

Renommer un tag

Clé avec écriture
PATCH/brands/{brand_id}/tags

Renomme un tag sur tous les prompts de la marque qui le portent. Pour ajouter ou retirer un tag sur un prompt, utilisez PATCH /prompts/{prompt_id}.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).

Corps de la requête (JSON)

ChampTypeDescription
from
obligatoire
stringTag actuel (casse exacte).
to
obligatoire
stringNouveau nom.
40 caractères max.

Requête

curl
curl -X PATCH "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/tags" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "Comparatif",
  "to": "Comparatifs"
}'

Réponse 200

JSON
{
  "data": {
    "from": "Comparatif",
    "to": "Comparatifs",
    "updated_prompts": 9
  }
}

Supprimer un tag

Clé avec écriture
DELETE/brands/{brand_id}/tags

Retire le tag de tous les prompts de la marque. Les prompts ne sont pas supprimés.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
tag
requête, obligatoire
stringTag à retirer (casse exacte).

Requête

curl
curl -X DELETE "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/tags?tag=Comparatif" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": {
    "tag": "Comparatif",
    "updated_prompts": 9
  }
}

Visibilité et réponses

Indicateurs, évolution dans le temps et réponses complètes des IA.

Vue d'ensemble

GET/brands/{brand_id}/overview

Les indicateurs clés de la marque sur la période, comparés à la période précédente de même durée : score de visibilité et tendance, position et sentiment moyens, types de mention, rang et part de voix face aux concurrents, volume de sources, d'URLs et de requêtes de fan-out. Le bloc competition est null quand un filtre de prompt ou de tag est appliqué.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
start_date
requête
string (date)Premier jour de la période (AAAA-MM-JJ, heure de Paris).
end_date
requête
string (date)Dernier jour de la période, inclus (aujourd'hui par défaut).
days
requête
integerDurée de la période en jours, 1 à 180 (30 par défaut). Sans start_date, la période finit à end_date ou aujourd'hui.
défaut : 30 · 1 à 180
llm
requête
stringIA retenues, séparées par des virgules : gpt, gemini, copilot, claude, ai-overview (et perplexity, deepseek pour l'historique). Toutes par défaut.
prompt_id
requête
stringLimiter aux prompts indiqués (identifiants séparés par des virgules, 200 au plus).
tag
requête
stringLimiter aux prompts qui portent l'un de ces tags (séparés par des virgules).

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/overview?days=30" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": {
    "period": {
      "start": "2026-09-20",
      "end": "2026-10-19",
      "days": 30
    },
    "previous_period": {
      "start": "2026-08-21",
      "end": "2026-09-19"
    },
    "visibility": {
      "score": 42.5,
      "previous_score": 38.1,
      "trend": 4.4,
      "answers": 3540,
      "mentioned": 1505
    },
    "quality": {
      "avg_position": 2.4,
      "avg_sentiment": 71.2,
      "mention_types": {
        "recommended": 412,
        "listed": 860,
        "incidental": 210,
        "negative": 23
      },
      "measured_answers": 3540
    },
    "competition": {
      "rank": 2,
      "entities": 6,
      "share_of_voice": 27.3,
      "leader": {
        "is_brand": false,
        "competitor_id": "c4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
        "name": "Dormeo",
        "score": 51.2
      }
    },
    "sources": {
      "total_citations": 18240,
      "unique_domains": 412,
      "unique_urls": 2875,
      "top_domain": "comparatif-literie.fr"
    },
    "fan_out": {
      "total_queries": 2930,
      "unique_queries": 1874
    },
    "prompts": {
      "total": 24,
      "active": 24,
      "pending_analysis": 0
    }
  }
}

Évolution de la visibilité

GET/brands/{brand_id}/visibility

Score de visibilité jour par jour (ou par semaine, par mois), global et par IA, avec la position et le sentiment moyens. Le score est la part des réponses qui citent la marque : mentioned / answers × 100. Sans filtre de prompt, la série vient de l'historique quotidien de la marque (6 mois) ; avec prompt_id ou tag, elle vient de l'historique par prompt, disponible depuis le 19 octobre 2026 (source: "prompt_history").

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
start_date
requête
string (date)Premier jour de la période (AAAA-MM-JJ, heure de Paris).
end_date
requête
string (date)Dernier jour de la période, inclus (aujourd'hui par défaut).
days
requête
integerDurée de la période en jours, 1 à 180 (30 par défaut). Sans start_date, la période finit à end_date ou aujourd'hui.
défaut : 30 · 1 à 180
llm
requête
stringIA retenues, séparées par des virgules : gpt, gemini, copilot, claude, ai-overview (et perplexity, deepseek pour l'historique). Toutes par défaut.
prompt_id
requête
stringLimiter aux prompts indiqués (identifiants séparés par des virgules, 200 au plus).
tag
requête
stringLimiter aux prompts qui portent l'un de ces tags (séparés par des virgules).
granularity
requête
stringRegroupement de la série : day (défaut), week (semaines commençant le lundi) ou month.
valeurs : day, week, month · défaut : day

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/visibility?days=90&granularity=week&llm=gpt,gemini" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": {
    "period": {
      "start": "2026-10-13",
      "end": "2026-10-19",
      "days": 7
    },
    "granularity": "day",
    "source": "brand_history",
    "summary": {
      "score": 43.1,
      "answers": 840,
      "mentioned": 362,
      "by_llm": {
        "gpt": {
          "score": 47.5,
          "answers": 168,
          "mentioned": 80
        },
        "gemini": {
          "score": 39.9,
          "answers": 168,
          "mentioned": 67
        }
      }
    },
    "series": [
      {
        "date": "2026-10-13",
        "score": 42.9,
        "answers": 120,
        "mentioned": 51,
        "avg_position": 2.4,
        "avg_sentiment": 72.1,
        "days_measured": 1,
        "by_llm": {
          "gpt": {
            "score": 45.8,
            "answers": 24,
            "mentioned": 11
          },
          "gemini": {
            "score": 37.5,
            "answers": 24,
            "mentioned": 9
          }
        }
      }
    ]
  }
}

Réponses des IA

GET/brands/{brand_id}/results

La dernière réponse de chaque IA à chaque prompt : texte complet, mention et position de la marque, sentiment, type de mention, concurrents cités avec leur position, sources, citations (URL et titre), requêtes de fan-out et contenus riches (produits, cartes, publicités). Pour l'évolution d'un prompt dans le temps, voir GET /prompts/{prompt_id}/history.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
llm
requête
stringIA retenues, séparées par des virgules : gpt, gemini, copilot, claude, ai-overview (et perplexity, deepseek pour l'historique). Toutes par défaut.
prompt_id
requête
stringLimiter aux prompts indiqués (identifiants séparés par des virgules, 200 au plus).
tag
requête
stringLimiter aux prompts qui portent l'un de ces tags (séparés par des virgules).
mentioned
requête
booleantrue : seulement les réponses qui citent la marque ; false : seulement celles qui ne la citent pas.
include_content
requête
booleanInclure le texte complet des réponses (content). Vrai par défaut ; false allège nettement la réponse.
défaut : true
page
requête
integerNuméro de page (1 par défaut).
défaut : 1
per_page
requête
integerRésultats par page, 1 à 100 (25 par défaut).
défaut : 25 · 1 à 100

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/results?llm=gpt&mentioned=false&per_page=10" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": [
    {
      "id": "0b9f6e2a-7c41-4d8e-a3b5-91c2d4e6f7a8",
      "prompt_id": "8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50",
      "prompt": "Quel est le meilleur matelas pour le mal de dos ?",
      "tags": [
        "Mal de dos",
        "Comparatif"
      ],
      "llm": "gpt",
      "analysis_date": "2026-10-19",
      "brand_mentioned": true,
      "brand_position": 2,
      "sentiment_score": 78,
      "mention_type": "recommended",
      "mention_tone": "positive",
      "mention_confidence": 0.92,
      "competitors": [
        {
          "name": "Dormeo",
          "position": 1
        },
        {
          "name": "Matelas Durand",
          "position": 3
        }
      ],
      "sources": [
        "comparatif-literie.fr",
        "literie-martin.fr"
      ],
      "citations": [
        {
          "url": "https://comparatif-literie.fr/meilleur-matelas-mal-de-dos",
          "title": "Meilleur matelas pour le mal de dos : notre comparatif 2026"
        },
        {
          "url": "https://www.literie-martin.fr/matelas-ferme",
          "title": "Matelas ferme Martin"
        }
      ],
      "fan_out_queries": [
        "meilleur matelas mal de dos 2026",
        "matelas ferme avis kinésithérapeute"
      ],
      "rich_content": null,
      "content": "Pour soulager le mal de dos, privilégiez un matelas ferme... 1. Dormeo... 2. Literie Martin..."
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 120,
    "has_more": true
  }
}

Réponses des IA à un prompt

GET/prompts/{prompt_id}/results

La dernière réponse de chaque IA à ce prompt, texte complet compris. Même format que GET /brands/{brand_id}/results.

Paramètres

ParamètreTypeDescription
prompt_id
chemin, obligatoire
string (uuid)Identifiant du prompt.
llm
requête
stringIA retenues, séparées par des virgules : gpt, gemini, copilot, claude, ai-overview (et perplexity, deepseek pour l'historique). Toutes par défaut.
include_content
requête
booleanInclure le texte complet des réponses (content). Vrai par défaut ; false allège nettement la réponse.
défaut : true
page
requête
integerNuméro de page (1 par défaut).
défaut : 1
per_page
requête
integerRésultats par page, 1 à 100 (50 par défaut).
défaut : 50 · 1 à 100

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/prompts/8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50/results" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": [
    {
      "id": "0b9f6e2a-7c41-4d8e-a3b5-91c2d4e6f7a8",
      "prompt_id": "8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50",
      "prompt": "Quel est le meilleur matelas pour le mal de dos ?",
      "tags": [
        "Mal de dos",
        "Comparatif"
      ],
      "llm": "gpt",
      "analysis_date": "2026-10-19",
      "brand_mentioned": true,
      "brand_position": 2,
      "sentiment_score": 78,
      "mention_type": "recommended",
      "mention_tone": "positive",
      "mention_confidence": 0.92,
      "competitors": [
        {
          "name": "Dormeo",
          "position": 1
        },
        {
          "name": "Matelas Durand",
          "position": 3
        }
      ],
      "sources": [
        "comparatif-literie.fr",
        "literie-martin.fr"
      ],
      "citations": [
        {
          "url": "https://comparatif-literie.fr/meilleur-matelas-mal-de-dos",
          "title": "Meilleur matelas pour le mal de dos : notre comparatif 2026"
        },
        {
          "url": "https://www.literie-martin.fr/matelas-ferme",
          "title": "Matelas ferme Martin"
        }
      ],
      "fan_out_queries": [
        "meilleur matelas mal de dos 2026",
        "matelas ferme avis kinésithérapeute"
      ],
      "rich_content": null,
      "content": "Pour soulager le mal de dos, privilégiez un matelas ferme... 1. Dormeo... 2. Literie Martin..."
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 5,
    "has_more": false
  }
}

Évolution d'un prompt

GET/prompts/{prompt_id}/history

Une ligne par jour et par IA : marque citée ou non, position, sentiment, type et ton de la mention, concurrents cités, nombre de sources et de citations. Historique enregistré depuis le 19 octobre 2026.

Paramètres

ParamètreTypeDescription
prompt_id
chemin, obligatoire
string (uuid)Identifiant du prompt.
start_date
requête
string (date)Premier jour de la période (AAAA-MM-JJ, heure de Paris).
end_date
requête
string (date)Dernier jour de la période, inclus (aujourd'hui par défaut).
days
requête
integerDurée de la période en jours, 1 à 180 (30 par défaut). Sans start_date, la période finit à end_date ou aujourd'hui.
défaut : 30 · 1 à 180
llm
requête
stringIA retenues, séparées par des virgules : gpt, gemini, copilot, claude, ai-overview (et perplexity, deepseek pour l'historique). Toutes par défaut.

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/prompts/8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50/history?days=30&llm=gpt" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": {
    "prompt": {
      "id": "8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50",
      "content": "Quel est le meilleur matelas pour le mal de dos ?"
    },
    "period": {
      "start": "2026-10-13",
      "end": "2026-10-19",
      "days": 7
    },
    "summary": {
      "by_llm": {
        "gpt": {
          "days_measured": 7,
          "days_mentioned": 5,
          "mention_rate": 71.4,
          "avg_position": 2.2
        }
      }
    },
    "days": [
      {
        "date": "2026-10-19",
        "llm": "gpt",
        "analysis_date": "2026-10-19",
        "brand_mentioned": true,
        "brand_position": 2,
        "sentiment_score": 78,
        "mention_type": "recommended",
        "mention_tone": "positive",
        "competitors": [
          {
            "name": "Dormeo",
            "position": 1
          }
        ],
        "source_count": 6,
        "citation_count": 8
      }
    ]
  }
}

Sources

Domaines et pages cités par les IA dans leurs réponses.

Domaines cités

GET/brands/{brand_id}/sources

Domaines cités par les IA sur la période : nombre de citations et part du total, nombre de pages différentes, jours où le domaine a été cité, type de site (média, forum, comparateur, e-commerce...) et indication de votre propre site.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
start_date
requête
string (date)Premier jour de la période (AAAA-MM-JJ, heure de Paris).
end_date
requête
string (date)Dernier jour de la période, inclus (aujourd'hui par défaut).
days
requête
integerDurée de la période en jours, 1 à 180 (30 par défaut). Sans start_date, la période finit à end_date ou aujourd'hui.
défaut : 30 · 1 à 180
llm
requête
stringIA retenues, séparées par des virgules : gpt, gemini, copilot, claude, ai-overview (et perplexity, deepseek pour l'historique). Toutes par défaut.
prompt_id
requête
stringLimiter aux prompts indiqués (identifiants séparés par des virgules, 200 au plus).
tag
requête
stringLimiter aux prompts qui portent l'un de ces tags (séparés par des virgules).
search
requête
stringTexte recherché (200 caractères au plus).
sort
requête
stringTri : citations (défaut), days (jours cités), recent (dernière citation) ou name.
valeurs : citations, days, recent, name · défaut : citations
page
requête
integerNuméro de page (1 par défaut).
défaut : 1
per_page
requête
integerRésultats par page, 1 à 100 (50 par défaut).
défaut : 50 · 1 à 100

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/sources?days=30&sort=citations&per_page=20" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": [
    {
      "domain": "comparatif-literie.fr",
      "type": "comparator",
      "is_brand_site": false,
      "citations": 1288,
      "share": 7.1,
      "unique_urls": 64,
      "days_cited": 30,
      "first_seen": "2026-09-20",
      "last_seen": "2026-10-19",
      "llms": [
        "gpt",
        "claude",
        "gemini",
        "ai-overview"
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 412,
    "has_more": true
  },
  "meta": {
    "total_citations": 18240
  }
}

Évolution des domaines

GET/brands/{brand_id}/sources/history

Citations jour par jour des domaines demandés (domain), ou des domaines les plus cités de la période (limit, 5 par défaut).

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
start_date
requête
string (date)Premier jour de la période (AAAA-MM-JJ, heure de Paris).
end_date
requête
string (date)Dernier jour de la période, inclus (aujourd'hui par défaut).
days
requête
integerDurée de la période en jours, 1 à 180 (30 par défaut). Sans start_date, la période finit à end_date ou aujourd'hui.
défaut : 30 · 1 à 180
llm
requête
stringIA retenues, séparées par des virgules : gpt, gemini, copilot, claude, ai-overview (et perplexity, deepseek pour l'historique). Toutes par défaut.
prompt_id
requête
stringLimiter aux prompts indiqués (identifiants séparés par des virgules, 200 au plus).
tag
requête
stringLimiter aux prompts qui portent l'un de ces tags (séparés par des virgules).
domain
requête
stringDomaines à suivre, séparés par des virgules (20 au plus).
limit
requête
integerSans domain : nombre de domaines les plus cités, 1 à 20 (5 par défaut).
défaut : 5 · 1 à 20

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/sources/history?days=30&limit=3" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": {
    "period": {
      "start": "2026-10-13",
      "end": "2026-10-19",
      "days": 7
    },
    "domains": [
      {
        "domain": "comparatif-literie.fr",
        "total_citations": 301,
        "points": [
          {
            "date": "2026-10-13",
            "citations": 42
          },
          {
            "date": "2026-10-14",
            "citations": 45
          }
        ]
      }
    ]
  }
}

Pages citées

GET/brands/{brand_id}/urls

Pages citées par les IA sur la période, avec leur titre, leur taux d'apparition (jours cités sur jours analysés depuis leur première citation ; null pour une page apparue depuis moins de 7 jours d'analyse), leur présence dans la dernière analyse (still_cited) et, quand la page a été lue par GEO Monitor, la façon dont elle parle de votre marque et de vos concurrents (page_analysis).

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
start_date
requête
string (date)Premier jour de la période (AAAA-MM-JJ, heure de Paris).
end_date
requête
string (date)Dernier jour de la période, inclus (aujourd'hui par défaut).
days
requête
integerDurée de la période en jours, 1 à 180 (30 par défaut). Sans start_date, la période finit à end_date ou aujourd'hui.
défaut : 30 · 1 à 180
llm
requête
stringIA retenues, séparées par des virgules : gpt, gemini, copilot, claude, ai-overview (et perplexity, deepseek pour l'historique). Toutes par défaut.
prompt_id
requête
stringLimiter aux prompts indiqués (identifiants séparés par des virgules, 200 au plus).
tag
requête
stringLimiter aux prompts qui portent l'un de ces tags (séparés par des virgules).
domain
requête
stringSeulement les pages de ce domaine.
search
requête
stringTexte recherché (200 caractères au plus).
sort
requête
stringTri : citations (défaut), days (jours cités), recent (dernière citation) ou name.
valeurs : citations, days, recent, name · défaut : citations
page
requête
integerNuméro de page (1 par défaut).
défaut : 1
per_page
requête
integerRésultats par page, 1 à 100 (50 par défaut).
défaut : 50 · 1 à 100

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/urls?days=30&domain=comparatif-literie.fr" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": [
    {
      "url": "https://comparatif-literie.fr/meilleur-matelas-mal-de-dos",
      "title": "Meilleur matelas pour le mal de dos : notre comparatif 2026",
      "domain": "comparatif-literie.fr",
      "is_brand_site": false,
      "citations": 96,
      "days_cited": 28,
      "appearance_rate": 93,
      "first_seen": "2026-09-20",
      "last_seen": "2026-10-19",
      "llms": [
        "gpt",
        "claude",
        "ai-overview"
      ],
      "still_cited": true,
      "still_cited_by": [
        "gpt",
        "ai-overview"
      ],
      "page_analysis": {
        "status": "ok",
        "competitor_site": null,
        "brand_mention": "recommended",
        "competitor_mentions": [
          {
            "name": "Dormeo",
            "mention_type": "listed"
          }
        ]
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 2875,
    "has_more": true
  },
  "meta": {
    "total_citations": 18240,
    "analyzed_days": 30
  }
}

Fan-out et contenus

Requêtes de recherche lancées par les IA, contenus sponsorisés et résultats locaux.

Requêtes de fan-out

GET/brands/{brand_id}/queries

Requêtes de recherche que les IA ont lancées sur le web pour construire leurs réponses (« query fan-out »), avec leur nombre d'occurrences, les jours où elles ont été vues et les prompts qui les ont déclenchées.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
start_date
requête
string (date)Premier jour de la période (AAAA-MM-JJ, heure de Paris).
end_date
requête
string (date)Dernier jour de la période, inclus (aujourd'hui par défaut).
days
requête
integerDurée de la période en jours, 1 à 180 (30 par défaut). Sans start_date, la période finit à end_date ou aujourd'hui.
défaut : 30 · 1 à 180
llm
requête
stringIA retenues, séparées par des virgules : gpt, gemini, copilot, claude, ai-overview (et perplexity, deepseek pour l'historique). Toutes par défaut.
prompt_id
requête
stringLimiter aux prompts indiqués (identifiants séparés par des virgules, 200 au plus).
tag
requête
stringLimiter aux prompts qui portent l'un de ces tags (séparés par des virgules).
search
requête
stringTexte recherché (200 caractères au plus).
sort
requête
stringTri : occurrences (défaut), days, recent ou name.
valeurs : occurrences, days, recent, name · défaut : occurrences
page
requête
integerNuméro de page (1 par défaut).
défaut : 1
per_page
requête
integerRésultats par page, 1 à 100 (50 par défaut).
défaut : 50 · 1 à 100

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/queries?days=30&search=matelas" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": [
    {
      "query": "meilleur matelas mal de dos 2026",
      "occurrences": 41,
      "days_seen": 19,
      "prompt_count": 2,
      "first_seen": "2026-09-22",
      "last_seen": "2026-10-19",
      "llms": [
        "gpt",
        "claude"
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 1874,
    "has_more": true
  },
  "meta": {
    "total_occurrences": 2930
  }
}

Synthèse du fan-out

GET/brands/{brand_id}/fan-out

La synthèse affichée dans Insights > Query fan-out : volumes, requêtes les plus fréquentes, répartition par IA, par jour et par prompt.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
start_date
requête
string (date)Premier jour de la période (AAAA-MM-JJ, heure de Paris).
end_date
requête
string (date)Dernier jour de la période, inclus (aujourd'hui par défaut).
days
requête
integerDurée de la période en jours, 1 à 180 (30 par défaut). Sans start_date, la période finit à end_date ou aujourd'hui.
défaut : 30 · 1 à 180
llm
requête
stringIA retenues, séparées par des virgules : gpt, gemini, copilot, claude, ai-overview (et perplexity, deepseek pour l'historique). Toutes par défaut.
prompt_id
requête
stringLimiter aux prompts indiqués (identifiants séparés par des virgules, 200 au plus).
tag
requête
stringLimiter aux prompts qui portent l'un de ces tags (séparés par des virgules).

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/fan-out?days=30" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": {
    "summary": {
      "total_queries": 2930,
      "unique_queries": 1874,
      "responses_with_fan_out": 1110,
      "avg_queries_per_response": 2.6
    },
    "top_queries": [
      {
        "query": "meilleur matelas mal de dos 2026",
        "count": 41,
        "prompts": 2,
        "llms": [
          "gpt",
          "claude"
        ]
      }
    ],
    "by_llm": [
      {
        "llm": "claude",
        "queries": 1650,
        "responses": 610,
        "avg_per_response": 2.7
      }
    ],
    "over_time": [
      {
        "date": "2026-10-19",
        "queries": 104
      }
    ],
    "by_prompt": [
      {
        "prompt_id": "8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50",
        "prompt_content": "Quel est le meilleur matelas pour le mal de dos ?",
        "queries": 210,
        "unique_queries": 132,
        "llms": [
          "gpt",
          "claude"
        ],
        "last_seen": "2026-10-19"
      }
    ]
  }
}

Contenus sponsorisés et produits

GET/brands/{brand_id}/placements

Publicités et fiches produits affichées dans les réponses des IA (Insights > Contenu sponsorisé et Affichage shopping) : annonceurs, produits, prompts concernés, répartition par IA et par jour. nature=paid ne garde que les achats d'espace avérés, organic les affichages naturels.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
start_date
requête
string (date)Premier jour de la période (AAAA-MM-JJ, heure de Paris).
end_date
requête
string (date)Dernier jour de la période, inclus (aujourd'hui par défaut).
days
requête
integerDurée de la période en jours, 1 à 180 (30 par défaut). Sans start_date, la période finit à end_date ou aujourd'hui.
défaut : 30 · 1 à 180
llm
requête
stringIA retenues, séparées par des virgules : gpt, gemini, copilot, claude, ai-overview (et perplexity, deepseek pour l'historique). Toutes par défaut.
prompt_id
requête
stringLimiter aux prompts indiqués (identifiants séparés par des virgules, 200 au plus).
tag
requête
stringLimiter aux prompts qui portent l'un de ces tags (séparés par des virgules).
nature
requête
stringall (défaut), paid ou organic.
valeurs : all, paid, organic · défaut : all

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/placements?days=30&nature=paid" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": {
    "summary": {
      "total_ads": 34,
      "paid_ads": 12,
      "advertisers_count": 9,
      "prompts_with_ads": 6,
      "products_count": 21
    },
    "advertisers": [
      {
        "advertiser": "Dormeo",
        "domain": "dormeo.fr",
        "ads": 8,
        "paid_ads": 3,
        "products": 5,
        "prompts": 3,
        "llms": [
          "gpt"
        ],
        "is_competitor": true
      }
    ],
    "products": [
      {
        "product": "Matelas Dormeo Memory",
        "advertiser": "Dormeo",
        "domain": "dormeo.fr",
        "ads": 4,
        "prompts": 2,
        "price": "499,00",
        "currency": "EUR",
        "image_url": null,
        "url": "https://www.dormeo.fr/matelas-memory"
      }
    ],
    "prompts": [
      {
        "prompt_id": "8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50",
        "prompt_content": "Quel est le meilleur matelas pour le mal de dos ?",
        "ads": 7,
        "advertisers": 4,
        "llms": [
          "gpt"
        ],
        "last_seen": "2026-10-19"
      }
    ],
    "by_llm": [
      {
        "llm": "gpt",
        "ads": 34
      }
    ],
    "over_time": [
      {
        "date": "2026-10-19",
        "ads": 3
      }
    ]
  }
}

Résultats locaux

GET/brands/{brand_id}/local

Établissements affichés dans les blocs locaux (cartes, listes d'adresses) des réponses, avec leur note, leur meilleur rang et l'indication de votre propre marque (is_brand).

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
start_date
requête
string (date)Premier jour de la période (AAAA-MM-JJ, heure de Paris).
end_date
requête
string (date)Dernier jour de la période, inclus (aujourd'hui par défaut).
days
requête
integerDurée de la période en jours, 1 à 180 (30 par défaut). Sans start_date, la période finit à end_date ou aujourd'hui.
défaut : 30 · 1 à 180
llm
requête
stringIA retenues, séparées par des virgules : gpt, gemini, copilot, claude, ai-overview (et perplexity, deepseek pour l'historique). Toutes par défaut.
prompt_id
requête
stringLimiter aux prompts indiqués (identifiants séparés par des virgules, 200 au plus).
tag
requête
stringLimiter aux prompts qui portent l'un de ces tags (séparés par des virgules).

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/local?days=30" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": {
    "summary": {
      "total_listings": 18,
      "unique_businesses": 7,
      "prompts_with_local": 3,
      "avg_rating": 4.5
    },
    "businesses": [
      {
        "name": "Literie Martin Lyon",
        "category": "Magasin de literie",
        "city": "Lyon",
        "address": "12 rue de la République, 69002 Lyon",
        "rating": 4.7,
        "reviews": 312,
        "appearances": 6,
        "best_rank": 1,
        "prompts": 2,
        "llms": [
          "gpt"
        ],
        "website": "https://www.literie-martin.fr",
        "image_url": null,
        "is_brand": true
      }
    ],
    "by_llm": [
      {
        "llm": "gpt",
        "listings": 18
      }
    ],
    "over_time": [
      {
        "date": "2026-10-19",
        "listings": 2
      }
    ],
    "by_prompt": [
      {
        "prompt_id": "8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50",
        "prompt_content": "Magasin de literie à Lyon",
        "listings": 12,
        "businesses": 6,
        "llms": [
          "gpt"
        ],
        "last_seen": "2026-10-19"
      }
    ]
  }
}

Concurrents

Classement de votre marque face à ses concurrents et gestion des concurrents suivis.

Classement des concurrents

GET/brands/{brand_id}/competitors

Les chiffres de la page Concurrents : rang de la marque, part de voix, écart avec le leader, et pour la marque comme pour chaque concurrent suivi le score de visibilité, sa tendance, le nombre de mentions, la position moyenne, l'IA où il est le plus visible et les prompts où il est cité sans votre marque (lost_prompts). Contient aussi les marques souvent citées mais pas encore suivies (suggestions) et celles que vous avez écartées (ignored). Toutes IA confondues.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
start_date
requête
string (date)Premier jour de la période (AAAA-MM-JJ, heure de Paris).
end_date
requête
string (date)Dernier jour de la période, inclus (aujourd'hui par défaut).
days
requête
integerDurée de la période en jours, 1 à 180 (30 par défaut). Sans start_date, la période finit à end_date ou aujourd'hui.
défaut : 30 · 1 à 180

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/competitors?days=30" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": {
    "period": {
      "start": "2026-09-20",
      "end": "2026-10-19",
      "days": 30
    },
    "kpis": {
      "rank": {
        "rank": 2,
        "total": 6
      },
      "previous_rank": {
        "rank": 3,
        "total": 6
      },
      "share_of_voice": 27,
      "leader_gap": 9,
      "leader_name": "Dormeo",
      "lost_prompts": 5,
      "analyzed_prompts": 24
    },
    "brand": {
      "id": "3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90",
      "name": "Literie Martin",
      "is_brand": true,
      "domain": "literie-martin.fr",
      "variants": [
        "Literie-Martin"
      ],
      "score": 42,
      "trend": 4,
      "mentions": 1505,
      "avg_position": 2.4,
      "best_llm": "claude"
    },
    "competitors": [
      {
        "id": "c4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
        "name": "Dormeo",
        "domain": "dormeo.fr",
        "variants": [],
        "score": 51,
        "trend": -1,
        "mentions": 1810,
        "avg_position": 1.9,
        "best_llm": "gpt",
        "lost_prompts": [
          {
            "prompt_id": "8a6d4f20-1b3c-4d5e-8f9a-0b1c2d3e4f50",
            "content": "Quel est le meilleur matelas pour le mal de dos ?",
            "llms": [
              "gemini"
            ]
          }
        ],
        "added_at": "2026-09-02T08:25:00.000Z"
      }
    ],
    "suggestions": [
      {
        "name": "Matelas Durand",
        "mentions": 37
      }
    ],
    "ignored": [
      {
        "name": "Ikea",
        "ignored_at": "2026-09-10T10:00:00.000Z"
      }
    ]
  }
}

Suivre un concurrent

Clé avec écriture
POST/brands/{brand_id}/competitors

Ajoute un concurrent suivi. Les variantes de nom servent à le reconnaître dans les réponses. Si le nom était écarté ou en attente, il repasse en suivi. Son score du jour est calculé dans la minute qui suit ; son historique démarre à partir de là.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).

Corps de la requête (JSON)

ChampTypeDescription
name
obligatoire
stringNom du concurrent.
100 caractères max.
websitestringSite du concurrent (trouvé automatiquement s'il est absent).
variantsarray<string>Autres écritures du nom.
50 éléments max.

Requête

curl
curl -X POST "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/competitors" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Matelas Durand",
  "website": "matelas-durand.fr",
  "variants": [
    "Durand Literie"
  ]
}'

Réponse 201

JSON
{
  "data": {
    "id": "c4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
    "brand_id": "3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90",
    "name": "Matelas Durand",
    "website": "matelas-durand.fr",
    "variants": [
      "Durand Literie"
    ],
    "status": "approved",
    "is_manual": true,
    "created_at": "2026-10-19T10:00:00.000Z"
  }
}

Lire un concurrent

GET/brands/{brand_id}/competitors/{competitor_id}

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
competitor_id
chemin, obligatoire
string (uuid)Identifiant du concurrent.

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/competitors/c4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": {
    "id": "c4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
    "brand_id": "3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90",
    "name": "Dormeo",
    "website": "dormeo.fr",
    "variants": [],
    "status": "approved",
    "is_manual": false,
    "created_at": "2026-09-02T08:25:00.000Z"
  }
}

Modifier un concurrent

Clé avec écriture
PATCH/brands/{brand_id}/competitors/{competitor_id}

Modifie les variantes de nom (la liste est remplacée) et le site du concurrent.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
competitor_id
chemin, obligatoire
string (uuid)Identifiant du concurrent.

Corps de la requête (JSON)

ChampTypeDescription
variantsarray<string>Variantes de nom (remplacent la liste actuelle).
50 éléments max.
websitestringSite du concurrent.

Requête

curl
curl -X PATCH "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/competitors/c4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "variants": [
    "Dormeo France"
  ]
}'

Réponse 200

JSON
{
  "data": {
    "id": "c4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
    "brand_id": "3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90",
    "name": "Dormeo",
    "website": "dormeo.fr",
    "variants": [
      "Dormeo France"
    ],
    "status": "approved",
    "is_manual": false,
    "created_at": "2026-09-02T08:25:00.000Z"
  }
}

Retirer un concurrent

Clé avec écriture
DELETE/brands/{brand_id}/competitors/{competitor_id}

Retire le concurrent et supprime son historique. Son nom est ajouté aux marques écartées : il ne sera plus proposé en suggestion. Pour le suivre de nouveau, utilisez POST /brands/{brand_id}/competitors.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
competitor_id
chemin, obligatoire
string (uuid)Identifiant du concurrent.

Requête

curl
curl -X DELETE "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/competitors/c4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": {
    "id": "c4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
    "deleted": true
  }
}

Évolution d'un concurrent

GET/brands/{brand_id}/competitors/{competitor_id}/visibility

Score de visibilité du concurrent jour par jour (ou par semaine, par mois), global et par IA. Même calcul que pour votre marque.

Paramètres

ParamètreTypeDescription
brand_id
chemin, obligatoire
string (uuid)Identifiant de la marque (voir GET /brands).
competitor_id
chemin, obligatoire
string (uuid)Identifiant du concurrent.
start_date
requête
string (date)Premier jour de la période (AAAA-MM-JJ, heure de Paris).
end_date
requête
string (date)Dernier jour de la période, inclus (aujourd'hui par défaut).
days
requête
integerDurée de la période en jours, 1 à 180 (30 par défaut). Sans start_date, la période finit à end_date ou aujourd'hui.
défaut : 30 · 1 à 180
llm
requête
stringIA retenues, séparées par des virgules : gpt, gemini, copilot, claude, ai-overview (et perplexity, deepseek pour l'historique). Toutes par défaut.
granularity
requête
stringRegroupement de la série : day (défaut), week (semaines commençant le lundi) ou month.
valeurs : day, week, month · défaut : day

Requête

curl
curl "https://www.geo-monitor.fr/api/v1/brands/3f2b8c1e-5d4a-4e9b-9c7d-2a1f6e8b4c90/competitors/c4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/visibility?days=90&granularity=week" \
  -H "Authorization: Bearer $GEO_MONITOR_API_KEY"

Réponse 200

JSON
{
  "data": {
    "competitor": {
      "id": "c4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
      "name": "Dormeo"
    },
    "period": {
      "start": "2026-07-22",
      "end": "2026-10-19",
      "days": 90
    },
    "granularity": "week",
    "summary": {
      "score": 50.4,
      "answers": 10560,
      "mentioned": 5322
    },
    "series": [
      {
        "date": "2026-10-13",
        "score": 51.2,
        "answers": 840,
        "mentioned": 430,
        "by_llm": {
          "gpt": {
            "score": 55.4,
            "answers": 168,
            "mentioned": 93
          }
        }
      }
    ]
  }
}

Objets

Description des principaux objets renvoyés par l'API.

Brand

Une marque suivie.

ChampTypeDescription
idstring (uuid)Identifiant.
namestringNom de la marque, utilisé pour la reconnaître dans les réponses des IA.
display_namestringNom d'affichage facultatif (rapports, dashboard).
labelstringNom à afficher : display_name s'il existe, sinon name.
sectorstringSecteur d'activité.
countrystringPays des analyses (code ISO à deux lettres).
websitestringSite de la marque.
site_domainsarray<string>Domaines reconnus comme votre site dans les sources.
productsstringProduits et services.
target_audiencestringCible.
marketing_objectivestringObjectif marketing.
name_variantsarray<string>Autres écritures du nom reconnues dans les réponses.
brand_detection_instructionsstringConsignes de détection (homonymes à exclure, par exemple).
llmsarray<string>IA analysées pour cette marque.
prompt_countintegerNombre de prompts.
created_atstring (date-heure)
updated_atstring (date-heure)

Prompt

Une question posée chaque jour aux IA.

ChampTypeDescription
idstring (uuid)
brand_idstring (uuid)
contentstringTexte du prompt.
tagsarray<string>Tags (8 au plus).
statusstringpending tant qu'aucune IA n'a encore répondu.
valeurs : pending, analyzed
is_activeboolean
created_atstring (date-heure)
updated_atstring (date-heure)
latestobjectRésumé de la dernière analyse.

Result

La dernière réponse d'une IA à un prompt.

ChampTypeDescription
idstring (uuid)
prompt_idstring (uuid)
promptstringTexte du prompt.
tagsarray<string>
llmstringIA qui a répondu.
analysis_datestring (date)Jour de la réponse.
brand_mentionedbooleanLa réponse cite la marque.
brand_positionintegerRang de la marque dans la réponse (1 = citée en premier).
sentiment_scoreintegerSentiment envers la marque, de 0 à 100.
mention_typestringFaçon d'être citée : recommandée, simplement listée, citée en passant, ou de façon négative.
valeurs : recommended, listed, incidental, negative
mention_tonestringTon de la mention.
valeurs : positive, neutral, negative
mention_confidencenumberConfiance de la classification (0 à 1).
competitorsarray<object>Concurrents cités dans la réponse.
sourcesarray<string>Domaines cités.
citationsarray<object>Pages citées.
fan_out_queriesarray<string>Recherches web lancées par l'IA pour répondre.
rich_contentobjectContenus affichés avec la réponse : products, shopping, map, business_locations, ads, images, videos. Format brut, variable selon l'IA.
contentstringTexte complet de la réponse (absent avec include_content=false).

Error

Format de toutes les erreurs.

ChampTypeDescription
errorobject

Versions

  • 1.0.0, 19 octobre 2026 : première version publique. Lecture de toutes les données des marques et de leur évolution, gestion des marques, prompts, tags et concurrents.

Une question, un besoin non couvert ? Écrivez-nous