Cette page a été traduite par l'API Cloud Translation.

Search Analytics: query

Interrogez vos données de trafic de recherche à l'aide des filtres et des paramètres que vous définissez. Cette méthode renvoie zéro ou plusieurs lignes regroupées en fonction des clés de ligne (dimensions) que vous définissez. Vous devez définir une plage de dates d'un ou plusieurs jours.

Lorsque la date fait partie des dimensions, les jours sans données sont omis de la liste des résultats. Pour savoir quels jours contiennent des données, lancez une requête sans filtres regroupés par date, pour la plage de dates qui vous intéresse.

Les résultats sont triés par nombre de clics dans l'ordre 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 savoir comment appeler cette méthode.

L'API est limitée par les limites internes de la Search Console et ne garantit pas que toutes les lignes de données soient renvoyées, mais plutôt les lignes du haut.

Découvrez les limites applicables à la quantité de données disponibles.

Exemple de requête JSON POST :

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 que définie dans la Search Console. Exemples:`http://www.example.com/` (pour une propriété avec 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 en respectant la structure suivante:

{
  "startDate": string,
  "endDate": string,
  "dimensions": [
    string
  ],
  "type": string,
  "dimensionFilterGroups": [
    {
      "groupType": string,
      "filters": [
        {
          "dimension": string,
          "operator": string,
          "expression": string
        }
      ]
    }
  ],
  "aggregationType": string,
  "rowLimit": integer,
  "startRow": integer
}

Nom de propriété	Valeur	Description
`startDate`	`string`	[Obligatoire] Date de début de la période demandée, au format AAAA-MM-JJ, exprimée en heure du Pacifique (UTC-7:00/8:00). La date de fin doit être antérieure ou égale à la date de fin. Cette valeur est comprise dans la plage.
`endDate`	`string`	[Obligatoire] Date de fin de la période demandée, au format AAAA-MM-JJ, exprimée à l'heure PT (UTC-7:00/8:00). La date de début doit être supérieure ou égale à la date de début. Cette valeur est comprise dans la plage.
`dimensions[]`	`list`	[Facultatif] Vous pouvez regrouper les résultats en fonction de zéro, une ou plusieurs dimensions.Les résultats sont regroupés dans l'ordre dans lequel vous indiquez ces dimensions.Vous pouvez utiliser n'importe quel nom de dimension dans `dimensionFilterGroups[].filters[].dimension`, ainsi que "date".Les valeurs des dimensions de regroupement sont combinées afin de créer une clé unique pour chaque ligne de résultats. Si aucune dimension n'est spécifiée, toutes les valeurs seront combinées dans une seule ligne. Vous pouvez regrouper autant de dimensions que vous le souhaitez, mais vous ne pouvez pas regrouper deux fois les données de la même dimension. Exemple : [pays, appareil]
`searchType`	`string`	Obsolète : utilisez `type` à la place
`type`	`string`	[Facultatif] Filtrez les résultats en fonction du type suivant : "`discover`": résultats Discover "`googleNews`": résultats du site 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" dans la recherche Google. "`news`": résultats de recherche issus de l'onglet "Actualités" de la recherche Google. "`image`": résultats de recherche issus de l'onglet "Image" de la recherche Google. "`video`": résultats de recherche de vidéos "`web`": [par défaut] permet de filtrer les résultats dans l'onglet combiné ("Tous") de la recherche Google. N'inclut pas les résultats Discover ni Google Actualités.
`dimensionFilterGroups[]`	`list`	[Facultatif] Zéro, un ou plusieurs groupes de filtres à appliquer aux valeurs de regroupement de 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 indiquer si tous les filtres doivent correspondre ou si au moins l'un d'entre eux doit correspondre.
`dimensionFilterGroups[].groupType`	`string`	Indique si tous les filtres de ce groupe doivent renvoyer la valeur "true" ("et") ou si un ou plusieurs d'entre eux doivent renvoyer la valeur "true" (pas encore compatible). 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] Aucun, un 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 de 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 répertoriée ici, même si vous n'effectuez pas de regroupement en fonction de celle-ci. Les valeurs acceptées sont les suivantes : "`country`": filtre en fonction du pays spécifié, avec 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 DE BUREAU 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 fonctionnalité spécifique des résultats de recherche. Pour afficher la liste des valeurs disponibles, exécutez une requête regroupée par "searchAppearance".
`dimensionFilterGroups[].filters[].operator`	`string`	[Facultatif] Indiquez si 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 ou être égale à votre expression (non sensible à la casse). "`equals`" : [par défaut] : votre expression doit être exactement égale à 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 sous la forme d'une sous-chaîne ou d'une 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 être mise en correspondance.
`dimensionFilterGroups[].filters[].expression`	`string`	Valeur du filtre à correspondre ou à exclure, selon l'opérateur.
`aggregationType`	`string`	[Facultatif] Mode d'agrégation des données. Si elles sont agrégées par propriété, toutes les données pour la même propriété sont regroupées. Si elles sont agrégées par page, toutes les données sont regroupées par URI canonique. Si vous filtrez ou regroupez par page, choisissez "Automatique". Sinon, vous pouvez agréger les données par propriété ou par page, selon le mode de calcul de vos données. Consultez la documentation d'aide pour découvrir comment les données sont calculées différemment selon le site ou par page. Remarque:Si vous regroupez ou filtrez les données 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 du résultat correspond au type demandé. Si vous demandez un type non valide, une erreur est renvoyée. L'API ne modifie jamais votre type d'agrégation si le type demandé n'est pas valide. Les valeurs acceptées sont les suivantes : "`auto`": [Par défaut] Laissez le service décider du type d'agrégation approprié. "`byNewsShowcasePanel`": valeurs agrégées 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 sur une autre `searchAppearance`, vous ne pouvez pas agréger par `byNewsShowcasePanel`. "`byPage`": valeurs agrégées par URI. "`byProperty`": valeurs agrégées par propriété. Non compatible avec `type=discover` ni `type=googleNews`
`rowLimit`	`integer`	[Facultatif ; la plage valide est comprise entre 1 et 25 000 ; la valeur par défaut est 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 basé sur zéro de la première ligne de la réponse. La valeur ne doit pas être négative. Si `startRow` dépasse le nombre de résultats de la requête, la réponse est une réponse positive avec aucune ligne.
`dataState`	`string`	[Facultatif] Si la valeur est "all" (non sensible à la casse), les données incluent des données récentes. Si ce paramètre est défini sur "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.

Réponse

Les résultats sont regroupés en fonction des dimensions spécifiées dans la requête. Toutes les valeurs utilisant le même ensemble de valeurs de dimension sont regroupées sur une seule ligne. Par exemple, si vous effectuez un regroupement en fonction de la dimension "Pays", tous les résultats pour "usa" le seront, tous les résultats pour "mdv" le seront, et ainsi de suite. Si vous avez effectué un regroupement par pays et par appareil, tous les résultats pour "français, tablette" le seront, tous les résultats pour "français, mobile" le seront, et ainsi de suite. Consultez la documentation sur le rapport "Analyse de la recherche" pour en savoir plus sur le mode de calcul des clics, des impressions, etc., ainsi que leur signification.

Les résultats sont triés par nombre de clics, dans l'ordre décroissant, sauf si vous les regroupez par date, auquel cas les résultats sont triés par date, dans l'ordre croissant (le plus ancien d'abord, le plus récent en dernier). En cas d'égalité entre deux lignes, l'ordre de tri est arbitraire.

Consultez la propriété rowLimit de 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
`rows[]`	`list`	Liste de lignes regroupées par valeurs de clé dans l'ordre indiqué dans la requête.
`rows[].keys[]`	`list`	Une liste des valeurs de dimension pour cette ligne, regroupées en fonction des dimensions de la requête, dans l'ordre spécifié dans celle-ci.
`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, inclus.
`rows[].position`	`double`	Position moyenne dans les résultats de recherche.
`responseAggregationType`	`string`	Façon dont les résultats ont été agrégés.Consultez la documentation d'aide pour savoir comment les données sont calculées différemment selon le site ou la page. Les valeurs acceptées sont les suivantes : "`auto`" "`byPage`": les résultats ont été agrégés par page. "`byProperty`": les résultats ont été agrégés par propriété.

Essayer

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