Obtenir la GEO Matrix

curl --request GET \
  --url https://www.qwairy.co/api/v1/brands/{brandId}/matrix \
  --header 'Authorization: <authorization>'

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://www.qwairy.co/api/v1/brands/{brandId}/matrix', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "brand": {
    "id": "<string>",
    "name": "<string>"
  },
  "granularity": "<string>",
  "providers": [
    {
      "id": "<string>",
      "name": "<string>"
    }
  ],
  "rows": [
    {
      "id": "<string>",
      "name": "<string>",
      "promptCount": 123,
      "mentionRate": 123,
      "coverage": {
        "count": 123,
        "total": 123,
        "percentage": 123
      },
      "overall": {},
      "cells": [
        {
          "provider": "<string>",
          "score": 123,
          "subScores": {
            "mentionRate": 123,
            "shareOfVoice": 123,
            "citationRate": 123,
            "sentiment": {}
          },
          "ranking": {
            "mentionRate": {},
            "shareOfVoice": {},
            "citationRate": {},
            "sentiment": {}
          },
          "citations": 123,
          "position": 123,
          "topCompetitor": "<string>",
          "topCompetitors": [
            {}
          ],
          "topSources": [
            {}
          ]
        }
      ]
    }
  ],
  "providerAverages": [
    {
      "provider": "<string>",
      "score": 123,
      "mentionRate": 123,
      "shareOfVoice": 123,
      "citationRate": 123,
      "sentiment": {}
    }
  ],
  "summary": {
    "totalRows": 123,
    "averageMentionRate": 123,
    "topPerforming": {},
    "needsAttention": {}
  }
}

GET

https://www.qwairy.co

api

brands

{brandId}

matrix

Obtenir la GEO Matrix

curl --request GET \
  --url https://www.qwairy.co/api/v1/brands/{brandId}/matrix \
  --header 'Authorization: <authorization>'

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://www.qwairy.co/api/v1/brands/{brandId}/matrix', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "brand": {
    "id": "<string>",
    "name": "<string>"
  },
  "granularity": "<string>",
  "providers": [
    {
      "id": "<string>",
      "name": "<string>"
    }
  ],
  "rows": [
    {
      "id": "<string>",
      "name": "<string>",
      "promptCount": 123,
      "mentionRate": 123,
      "coverage": {
        "count": 123,
        "total": 123,
        "percentage": 123
      },
      "overall": {},
      "cells": [
        {
          "provider": "<string>",
          "score": 123,
          "subScores": {
            "mentionRate": 123,
            "shareOfVoice": 123,
            "citationRate": 123,
            "sentiment": {}
          },
          "ranking": {
            "mentionRate": {},
            "shareOfVoice": {},
            "citationRate": {},
            "sentiment": {}
          },
          "citations": 123,
          "position": 123,
          "topCompetitor": "<string>",
          "topCompetitors": [
            {}
          ],
          "topSources": [
            {}
          ]
        }
      ]
    }
  ],
  "providerAverages": [
    {
      "provider": "<string>",
      "score": 123,
      "mentionRate": 123,
      "shareOfVoice": 123,
      "citationRate": 123,
      "sentiment": {}
    }
  ],
  "summary": {
    "totalRows": 123,
    "averageMentionRate": 123,
    "topPerforming": {},
    "needsAttention": {}
  }
}

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.

Cet endpoint renvoie un tableau croisé de la visibilité de votre marque. Consultez Performance pour les indicateurs agrégés et Competitor pour les structures utilisées dans topCompetitors.

string

requis

Jeton bearer. Exemple : Bearer qw-api-xxx

GET /api/v1/brands/{brandId}/matrix

Paramètres de chemin

string

requis

L’identifiant unique de la marque

Paramètres de requête

string

Regroupement des lignes : topics (par défaut), tags, prompts ou funnel

number

Nombre de jours à inclure. Par défaut : 30

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.

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.

string

Filtre par fournisseur IA. Accepte plusieurs valeurs séparées par des virgules (par exemple chatgpt,claude).

string

Filtre par identifiant de Topic (keywordId). Accepte plusieurs valeurs séparées par des virgules (par exemple id1,id2).

string

Filtre par identifiant de Tag. Accepte plusieurs valeurs séparées par des virgules (par exemple id1,id2).

string

défaut:"or"

Combine plusieurs identifiants de Tags par or ou and. Les lignes par Tag utilisent toujours OU.

string

Filtre par étape du tunnel : TOFU, MOFU, BOFU ou POST_PURCHASE. Accepte plusieurs valeurs séparées par des virgules.

string

UUID d’un domaine concurrent SELF actif, pour limiter la matrice à une concession ou une sous-marque.

number

Nombre maximal de lignes renvoyées. Par défaut : 50, maximum : 100

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

boolean

Indique si la requête a réussi

object

Afficher Informations de la marque

string

Identifiant de la marque

string

Nom de la marque

string

La granularité utilisée pour cette matrice (topics, tags, prompts ou funnel)

array

Liste des fournisseurs IA utilisés comme colonnes. Chaque entrée est un objet avec un id et un name.

Afficher Objet fournisseur

string

Identifiant du fournisseur (par exemple chatgpt, perplexity, claude)

string

Nom affiché du fournisseur

array

Lignes de la matrice, une par Topic, Tag, prompt ou étape du tunnel

Afficher Structure d’une ligne

string

Identifiant de la ligne (identifiant de Topic, de Tag, de prompt ou étape du tunnel)

string

Nom affiché de la ligne

number

Nombre de prompts distincts dans cette ligne

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

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.

Afficher Objet coverage

number

Cellules de fournisseurs avec un taux de mention ou de citation SELF non nul

number

Colonnes de fournisseurs de la matrice sélectionnée

number

count / total × 100, arrondi à l’entier

object

score, subScores, answerCount et ranking de la marque, regroupés sur tous les fournisseurs sélectionnés de la ligne

array

Une cellule par fournisseur

Afficher Structure d’une cellule

string

Identifiant du fournisseur

number

Score GEO composite (0 à 100)

object

Afficher Détail des sous-scores

number

Taux de mention de la marque (%)

Part de voix (%)

number

Taux de citation comme source (%)

number | null

Sentiment moyen des mentions SELF sur une échelle de 0 à 100, ou null

object

Afficher Classement par indicateur

object

Rang et total (par exemple {"rank": 2, "total": 8})

Rang et total

object

Rang et total

object

Rang et total

number

Occurrences de citations de sources SELF dans la cellule

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)

string

Nom du concurrent en tête dans cette cellule (null s’il n’y en a pas)

array

Principaux concurrents de cette cellule, chacun avec name, mentions, avgPosition et relationship

array

Sources les plus citées dans cette cellule

array

Indicateurs moyens par fournisseur sur l’ensemble des lignes renvoyées.

Afficher Objet de moyenne par fournisseur

string

Identifiant du fournisseur

number

Score GEO composite moyen pour ce fournisseur (0 à 100)

number

Taux de mention moyen pour ce fournisseur (%)

Part de voix moyenne pour ce fournisseur (%)

number

Taux de citation moyen pour ce fournisseur (%)

number | null

Moyenne non pondérée des valeurs de sentiment non nulles des lignes pour ce fournisseur, arrondie à l’entier

object

Afficher Statistiques de synthèse

number

Nombre total de lignes

number

Moyenne des taux de mention non nuls des lignes, arrondie à l’entier

object

Ligne au taux de mention le plus élevé, ou null. Forme : { rowId, rowName, mentionRate }.

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.

Exemple de requête

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

{
  "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 pour la gestion des nouvelles tentatives.

Bien démarrer

Configurer les données

Suivi et mesure

Analyse et action

Agence et automatisation

Guides d’implémentation

Obtenir la GEO Matrix

Paramètres de chemin

Paramètres de requête

Options de granularité

Réponse

Exemple de requête

Exemple de réponse

Erreurs

​Paramètres de chemin

​Paramètres de requête

​Options de granularité

​Réponse

​Exemple de requête

​Exemple de réponse

​Erreurs

Paramètres de chemin

Paramètres de requête

Options de granularité

Réponse

Exemple de requête

Exemple de réponse

Erreurs