Search Analytics: query

Nécessite une autorisation

Interrogez les données sur le trafic issu de la recherche à l'aide de filtres et de paramètres que vous définissez. La méthode renvoie zéro ou plusieurs lignes regroupées par les clés de ligne (dimensions) que vous définissez. Vous devez définir une plage de dates d'un ou de plusieurs jours.

Lorsque la date est l'une des dimensions, les jours sans données sont omis de la liste des résultats. Pour savoir quels jours contiennent des données, exécutez une requête sans filtres avec critère de regroupement par date, pour la plage de dates qui vous intéresse.

Les résultats sont triés par nombre de clics décroissant. Si deux lignes ont le même nombre de clics, elles sont triées de manière arbitraire.

Consultez l'exemple Python pour appeler cette méthode.

L'API est soumise aux limites internes de la Search Console et ne garantit pas de renvoyer toutes les lignes de données, mais plutôt les principales.

En savoir plus sur les limites de la quantité de données disponibles

Exemple de requête POST JSON :
POST https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fwww.example.com%2F/searchAnalytics/query?key={MY_API_KEY}
{
  "startDate": "2015-04-01",
  "endDate": "2015-05-01",
  "dimensions": ["country","device"]
}
Essayer maintenant

Requête

Requête HTTP

POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query

Paramètres

Nom du paramètre Valeur Description
Paramètres de chemin d'accès
siteUrl string URL de la propriété telle qu'elle est définie dans la Search Console. Exemples : http://www.example.com/ (pour une propriété de préfixe d'URL) ou sc-domain:example.com (pour une propriété de domaine)

Autorisation

Une autorisation est requise pour cette requête. Celle-ci doit inclure au moins l'un des champs d'application suivants. En savoir plus sur le processus d'authentification et d'autorisation

Champ d'application
https://www.googleapis.com/auth/webmasters.readonly
https://www.googleapis.com/auth/webmasters

Corps de la requête

Dans le corps de la requête, fournissez des données avec la structure suivante :

{
  "startDate": string,
  "endDate": string,
  "dimensions": [
    string
  ],
  "type": string,
  "dimensionFilterGroups": [
    {
      "groupType": string,
      "filters": [
        {
          "dimension": string,
          "operator": string,
          "expression": string
        }
      ],
      "filterLists": [
        {
          "dimension": string,
          "expressions": [
            string
          ]
        }
      ]
    }
  ],
  "aggregationType": string,
  "rowLimit": integer,
  "startRow": integer
}
Nom de propriété Valeur Description Remarques
startDate string [Obligatoire] Date de début de la plage de dates demandée, au format AAAA-MM-JJ, à l'heure du Pacifique (UTC - 7:00/8:00). La valeur doit être inférieure ou égale à la date de fin. Cette valeur est incluse dans la plage.
endDate string [Obligatoire] Date de fin de la plage de dates demandée, au format AAAA-MM-JJ, à l'heure du Pacifique (UTC - 7:00/8:00). La date de fin doit être postérieure ou égale à la date de début. Cette valeur est incluse dans la plage.
dimensions[] list [Facultatif] Zéro ou plusieurs dimensions pour regrouper les résultats. Les résultats sont regroupés dans l'ordre dans lequel vous fournissez ces dimensions. Vous pouvez utiliser n'importe quel nom de dimension dans dimensionFilterGroups[].filters[].dimension, ainsi que "date" et "hour". Les valeurs de la dimension de regroupement sont combinées pour créer une clé unique pour chaque ligne de résultat. Si aucune dimension n'est spécifiée, toutes les valeurs seront combinées en une seule ligne. Le nombre de dimensions que vous pouvez utiliser comme critère de regroupement n'est pas limité, mais vous ne pouvez pas utiliser la même dimension deux fois comme critère de regroupement. Exemple : [country, device]
searchType string Obsolète, utilisez plutôt type
type string [Facultatif] Filtrer les résultats selon le type suivant :
  • "discover" : résultats Discover
  • "googleNews" : résultats de news.google.com et de l'application Google Actualités sur Android et iOS. N'inclut pas les résultats de l'onglet "Actualités" de la recherche Google.
  • "news" : résultats de recherche de l'onglet "Actualités" de la recherche Google.
  • "image" : résultats de recherche de l'onglet "Image" de la recherche Google.
  • "video" : résultats de recherche de vidéos
  • "web" : [par défaut] filtre les résultats de l'onglet combiné ("Tous") de la recherche Google. N'inclut pas les résultats Discover ni Google Actualités.
  • "webMultimodal" : résultats de recherche de Google Lens, d'Entourer pour chercher sur Android et des images importées dans la recherche Google.
dimensionFilterGroups[] list [Facultatif] Zéro ou plusieurs groupes de filtres à appliquer aux valeurs de regroupement des dimensions. Tous les groupes de filtres doivent correspondre pour qu'une ligne soit renvoyée dans la réponse. Dans un même groupe de filtres, vous pouvez spécifier si tous les filtres doivent correspondre ou si au moins un doit correspondre.
dimensionFilterGroups[].groupType string Indique si tous les filtres de ce groupe doivent renvoyer la valeur "true" ("and") ou si un ou plusieurs d'entre eux doivent renvoyer la valeur "true" (pas encore pris en charge).

Les valeurs acceptées sont les suivantes :
  • "and" : tous les filtres du groupe doivent renvoyer la valeur "true" pour que le groupe de filtres soit défini sur "true".
dimensionFilterGroups[].filters[] list [Facultatif] Zéro ou plusieurs filtres à tester sur la ligne. Chaque filtre se compose d'un nom de dimension, d'un opérateur et d'une valeur. Longueur maximale : 4 096 caractères. Exemples :
country equals FRA
query contains mobile use
device notContains tablet
dimensionFilterGroups[].filters[].dimension string Dimension à laquelle ce filtre s'applique. Vous pouvez filtrer les données en fonction de n'importe quelle dimension listée ici, même si vous n'utilisez pas cette dimension comme critère de regroupement.

Les valeurs acceptées sont les suivantes :
  • "country" : filtre en fonction du pays spécifié, indiqué par un code pays à trois lettres (ISO 3166-1 alpha-3).
  • "device" : filtre les résultats en fonction du type d'appareil spécifié. Valeurs acceptées :
    • ORDINATEUR
    • MOBILE
    • TABLETTE
  • "page" : filtre en fonction de la chaîne d'URI spécifiée.
  • "query" : filtre en fonction de la chaîne de requête spécifiée.
  • "searchAppearance" : filtrez les résultats en fonction d'une option d'affichage spécifique dans les résultats de recherche. Pour afficher la liste des valeurs disponibles, exécutez une requête avec le critère de regroupement "searchAppearance". La liste complète des valeurs et des descriptions est également disponible dans la documentation d'aide.
  • "brandedClassification" : filtre les résultats en fonction de la classification de requête incluant une marque spécifiée (seul l'opérateur "equals" est accepté). Le filtrage ou le regroupement par "brandedClassification" ne peut pas être combiné avec un filtre "query" dans la même requête. Les données sont disponibles à partir du 21 février 2026, et uniquement pour les propriétés de premier niveau dont le volume de requêtes et d'impressions est suffisant (voir l'annonce sur les requêtes incluant une marque). Valeurs acceptées :
    • BRANDED
    • NON_BRANDED
dimensionFilterGroups[].filters[].operator string [Facultatif] Indique comment la valeur que vous avez spécifiée doit correspondre (ou non) à la valeur de dimension de la ligne.

Les valeurs acceptées sont les suivantes :
  • "contains" : la valeur de la ligne doit contenir votre expression ou lui être égale (sans tenir compte de la casse).
  • "equals" : [Par défaut] Votre expression doit correspondre exactement à la valeur de la ligne (sensible à la casse pour les dimensions de page et de requête).
  • "notContains" : la valeur de la ligne ne doit pas contenir votre expression en tant que sous-chaîne ou correspondance complète (non sensible à la casse).
  • "notEquals" : votre expression ne doit pas être exactement égale à la valeur de la ligne (sensible à la casse pour les dimensions de page et de requête).
  • "includingRegex" : expression régulière de syntaxe RE2 qui doit être mise en correspondance.
  • "excludingRegex" : expression régulière de syntaxe RE2 qui ne doit pas correspondre.
dimensionFilterGroups[].filters[].expression string Valeur que le filtre doit faire correspondre ou exclure, selon l'opérateur.
dimensionFilterGroups[].filterLists[] list [Facultatif] Zéro ou plusieurs filtres de dimension à valeurs multiples à tester par rapport à la ligne. Contrairement à filters[], qui correspond à une seule valeur par entrée, filterLists[] permet de faire correspondre plusieurs valeurs exactes pour une seule dimension dans un filtre. Une ligne correspond à une liste de filtres si sa valeur pour le dimension spécifié est égale à l'un des expressions fournis. Notez qu'une même requête ne peut pas filtrer sur la même dimension à la fois dans filters et filterLists.
dimensionFilterGroups[].filterLists[].dimension string [Obligatoire] Dimension à laquelle cette liste de filtres s'applique.

Les valeurs acceptées sont les suivantes :
  • "country" : filtre les pays spécifiés à l'aide de codes pays à trois lettres (ISO 3166-1 alpha-3).
  • "device" : filtre les types d'appareils spécifiés (DESKTOP, MOBILE, TABLET).
dimensionFilterGroups[].filterLists[].expressions[] list [Obligatoire] Liste des valeurs (string) à filtrer.
aggregationType string

[Facultatif] Mode d'agrégation des données. Si l'agrégation est effectuée par propriété, toutes les données de la même propriété sont agrégées. Si l'agrégation est effectuée par page, toutes les données sont agrégées par URI canonique. Si vous filtrez ou regroupez par page, choisissez "auto". Sinon, vous pouvez agréger par propriété ou par page, selon la façon dont vous souhaitez que vos données soient calculées. Consultez la documentation d'aide pour découvrir comment les données sont calculées différemment par site et par page.

Remarque : Si vous regroupez ou filtrez par page, vous ne pouvez pas agréger par propriété.

Si vous spécifiez une valeur autre que "auto", le type d'agrégation dans le résultat correspondra au type demandé. Si vous demandez un type non valide, vous obtiendrez une erreur. L'API ne modifiera jamais votre type d'agrégation si le type demandé n'est pas valide.

Voici les valeurs acceptées :
  • "auto" : [Par défaut] Laissez le service décider du type d'agrégation approprié.
  • "byNewsShowcasePanel" : regroupe les valeurs par panneau News Showcase. Il doit être utilisé en combinaison avec le filtre NEWS_SHOWCASE searchAppearance et type=discover ou type=googleNews. Si vous regroupez par page, filtrez par page ou filtrez par un autre searchAppearance, vous ne pouvez pas agréger par byNewsShowcasePanel.
  • "byPage" : regroupe les valeurs par URI.
  • "byProperty" : agrège les valeurs par propriété. Non disponible pour type=discover ou type=googleNews
rowLimit integer [Facultatif ; plage valide : 1 à 25 000 ; valeur par défaut : 1 000] Nombre maximal de lignes à renvoyer. Pour parcourir les résultats, utilisez le décalage startRow.
startRow integer [Facultatif ; la valeur par défaut est 0] Index de base zéro de la première ligne de la réponse. Spécifiez un nombre non négatif. Si startRow dépasse le nombre de résultats de la requête, la réponse sera une réponse réussie avec zéro ligne.
dataState string [Facultatif] Si la valeur est "all" (non sensible à la casse), les données incluront des données récentes. Si la valeur est "final" (non sensible à la casse) ou si ce paramètre est omis, les données renvoyées n'incluront que les données finalisées. Si la valeur est "hourly_all" (non sensible à la casse), les données incluront une répartition horaire. Cela indique que les données horaires incluent des données partielles et doivent être utilisées lors du regroupement par la dimension d'API HOUR.

Réponse

Les résultats sont regroupés en fonction des dimensions spécifiées dans la requête. Toutes les valeurs associées au même ensemble de valeurs de dimension seront regroupées sur une seule ligne. Par exemple, si vous regroupez les résultats par dimension "Pays", tous les résultats pour "usa" seront regroupés, tous les résultats pour "mdv" seront regroupés, etc. Si vous avez regroupé les données par pays et par appareil, tous les résultats pour "États-Unis, tablette" seront regroupés, tous les résultats pour "États-Unis, mobile" seront regroupés, et ainsi de suite. Consultez la documentation sur le rapport Analyse de la recherche pour en savoir plus sur le calcul des clics, des impressions, etc., et sur leur signification.

Les résultats sont triés par nombre de clics, par ordre décroissant, sauf si vous les regroupez par date. Dans ce cas, ils sont triés par date, par ordre croissant (du plus ancien au plus récent). Si deux lignes sont ex æquo, l'ordre de tri est arbitraire.

Consultez la propriété rowLimit dans la requête pour connaître le nombre maximal de valeurs pouvant être renvoyées.

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}
Nom de propriété Valeur Description Remarques
rows[] list Liste de lignes regroupées par valeurs de clé dans l'ordre indiqué dans la requête.
rows[].keys[] list Liste des valeurs de dimension pour cette ligne, regroupées selon les dimensions de la requête, dans l'ordre spécifié dans la requête.
rows[].clicks double Nombre de clics pour la ligne.
rows[].impressions double Nombre d'impressions pour la ligne.
rows[].ctr double Taux de clics (CTR) pour la ligne. Les valeurs sont comprises entre 0 et 1, 0 (inclus).
rows[].position double Position moyenne dans les résultats de recherche.
responseAggregationType string Comment les résultats ont été agrégés. Consultez la documentation d'aide pour découvrir comment les données sont calculées différemment par site ou par page.

Les valeurs acceptées sont les suivantes :
  • "auto"
  • "byPage" : les résultats ont été regroupés par page.
  • "byProperty" : les résultats ont été agrégés par propriété.
metadata object

Objet pouvant être renvoyé avec les résultats de votre requête, fournissant un contexte sur l'état des données.

Lorsque vous demandez des données récentes (en utilisant all ou hourly_all pour dataState), certaines des lignes renvoyées peuvent représenter des données incomplètes, ce qui signifie que les données sont toujours en cours de collecte et de traitement. Cet objet de métadonnées vous aide à identifier précisément quand elle commence et se termine.

Toutes les dates et heures fournies dans cet objet sont exprimées dans le fuseau horaire America/Los_Angeles.

Le champ spécifique renvoyé dans cet objet dépend de la façon dont vous avez regroupé vos données dans la requête :

  • first_incomplete_date (string) : première date pour laquelle les données sont encore collectées et traitées, au format YYYY-MM-DD (format de date locale étendu ISO-8601).

    Ce champ n'est renseigné que lorsque le champ dataState de la requête est défini sur all, que les données sont regroupées par date et que la plage de dates demandée contient des points de données incomplets.

    Toutes les valeurs après le first_incomplete_date peuvent encore changer de manière notable.

  • first_incomplete_hour (string) : première heure pour laquelle les données sont encore collectées et traitées, présentée au format YYYY-MM-DDThh:mm:ss[+|-]hh:mm (format de date/heure avec décalage étendu ISO-8601).

    Ce champ n'est renseigné que lorsque le champ dataState de la requête est défini sur hourly_all, que les données sont regroupées par hour et que la plage de dates demandée contient des points de données incomplets.

    Toutes les valeurs après le first_incomplete_hour peuvent encore changer de manière notable.

Essayer

Utilisez l'explorateur d'API ci-dessous pour appeler cette méthode sur des données en direct, puis observez la réponse.