> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Obtenir la GEO Matrix

> Obtenez la matrice de visibilité GEO de votre marque par fournisseur et par dimension.

Renvoie des lignes regroupées par Topic, Tag, prompt ou étape du tunnel, et des colonnes regroupées par fournisseur. Chaque cellule contient le score actuel de la matrice pour son périmètre de réponses.

<Note>
  Cet endpoint renvoie un tableau croisé de la visibilité de votre marque. Consultez [Performance](/fr/developers/endpoints/performance) pour les indicateurs agrégés et [Competitor](/fr/developers/entities#competitor) pour les structures utilisées dans `topCompetitors`.
</Note>

<ParamField header="Authorization" type="string" required>
  Jeton bearer. Exemple : `Bearer qw-api-xxx`
</ParamField>

```http theme={null}
GET /api/v1/brands/{brandId}/matrix
```

## Paramètres de chemin

<ParamField path="brandId" type="string" required>
  L’identifiant unique de la marque
</ParamField>

## Paramètres de requête

<ParamField query="granularity" type="string">
  Regroupement des lignes : `topics` (par défaut), `tags`, `prompts` ou `funnel`
</ParamField>

<ParamField query="period" type="number">
  Nombre de jours à inclure. Par défaut : 30
</ParamField>

<ParamField query="startDate" type="string">
  Date de début au format `YYYY-MM-DD`. Fournissez-la avec `endDate` ; une borne seule est actuellement ignorée. Choisissez soit `period`, soit la paire de dates complète.
</ParamField>

<ParamField query="endDate" type="string">
  Date de fin au format `YYYY-MM-DD`. Fournissez-la avec `startDate` ; une borne seule est actuellement ignorée. Ne combinez pas la paire de dates complète avec `period`.
</ParamField>

<ParamField query="provider" type="string">
  Filtre par fournisseur IA. Accepte plusieurs valeurs séparées par des virgules (par exemple `chatgpt,claude`).
</ParamField>

<ParamField query="topic" type="string">
  Filtre par identifiant de Topic (keywordId). Accepte plusieurs valeurs séparées par des virgules (par exemple `id1,id2`).
</ParamField>

<ParamField query="tag" type="string">
  Filtre par identifiant de Tag. Accepte plusieurs valeurs séparées par des virgules (par exemple `id1,id2`).
</ParamField>

<ParamField query="tagOperator" type="string" default="or">
  Combine plusieurs identifiants de Tags par `or` ou `and`. Les lignes par Tag utilisent toujours OU.
</ParamField>

<ParamField query="funnel" type="string">
  Filtre par étape du tunnel : `TOFU`, `MOFU`, `BOFU` ou `POST_PURCHASE`. Accepte plusieurs valeurs séparées par des virgules.
</ParamField>

<ParamField query="competitorDomainId" type="string">
  UUID d’un domaine concurrent SELF actif, pour limiter la matrice à une concession ou une sous-marque.
</ParamField>

<ParamField query="limit" type="number">
  Nombre maximal de lignes renvoyées. Par défaut : 50, maximum : 100
</ParamField>

### Options de granularité

| Valeur | Regroupe les lignes par |
| - | - |
| `topics` | Mots-clés et Topics (par défaut) |
| `tags` | Tags appliqués aux prompts |
| `prompts` | Questions suivies une par une |
| `funnel` | Étapes du tunnel (TOFU/MOFU/BOFU/POST\_PURCHASE) |

## Réponse

<ResponseField name="success" type="boolean">
  Indique si la requête a réussi
</ResponseField>

<ResponseField name="brand" type="object">
  <Expandable title="Informations de la marque">
    <ResponseField name="id" type="string">Identifiant de la marque</ResponseField>
    <ResponseField name="name" type="string">Nom de la marque</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="granularity" type="string">
  La granularité utilisée pour cette matrice (`topics`, `tags`, `prompts` ou `funnel`)
</ResponseField>

<ResponseField name="providers" type="array">
  Liste des fournisseurs IA utilisés comme colonnes. Chaque entrée est un objet avec un `id` et un `name`.

  <Expandable title="Objet fournisseur">
    <ResponseField name="id" type="string">Identifiant du fournisseur (par exemple `chatgpt`, `perplexity`, `claude`)</ResponseField>
    <ResponseField name="name" type="string">Nom affiché du fournisseur</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="rows" type="array">
  Lignes de la matrice, une par Topic, Tag, prompt ou étape du tunnel

  <Expandable title="Structure d’une ligne">
    <ResponseField name="id" type="string">Identifiant de la ligne (identifiant de Topic, de Tag, de prompt ou étape du tunnel)</ResponseField>
    <ResponseField name="name" type="string">Nom affiché de la ligne</ResponseField>
    <ResponseField name="promptCount" type="number">Nombre de prompts distincts dans cette ligne</ResponseField>
    <ResponseField name="mentionRate" type="number">Taux de mention global de la ligne : réponses avec une mention SELF divisées par les réponses avec une mention SELF ou DIRECT</ResponseField>

    <ResponseField name="coverage" type="object">
      Couverture des colonnes de fournisseurs pour cette ligne. Un fournisseur compte lorsque sa cellule a un taux de mention SELF ou un taux de citation SELF non nul. Ce n’est pas la couverture au niveau des réponses ni des prompts.

      <Expandable title="Objet coverage">
        <ResponseField name="count" type="number">Cellules de fournisseurs avec un taux de mention ou de citation SELF non nul</ResponseField>
        <ResponseField name="total" type="number">Colonnes de fournisseurs de la matrice sélectionnée</ResponseField>
        <ResponseField name="percentage" type="number">`count / total × 100`, arrondi à l’entier</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="overall" type="object">
      `score`, `subScores`, `answerCount` et `ranking` de la marque, regroupés sur tous les fournisseurs sélectionnés de la ligne
    </ResponseField>

    <ResponseField name="cells" type="array">
      Une cellule par fournisseur

      <Expandable title="Structure d’une cellule">
        <ResponseField name="provider" type="string">Identifiant du fournisseur</ResponseField>
        <ResponseField name="score" type="number">Score GEO composite (0 à 100)</ResponseField>

        <ResponseField name="subScores" type="object">
          <Expandable title="Détail des sous-scores">
            <ResponseField name="mentionRate" type="number">Taux de mention de la marque (%)</ResponseField>
            <ResponseField name="shareOfVoice" type="number">Part de voix (%)</ResponseField>
            <ResponseField name="citationRate" type="number">Taux de citation comme source (%)</ResponseField>
            <ResponseField name="sentiment" type="number | null">Sentiment moyen des mentions SELF sur une échelle de 0 à 100, ou `null`</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="ranking" type="object">
          <Expandable title="Classement par indicateur">
            <ResponseField name="mentionRate" type="object">Rang et total (par exemple `{"rank": 2, "total": 8}`)</ResponseField>
            <ResponseField name="shareOfVoice" type="object">Rang et total</ResponseField>
            <ResponseField name="citationRate" type="object">Rang et total</ResponseField>
            <ResponseField name="sentiment" type="object">Rang et total</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="citations" type="number">Occurrences de citations de sources SELF dans la cellule</ResponseField>
        <ResponseField name="position" type="number">Meilleure position (minimale) atteinte par votre marque dans les réponses de cette cellule (plus c’est bas, mieux c’est ; `null` si elle n’est pas mentionnée)</ResponseField>
        <ResponseField name="topCompetitor" type="string">Nom du concurrent en tête dans cette cellule (`null` s’il n’y en a pas)</ResponseField>
        <ResponseField name="topCompetitors" type="array">Principaux concurrents de cette cellule, chacun avec `name`, `mentions`, `avgPosition` et `relationship`</ResponseField>
        <ResponseField name="topSources" type="array">Sources les plus citées dans cette cellule</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="providerAverages" type="array">
  Indicateurs moyens par fournisseur sur l’ensemble des lignes renvoyées.

  <Expandable title="Objet de moyenne par fournisseur">
    <ResponseField name="provider" type="string">Identifiant du fournisseur</ResponseField>
    <ResponseField name="score" type="number">Score GEO composite moyen pour ce fournisseur (0 à 100)</ResponseField>
    <ResponseField name="mentionRate" type="number">Taux de mention moyen pour ce fournisseur (%)</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Part de voix moyenne pour ce fournisseur (%)</ResponseField>
    <ResponseField name="citationRate" type="number">Taux de citation moyen pour ce fournisseur (%)</ResponseField>
    <ResponseField name="sentiment" type="number | null">Moyenne non pondérée des valeurs de sentiment non nulles des lignes pour ce fournisseur, arrondie à l’entier</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="summary" type="object">
  <Expandable title="Statistiques de synthèse">
    <ResponseField name="totalRows" type="number">Nombre total de lignes</ResponseField>
    <ResponseField name="averageMentionRate" type="number">Moyenne des taux de mention non nuls des lignes, arrondie à l’entier</ResponseField>
    <ResponseField name="topPerforming" type="object">Ligne au taux de mention le plus élevé, ou `null`. Forme : `{ rowId, rowName, mentionRate }`.</ResponseField>
    <ResponseField name="needsAttention" type="object">Champ de synthèse de l’API contenant la ligne non nulle la plus basse sous le seuil intégré de 50 %, ou `null`. Ce seuil n’est pas une référence propre à votre compte.</ResponseField>
  </Expandable>
</ResponseField>

## Exemple de requête

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/matrix?granularity=topics&period=30&limit=10" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Exemple de réponse

```json theme={null}
{
  "success": true,
  "brand": {
    "id": "brand_01",
    "name": "Acme Analytics"
  },
  "granularity": "topics",
  "providers": [
    { "id": "openai", "name": "ChatGPT" },
    { "id": "perplexity", "name": "Perplexity" },
    { "id": "anthropic", "name": "Claude" }
  ],
  "rows": [
    {
      "id": "topic_01",
      "name": "Data exports",
      "promptCount": 12,
      "mentionRate": 52.4,
      "coverage": { "count": 3, "total": 3, "percentage": 100 },
      "overall": {
        "score": 60,
        "subScores": {
          "mentionRate": 52.4,
          "shareOfVoice": 13.5,
          "citationRate": 29.1,
          "sentiment": 76.3
        },
        "answerCount": 60,
        "ranking": {
          "mentionRate": { "rank": 2, "total": 8 },
          "shareOfVoice": { "rank": 3, "total": 8 },
          "citationRate": { "rank": 2, "total": 8 },
          "sentiment": { "rank": 1, "total": 8 },
          "score": { "rank": 2, "total": 8 }
        }
      },
      "cells": [
        {
          "provider": "openai",
          "score": 72,
          "subScores": {
            "mentionRate": 65.0,
            "shareOfVoice": 18.5,
            "citationRate": 30.2,
            "sentiment": 81.0
          },
          "ranking": {
            "mentionRate": { "rank": 2, "total": 8 },
            "shareOfVoice": { "rank": 3, "total": 8 },
            "citationRate": { "rank": 1, "total": 8 },
            "sentiment": { "rank": 1, "total": 8 }
          },
          "citations": 12,
          "position": 2,
          "topCompetitor": "Rival Labs",
          "topCompetitors": [
            { "name": "Rival Labs", "mentions": 9, "avgPosition": 2, "relationship": "DIRECT" },
            { "name": "Northstar Data", "mentions": 6, "avgPosition": 3, "relationship": "DIRECT" }
          ],
          "topSources": [
            { "domain": "publisher.example", "citations": 8 }
          ]
        },
        {
          "provider": "perplexity",
          "score": 58,
          "subScores": {
            "mentionRate": 50.0,
            "shareOfVoice": 12.3,
            "citationRate": 42.1,
            "sentiment": 76.0
          },
          "ranking": {
            "mentionRate": { "rank": 3, "total": 7 },
            "shareOfVoice": { "rank": 4, "total": 7 },
            "citationRate": { "rank": 2, "total": 7 },
            "sentiment": { "rank": 2, "total": 7 }
          },
          "citations": 18,
          "position": 3,
          "topCompetitor": "Northstar Data",
          "topCompetitors": [
            { "name": "Northstar Data", "mentions": 11, "avgPosition": 2, "relationship": "DIRECT" },
            { "name": "Rival Labs", "mentions": 7, "avgPosition": 4, "relationship": "DIRECT" }
          ],
          "topSources": [
            { "domain": "reviews.example", "citations": 14 }
          ]
        },
        {
          "provider": "anthropic",
          "score": 45,
          "subScores": {
            "mentionRate": 35.0,
            "shareOfVoice": 9.8,
            "citationRate": 15.0,
            "sentiment": 72.0
          },
          "ranking": {
            "mentionRate": { "rank": 5, "total": 6 },
            "shareOfVoice": { "rank": 4, "total": 6 },
            "citationRate": { "rank": 3, "total": 6 },
            "sentiment": { "rank": 3, "total": 6 }
          },
          "citations": 4,
          "position": 4,
          "topCompetitor": "Rival Labs",
          "topCompetitors": [
            { "name": "Rival Labs", "mentions": 5, "avgPosition": 3, "relationship": "DIRECT" }
          ],
          "topSources": [
            { "domain": "acme.example", "citations": 3 }
          ]
        }
      ]
    }
  ],
  "providerAverages": [
    { "provider": "openai", "score": 72, "mentionRate": 65.0, "shareOfVoice": 18.5, "citationRate": 30.2, "sentiment": 81.0 },
    { "provider": "perplexity", "score": 58, "mentionRate": 50.0, "shareOfVoice": 12.3, "citationRate": 42.1, "sentiment": 76.0 },
    { "provider": "anthropic", "score": 45, "mentionRate": 35.0, "shareOfVoice": 9.8, "citationRate": 15.0, "sentiment": 72.0 }
  ],
  "summary": {
    "totalRows": 12,
    "averageMentionRate": 50,
    "topPerforming": {
      "rowId": "topic_01",
      "rowName": "Data exports",
      "mentionRate": 52.4
    },
    "needsAttention": {
      "rowId": "topic7",
      "rowName": "Pricing",
      "mentionRate": 31.0
    }
  }
}
```

## Erreurs

| Statut | Code | Description |
| - | - | - |
| 400 | `INVALID_PARAMETER` | Paramètre de requête invalide (par exemple une granularité inconnue) |
| 401 | erreur de passerelle | Jeton d’API manquant ou invalide |
| 404 | `BRAND_NOT_FOUND` | Marque inexistante ou inaccessible |
| 429 | erreur de passerelle | Limite de débit dépassée ; respectez `Retry-After` |

Consultez [Limites de débit](/fr/developers/rate-limits) pour la gestion des nouvelles tentatives.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.