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

Search Analytics: query

Interrogez vos données sur le trafic généré par les recherches à l'aide des filtres et des 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 plusieurs jours.

Lorsque la date est l'une des dimensions, les jours sans données sont exclus de la liste des résultats. Pour savoir quels jours contiennent des données, émettez une requête sans filtres, regroupée par date, pour la période 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 appeler cette méthode.

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

Consultez 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é 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, indiquez des données en utilisant 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, dans le fuseau horaire PT (UTC -7:00/8:00). 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 période demandée, au format AAAA-MM-JJ, en heure du Pacifique (UTC -7:00/8:00). Doit être supérieure ou égale à la date de début. Cette valeur est incluse dans la plage.
`dimensions[]`	`list`	[Facultatif] Zéro ou plusieurs dimensions à regrouper. 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 "heure". Les valeurs de la dimension de regroupement sont combinées pour créer une clé unique pour chaque ligne de résultats. Si aucune dimension n'est spécifiée, toutes les valeurs sont combinées dans une seule ligne. Vous pouvez regrouper vos données selon un nombre illimité de dimensions, mais vous ne pouvez pas regrouper deux fois les données selon la même dimension. Exemple : [country, device]
`searchType`	`string`	Obsolète, utilisez plutôt `type`.
`type`	`string`	[Facultatif] Filtrez les résultats par type : "`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 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 ou plusieurs groupes de filtres à appliquer aux valeurs de regroupement des dimensions. Pour qu'une ligne soit renvoyée dans la réponse, tous les groupes de filtres doivent correspondre. 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" (non 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 vrai.
`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 ne la regroupez pas. Les valeurs acceptées sont les suivantes : "`country`": filtre basé sur le pays spécifié, tel que spécifié par le 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: DESKTOP MOBILE TABLETTE "`page`": filtre en fonction de la chaîne d'URI spécifiée. "`query`": filtrez en fonction de la chaîne de requête spécifiée. "`searchAppearance`": filtrez les résultats de recherche en fonction d'une fonctionnalité spécifique. Pour afficher la liste des valeurs disponibles, exécutez une requête groupée par "searchAppearance". La liste complète des valeurs et des descriptions est également disponible dans la documentation d'aide.
`dimensionFilterGroups[].filters[].operator`	`string`	[Facultatif] Comment la valeur que vous avez spécifiée doit correspondre (ou non) à la valeur de la dimension pour la ligne. Les valeurs acceptées sont les suivantes : "`contains`": la valeur de la ligne doit contenir ou être égale à votre expression (sans distinction entre majuscules et minuscules). "`equals`": [Par défaut] Votre expression doit être exactement égale à la valeur de la ligne (sensible à la casse pour les dimensions "Page" et "Requête"). "`notContains`": la valeur de la ligne ne doit pas contenir votre expression en tant que sous-chaîne ni en tant que correspondance complète (sans distinction entre majuscules et minuscules). "`notEquals`": votre expression ne doit pas correspondre exactement à la valeur de la ligne (sensible à la casse pour les dimensions "page" et "requête"). "`includingRegex`": expression régulière RE2 à faire correspondre. "`excludingRegex`": expression régulière RE2 qui ne doit pas être mise en correspondance.
`dimensionFilterGroups[].filters[].expression`	`string`	Valeur à faire correspondre ou à exclure pour le filtre, en fonction de l'opérateur.
`aggregationType`	`string`	[Facultatif] Comment les données sont agrégées. Si l'agrégation est effectuée par propriété, toutes les données de la même propriété sont regroupées. Si l'agrégation est effectuée par page, toutes les données sont regroupées par URI canonique. Si vous filtrez ou regroupez les données par page, choisissez "Auto". Sinon, vous pouvez les agréger par propriété ou par page, selon la manière 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 du résultat correspondra au type demandé. Si vous demandez un type non valide, une erreur s'affichera. L'API ne modifiera 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éterminer le type d'agrégation approprié. "`byNewsShowcasePanel`": agrégation des valeurs par panneau News Showcase. Il doit être utilisé conjointement avec le filtre `searchAppearance` `NEWS_SHOWCASE` et `type=discover` ou `type=googleNews`. Si vous regroupez par page, filtrez par page ou filtrez vers une autre `searchAppearance`, vous ne pouvez pas agréger par `byNewsShowcasePanel`. "`byPage`": valeurs globales par URI. "`byProperty`": agrégation des valeurs par propriété. Non compatible avec `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 ; par défaut, 0] Indice basé sur zéro de la première ligne de la réponse. Doit être un nombre non négatif. Si `startRow` dépasse le nombre de résultats de la requête, la réponse est positive, mais ne contient aucune ligne.
`dataState`	`string`	[Facultatif] Si la valeur est "all" (toutes les données, insensible à la casse), les données incluront les données récentes. Si la valeur "final" (insensible à la casse) est spécifiée ou si ce paramètre est omis, seules les données finalisées sont renvoyées. Si la valeur est "hourly_all" (non sensible à la casse), les données incluent la 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 API HOUR.

Réponse

Les résultats sont regroupés en fonction des dimensions spécifiées dans la requête. Toutes les valeurs ayant le même ensemble de valeurs de dimension seront regroupées sur une seule ligne. Par exemple, si vous regroupez les données 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, etc. Consultez la documentation sur le rapport "Analyse de la recherche" pour en savoir plus sur la manière dont les clics, les impressions, etc. sont calculés et sur 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 ils sont triés par date, dans l'ordre croissant (les plus anciens en premier, les plus récents en dernier). En cas d'égalité entre deux lignes, 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
`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 en fonction des dimensions de la requête, dans l'ordre spécifié dans la requête.
`rows[].clicks`	`double`	Cliquez sur le nombre de lignes.
`rows[].impressions`	`double`	Nombre d'impressions pour la ligne.
`rows[].ctr`	`double`	Taux de clics (CTR) de 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 et 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é.

Essayer

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