Autorisation requise
interroger vos données de trafic de recherche à l'aide de filtres et de 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 "date" est l'une 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 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 des limites internes de la Search Console et ne garantit pas de renvoyer toutes les lignes de données, mais plutôt les premières.
Voir les limites relatives à la quantité de données disponible
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 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 les données selon 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 Heure du Pacifique (UTC - 7:00/8:00). La date de fin doit être inférieure ou égale à celle de 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, et heure du Pacifique (UTC - 7:00/8:00). La date de début doit être supérieure ou égale à la date de début. Cette valeur est incluse dans la plage. | |
dimensions[] |
list |
[Facultatif] Zéro, une ou plusieurs dimensions pour regrouper les résultats.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ésultat. Si aucune dimension n'est spécifiée, toutes les valeurs sont combinées en une seule ligne. Vous pouvez utiliser un nombre illimité de dimensions, 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:
<ph type="x-smartling-placeholder">
|
|
dimensionFilterGroups[] |
list |
[Facultatif] Zéro, un ou plusieurs groupes de filtres à appliquer aux valeurs des regroupements de 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 au moins un filtre doit correspondre. | |
dimensionFilterGroups[].groupType |
string |
Permet de spécifier 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).
Les valeurs possibles sont les suivantes: <ph type="x-smartling-placeholder">
|
|
dimensionFilterGroups[].filters[] |
list |
[Facultatif] Aucun, un ou plusieurs filtres, à tester par rapport à la ligne Chaque filtre est composé des éléments suivants :
un nom de dimension, un opérateur et une valeur. Longueur maximale : 4 096 caractères. Exemples:
country equals FRA query contains mobile use device notContains tablet |
|
dimensionFilterGroups[].filters[].dimension |
string |
Il s'agit de la 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'effectuez pas de regroupement en fonction de cette dimension.
Les valeurs possibles sont les suivantes: <ph type="x-smartling-placeholder">
|
|
dimensionFilterGroups[].filters[].operator |
string |
[Facultatif] Indique à quel point la valeur spécifiée doit correspondre (ou ne pas correspondre) à la valeur de dimension de la ligne.
Les valeurs possibles sont les suivantes: <ph type="x-smartling-placeholder">
|
|
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 une même propriété est agrégée ; En cas d'agrégation par page, toutes les données sont regroupées par pages canoniques URI. Si vous filtrez ou regroupez par page, choisissez auto; Sinon, vous pouvez agréger propriété ou par page, selon le mode de calcul souhaité. voir la documentation d'aide pour découvrir comment les données sont calculées différemment selon le site et la page. Remarque: Si vous regroupez ou filtrez les données par page, vous ne pouvez pas les agréger par propriété. Si vous indiquez une valeur autre que "auto", le type d'agrégation du résultat correspond au type demandé ; ou Si vous demandez un type non valide, un message d'erreur s'affiche. L'API ne modifiera jamais votre type d'agrégation si le type demandé n'est pas valide. Les valeurs acceptables sont les suivantes: <ph type="x-smartling-placeholder">
|
|
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 doit être un nombre non négatif. Si startRow dépasse le nombre de résultats pour la requête, la réponse est une réponse positive sans aucune ligne. |
|
dataState |
string |
[Facultatif] Si "tous" (non sensible à la casse), les données suivantes des données à jour. Si « final » (non sensible à la casse) ou, si ce paramètre est omis, les données renvoyées incluront uniquement 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 associées au même ensemble de valeurs de dimension sont regroupées sur une même ligne. Par exemple, si vous effectuez un regroupement en fonction de la dimension "Pays", tous les résultats pour "usa" seront regroupés, tous les résultats pour "mdv" sont regroupés, etc. Si vous avez effectué un regroupement par pays et par appareil, tous les résultats pour "usa, tablet" sera regroupé, tous les résultats pour "usa, mobile" sont regroupés, etc. 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 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 les résultats 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 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 selon les 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 |
Méthode d'agrégation des résultatsConsultez la documentation d'aide pour découvrir comment les données sont calculées différemment par site et par page.
Les valeurs possibles sont les suivantes: <ph type="x-smartling-placeholder">
|
Essayer
Utilisez l'explorateur d'API ci-dessous pour appeler cette méthode sur des données en direct, puis observez la réponse.