Autorisation requise
Interrogez vos données de trafic de recherche à l'aide de filtres et de 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, tous les jours sans données sont omis de la liste de résultats. Pour savoir quels jours contiennent des données, exécutez 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, par 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 contraintes 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 concernant 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 qu'elle est définie dans la Search Console. Exemples : http://www.example.com/ (pour une propriété de 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 | Remarques |
|---|---|---|---|
startDate |
string |
[Obligatoire] Date de début de la plage de dates 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 plage de dates demandée, au format AAAA-MM-JJ, dans le fuseau horaire PT (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 selon lesquelles regrouper les résultats. 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 "hour". 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 en une seule ligne. Le nombre de dimensions selon lesquelles vous pouvez regrouper les données n'est pas limité, mais vous ne pouvez pas regrouper les données selon la même dimension deux fois. Exemple : [country, device] | |
searchType |
string |
Obsolète, utilisez type à la place
|
|
type |
string |
[Facultatif] Filtrez les résultats selon le type suivant :
|
|
dimensionFilterGroups[] |
list |
[Facultatif] Zéro ou plusieurs groupes de filtres à appliquer aux valeurs de regroupement des 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 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 doivent renvoyer la valeur "true" (pas encore compatible).
Les valeurs acceptables sont les suivantes :
|
|
dimensionFilterGroups[].filters[] |
list |
[Facultatif] Zéro ou plusieurs filtres à tester par rapport à la ligne. Chaque filtre se compose de
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 |
Dimension à laquelle ce filtre s'applique. Vous pouvez filtrer les données selon n'importe quelle dimension listée ici, même si vous ne les regroupez pas selon cette dimension.
Les valeurs acceptables sont les suivantes :
|
|
dimensionFilterGroups[].filters[].operator |
string |
[Facultatif] Indique si la valeur spécifiée doit correspondre (ou non) à la valeur de la dimension pour la ligne.
Les valeurs acceptables sont les suivantes :
|
|
dimensionFilterGroups[].filters[].expression |
string |
Valeur à laquelle le filtre doit correspondre ou qu'il doit exclure, selon l'opérateur. | |
aggregationType |
string |
[Facultatif] Indique comment les données sont agrégé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 les données par page, choisissez "auto". Sinon, vous pouvez les agréger par propriété ou par page, selon la façon dont vous souhaitez les calculer. 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 les données par page, vous ne pouvez pas les agréger par propriété. Si vous spécifiez une valeur autre que "auto", le type d'agrégation dans le résultat correspond au type demandé. Si vous demandez un type non valide, une erreur s'affiche. L'API ne modifie jamais votre type d'agrégation si le type demandé n'est pas valide. Les valeurs acceptables sont les suivantes :
|
|
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 ; valeur par défaut : 0] Index de base zéro de la première ligne de la réponse. Spécifiez un nombre non négatif. Si startRow dépasse le nombre de résultats de la requête, la réponse sera une réponse réussie avec zéro ligne. |
|
dataState |
string |
[Facultatif] Si la valeur est "all" (sans tenir compte de la casse), les données incluent les données récentes. Si la valeur est "final" (sans tenir compte de la casse) ou si ce paramètre est omis, les données renvoyées n'incluent que les données finalisées. Si la valeur est "hourly_all" (sans tenir compte de la casse), les données incluent une répartition horaire. Cela indique que les données horaires incluent des données partielles et doivent être utilisées lors du regroupement par dimension d'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 sont regroupées en une seule ligne. Par exemple, si vous regroupez les données par dimension de pays, tous les résultats pour "usa" sont regroupés, tous les résultats pour "mdv" sont regroupés, et ainsi de suite. Si vous regroupez les données par pays et par appareil, tous les résultats pour "usa, tablette" sont regroupés, tous les résultats pour "usa, mobile" sont regroupés, et ainsi de suite. Consultez la documentation du rapport sur les performances dans la recherche pour découvrir les spécificités du calcul des clics, des impressions, etc., et leur signification.
Les résultats sont triés par nombre de clics, par ordre décroissant, sauf si vous les regroupez par date. Dans ce cas, ils sont triés par date, par ordre croissant (du plus ancien au plus récent). Si deux lignes sont à égalité, 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 les valeurs clés 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) 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 |
Indique 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 acceptables sont les suivantes :
|
|
metadata |
object |
Objet pouvant être renvoyé avec les résultats de votre requête, fournissant un contexte sur l'état des données. Lorsque vous demandez des données récentes (en utilisant Toutes les dates et heures fournies dans cet objet sont dans le Le champ spécifique renvoyé dans cet objet dépend de la façon dont vous avez regroupé vos données dans la requête :
|
Essayer
Utilisez l'explorateur d'API ci-dessous pour appeler cette méthode sur des données en direct, puis observez la réponse.