Autorisation requise
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, une 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 comportent 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 décroissant. Si deux lignes indiquent 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 des limites internes de la Search Console et ne garantit pas de renvoyer toutes les lignes de données, mais plutôt les lignes les plus élevées.
Découvrez les limites applicables à la quantité de données disponibles.
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"] }
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 un 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
Définition du 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 présentant 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, 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, en heure du Pacifique (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] Aucune, une ou plusieurs dimensions à utiliser pour regrouper les résultatsLes 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".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 sont combinées dans une seule ligne. Vous pouvez regrouper autant de dimensions que vous le souhaitez, mais vous ne pouvez pas effectuer un regroupement deux fois par rapport à 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 :
|
|
dimensionFilterGroups[] |
list |
[Facultatif] Aucun, 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 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 filtres doivent renvoyer la valeur "true" (pas encore disponible).
Valeurs acceptées :
|
|
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 : 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 de n'importe quelle dimension listée ici, même si vous n'effectuez pas de regroupement en fonction de celle-ci.
Valeurs acceptées :
|
|
dimensionFilterGroups[].filters[].operator |
string |
[Facultatif] La valeur spécifiée doit correspondre (ou ne pas correspondre) à la valeur de dimension associée à la ligne.
Valeurs acceptées :
|
|
dimensionFilterGroups[].filters[].expression |
string |
Valeur du filtre à correspondre 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é le sont. En cas d'agrégation par page, toutes les données sont agrégées par URI canonique. Si vous filtrez ou regroupez par page, choisissez "Automatique". Sinon, vous pouvez agréger 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 la page. Remarque:Si vous effectuez un regroupement ou un filtrage par page, vous ne pouvez pas agréger les données par propriété. Si vous spécifiez une valeur autre que "auto", le type d'agrégation indiqué dans le 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. Voici les valeurs acceptées :
|
|
rowLimit |
integer |
[Facultatif ; plage valide est comprise entre 1 et 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. Veuillez saisir un nombre non négatif. Si startRow dépasse le nombre de résultats de la requête, la réponse est une réponse réussie avec aucune ligne. |
|
dataState |
string |
[Facultatif] Si la valeur est "all" (non sensible à la casse), les données incluent de nouvelles données. Si ce paramètre est défini sur "final" (non sensible à la casse) ou omis, les données renvoyées ne comprendront 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 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, etc. Si vous avez regroupé les résultats par pays et par appareil, tous les résultats pour "france, tablette" le seront, alors que tous les résultats pour "français, mobile" le seront, etc. Consultez la documentation du rapport "Analyse de la recherche" pour découvrir les détails du calcul des clics, des impressions, etc., et 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 (les plus anciens d'abord, les plus récents 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 | Remarques |
---|---|---|---|
rows[] |
list |
Liste de lignes regroupées en fonction des 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 demande, dans l'ordre spécifié dans la demande. | |
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) associé à 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 découvrir comment les données sont calculées différemment selon le site ou la page.
Valeurs acceptées :
|
Essayer
Utilisez l'explorateur d'API ci-dessous pour appeler cette méthode sur des données en direct, puis observez la réponse.