Search Analytics: query

Nécessite une autorisation

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

Lorsque la date fait partie de l'attribut, 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 d'intérêt.

Les résultats sont triés par ordre décroissant du nombre de clics. Si deux lignes présentent 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 les premières.

Découvrez les limites concernant 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

Portée
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 les données avec 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 Remarques
startDate string [Obligatoire] Date de début de la période demandée, au format AAAA-MM-JJ, au format PT (UTC - 7:00/8:00) Doit être inférieure ou égale à la date de fin. Cette valeur est comprise dans la plage.
endDate string [Obligatoire] Date de fin de la plage de dates demandée, au format AAAA-MM-JJ, au format PT (UTC - 7:00/8:00). Doit être supérieure ou égale à la date de début. Cette valeur est comprise dans la plage.
dimensions[] list [Facultatif] Zéro, une ou plusieurs dimensions selon lesquelles regrouper les résultats.Les résultats sont regroupés dans l'ordre dans lequel vous les avez fournis.Vous pouvez utiliser n'importe quel nom de dimension dans dimensionFilterGroups[].filters[].dimension ainsi que "date".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 sont combinées sur une seule ligne. Vous pouvez regrouper autant de dimensions que vous le souhaitez, mais vous ne pouvez pas regrouper deux fois la même dimension. Exemple : [pays, appareil]
searchType string Obsolète. Utilisez plutôt type.
type string [Facultatif] Filtrez les résultats selon le type suivant :
  • "discover" : découvrir les résultats
  • "googleNews" : résultats provenant 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] filtrer les résultats sur l'onglet combiné ("Tous") de la recherche Google. N'inclut pas les résultats Discover ou Google Actualités.
dimensionFilterGroups[] list [Facultatif] Zéro, un ou plusieurs groupes de filtres à appliquer aux valeurs du regroupement de dimensions. Tous les groupes de filtres doivent correspondre pour qu'une ligne soit affichée dans la réponse. Dans un même groupe de filtres, vous pouvez indiquer si tous les filtres doivent correspondre ou s'ils doivent être identiques.
dimensionFilterGroups[].groupType string Indique si tous les filtres de ce groupe doivent renvoyer la valeur "true" ("et"), ou un ou plusieurs doivent renvoyer la valeur "true" (pas encore disponible).

Les valeurs autorisé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, un ou plusieurs filtres à tester sur la ligne. Chaque filtre comprend un nom de dimension, un opérateur et une valeur. Ne doit pas dépasser 4 096 caractères. Exemples :
country equals FRA
query contains mobile use
device notContains tablet
dimensionFilterGroups[].filters[].dimension string Dimension à laquelle s'applique ce filtre. Vous pouvez filtrer les données en fonction des variables répertoriées ici, même si vous ne groupez pas les données en fonction de cette variable.

Les valeurs autorisées sont les suivantes :
  • "country" : filtre en fonction du pays spécifié, comme indiqué 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:
    • POUR ORDINATEUR
    • MOBILE
    • TABLETTE
  • "page" : filtre sur la chaîne URI spécifiée.
  • "query" : filtre sur la chaîne de requête spécifiée.
  • "searchAppearance" : filtrez les résultats en fonction d'une fonctionnalité de résultat de recherche spécifique. Pour afficher la liste des valeurs disponibles, exécutez une requête regroupée par "SearchAppearance".
dimensionFilterGroups[].filters[].operator string [Facultatif] Indiquez dans quelle mesure la valeur spécifiée doit correspondre (ou non) à la valeur de la ligne.

Les valeurs autorisées sont les suivantes :
  • "contains" : la valeur de la ligne doit contenir ou égaler votre expression (non sensible à 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 ni en tant que correspondance complète (non sensible à la casse).
  • "notEquals" : votre expression ne doit pas correspondre exactement à 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 correspondre.
  • "excludingRegex" : expression régulière de syntaxe RE2 qui ne doit pas être mise en correspondance.
dimensionFilterGroups[].filters[].expression string Valeur du filtre à mettre en correspondance ou à exclure, en fonction de 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 de la même propriété sont agrégées. Si elles sont agrégées par page, toutes les données sont agrégées par URI canonique. Si vous filtrez ou regroupez par page, sélectionnez "Automatique". Sinon, vous pouvez agréger les données par propriété ou par page, selon le mode de calcul souhaité. Consultez la documentation d'aide pour découvrir comment les données sont calculées par site et par page.

Remarque:Si vous groupez ou filtrez par page, vous ne pouvez pas effectuer d'agrégation par propriété.

Si vous spécifiez une valeur autre qu'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.

Valeurs autorisées :
  • "auto" : [par défaut] laisser le service décider du type d'agrégation approprié.
  • "byPage" : agréger les valeurs par URI.
  • "byProperty" : agréger les valeurs par propriété. Non compatible avec type=discover ou 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 de base zéro de la première ligne de la réponse. La valeur doit être un nombre non négatif. Si startRow dépasse le nombre de résultats pour la requête, la réponse sera une réponse positive avec aucune ligne.
dataState string [Facultatif] Si "tous" (non sensible à la casse), les données incluent des données récentes. Si la valeur est "finale" (non sensible à la casse) ou si ce paramètre est omis, les données renvoyées n'incluent 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 ayant le même ensemble de valeurs de dimension seront regroupées sur une seule ligne. Par exemple, si vous effectuez un regroupement par variable de pays, tous les résultats pour "usa" seront regroupés, tous les résultats pour "mdv" seront regroupés, etc. Si vous procédez à un regroupement 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 du rapport Analyse de la recherche pour découvrir comment les clics, les impressions, etc. sont calculés et connaître leur signification.

Les résultats sont triés par nombre de clics, par ordre décroissant, sauf si vous les groupez par date. Dans ce cas, les résultats sont triés par date, par 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 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 en fonction des 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) 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 Manière dont 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 selon le site et la page.

Les valeurs autorisé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.