Erfordert Autorisierung
Fragen Sie Ihre Daten zum Traffic über das Suchnetzwerk mit von Ihnen definierten Filtern und Parametern ab. Die Methode gibt null oder mehr Zeilen zurück, die nach den von Ihnen definierten Zeilenschlüsseln (Dimensionen) gruppiert sind. Sie müssen einen Zeitraum von einem oder mehreren Tagen festlegen.
Wenn das Datum eine der Dimensionen ist, werden alle Tage ohne Daten aus der Ergebnisliste weggelassen. Wenn Sie wissen möchten, für welche Tage Daten vorhanden sind, führen Sie eine Abfrage ohne Filter aus, die nach Datum gruppiert ist, und zwar für den gewünschten Zeitraum.
Die Ergebnisse sind nach der Anzahl Klicks absteigend sortiert. Wenn zwei Zeilen dieselbe Anzahl Klicks haben, werden sie in beliebiger Reihenfolge sortiert.
Ein Beispiel für den Aufruf dieser Methode finden Sie im Python-Beispiel.
Die API ist durch interne Einschränkungen der Search Console begrenzt. Es wird nicht garantiert, dass alle Datenzeilen zurückgegeben werden, sondern nur die wichtigsten.
Informationen zu den Einschränkungen bei der Menge der verfügbaren Daten
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"]
}Anfrage
HTTP-Anfrage
POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query
Parameter
| Parametername | Wert | Beschreibung |
|---|---|---|
| Pfadparameter | ||
siteUrl |
string |
Die URL der Property, wie sie in der Search Console definiert ist. Beispiele:
http://www.example.com/ (für eine URL-Präfix-Property) oder
sc-domain:example.com (für eine Domain-Property)
|
Autorisierung
Diese Anfrage benötigt eine Autorisierung mit mindestens einem der folgenden Bereiche (weitere Informationen zu Authentifizierung und Autorisierung).
| Bereich |
|---|
https://www.googleapis.com/auth/webmasters.readonly |
https://www.googleapis.com/auth/webmasters |
Anfragetext
Geben Sie im Anfragetext Daten mit der folgenden Struktur ein:
{
"startDate": string,
"endDate": string,
"dimensions": [
string
],
"type": string,
"dimensionFilterGroups": [
{
"groupType": string,
"filters": [
{
"dimension": string,
"operator": string,
"expression": string
}
],
"filterLists": [
{
"dimension": string,
"expressions": [
string
]
}
]
}
],
"aggregationType": string,
"rowLimit": integer,
"startRow": integer
}| Name der Eigenschaft | Wert | Beschreibung | Hinweise |
|---|---|---|---|
startDate |
string |
[Erforderlich] Startdatum des angeforderten Zeitraums im Format JJJJ-MM-TT, in PT-Zeit (UTC - 7:00/8:00). Muss kleiner oder gleich dem Enddatum sein. Dieser Wert ist im Bereich enthalten. | |
endDate |
string |
[Erforderlich] Enddatum des angeforderten Zeitraums im Format JJJJ-MM-TT, in PT-Zeit (UTC - 7:00/8:00). Muss größer oder gleich dem Startdatum sein. Dieser Wert ist im Bereich enthalten. | |
dimensions[] |
list |
[Optional] Null oder mehr Dimensionen, nach denen die Ergebnisse gruppiert werden sollen. Die Ergebnisse werden in der Reihenfolge gruppiert, in der Sie diese Dimensionen angeben. Sie können jeden Dimensionsnamen in dimensionFilterGroups[].filters[].dimension sowie „date“ und „hour“ verwenden. Die Werte der Gruppierungsdimensionen werden kombiniert, um einen eindeutigen Schlüssel für jede Ergebniszeile zu erstellen. Wenn keine Dimensionen angegeben sind, werden alle Werte in einer einzigen Zeile zusammengefasst. Die Anzahl der Dimensionen, nach denen Sie gruppieren können, ist nicht begrenzt. Sie können jedoch nicht zweimal nach derselben Dimension gruppieren. Beispiel: [Land, Gerät] | |
searchType |
string |
Verworfen, verwenden Sie stattdessen type
|
|
type |
string |
[Optional] Filtern Sie die Ergebnisse nach dem folgenden Typ:
|
|
dimensionFilterGroups[] |
list |
[Optional] Null oder mehr Filtergruppen, die auf die Werte der Dimensionsgruppierung angewendet werden sollen. Alle Filtergruppen müssen übereinstimmen, damit eine Zeile in der Antwort zurückgegeben wird. Innerhalb einer einzelnen Filtergruppe können Sie angeben, ob alle Filter übereinstimmen müssen oder ob mindestens einer übereinstimmen muss. | |
dimensionFilterGroups[].groupType |
string |
Gibt an, ob alle Filter in dieser Gruppe „true“ zurückgeben müssen („and“) oder ob ein oder mehrere Filter „true“ zurückgeben müssen (noch nicht unterstützt).
Zulässige Werte sind:
|
|
dimensionFilterGroups[].filters[] |
list |
[Optional] Null oder mehr Filter, die auf die Zeile angewendet werden sollen. Jeder Filter besteht aus einem Dimensionsnamen, einem Operator und einem Wert. Maximale Länge: 4.096 Zeichen. Beispiele:
country equals FRA query contains mobile use device notContains tablet |
|
dimensionFilterGroups[].filters[].dimension |
string |
Die Dimension, auf die dieser Filter angewendet wird. Sie können nach jeder hier aufgeführten Dimension filtern, auch wenn Sie nicht nach dieser Dimension gruppieren.
Zulässige Werte sind:
|
|
dimensionFilterGroups[].filters[].operator |
string |
[Optional] Wie der angegebene Wert mit dem Dimensionswert für die Zeile übereinstimmen (oder nicht übereinstimmen) muss.
Zulässige Werte sind:
|
|
dimensionFilterGroups[].filters[].expression |
string |
Der Wert, den der Filter je nach Operator abgleichen oder ausschließen soll. | |
dimensionFilterGroups[].filterLists[] |
list |
[Optional] Null oder mehr Dimensionsfilter mit mehreren Werten, die für die Zeile getestet werden sollen.
Im Gegensatz zu filters[], das einen einzelnen Wert pro Eintrag abgleicht, ermöglicht filterLists[] den Abgleich mit mehreren genau passenden Werten für eine einzelne Dimension in einem Filter. Eine Zeile entspricht einer Filterliste, wenn ihr Wert für die angegebene dimension mit einer der angegebenen expressions übereinstimmt. Beachten Sie, dass in einer einzelnen Anfrage nicht gleichzeitig in filters und filterLists nach derselben Dimension gefiltert werden kann. |
|
dimensionFilterGroups[].filterLists[].dimension |
string |
[Erforderlich] Die Dimension, auf die diese Filterliste angewendet wird.
Zulässige Werte sind:
|
|
dimensionFilterGroups[].filterLists[].expressions[] |
list |
[Erforderlich] Die Liste der Werte (string), nach denen gefiltert werden soll. |
|
aggregationType |
string |
[Optional] Wie Daten aggregiert werden. Wenn die Daten nach Property zusammengefasst werden, werden alle Daten für dieselbe Property zusammengefasst. Wenn die Daten nach Seite zusammengefasst werden, werden alle Daten nach kanonischem URI zusammengefasst. Wenn Sie nach Seite filtern oder gruppieren, wählen Sie „Automatisch“ aus. Andernfalls können Sie entweder nach Property oder nach Seite zusammenfassen, je nachdem, wie Ihre Daten berechnet werden sollen. In der Hilfedokumentation erfahren Sie, wie Daten nach Website und nach Seite unterschiedlich berechnet werden. Hinweis: Wenn Sie nach Seite gruppieren oder filtern, können Sie nicht nach Property zusammenfassen. Wenn Sie einen anderen Wert als „auto“ angeben, entspricht der Aggregationstyp im Ergebnis dem angeforderten Typ. Wenn Sie einen ungültigen Typ anfordern, erhalten Sie einen Fehler. Die API ändert den Aggregationstyp nie, wenn der angeforderte Typ ungültig ist. Zulässige Werte sind:
|
|
rowLimit |
integer |
[Optional; gültiger Bereich: 1–25.000; Standardwert: 1.000] Die maximale Anzahl der zurückzugebenden Zeilen. Verwenden Sie den Offset startRow, um durch die Ergebnisse zu blättern. |
|
startRow |
integer |
[Optional; Standardwert ist 0] Nullbasierter Index der ersten Zeile in der Antwort. Muss eine nicht negative Zahl sein. Wenn startRow die Anzahl der Ergebnisse für die Abfrage überschreitet, ist die Antwort eine erfolgreiche Antwort mit null Zeilen. |
|
dataState |
string |
[Optional] Wenn „all“ (Groß-/Kleinschreibung wird nicht berücksichtigt) angegeben ist, enthalten die Daten aktuelle Daten. Wenn „final“ (Groß-/Kleinschreibung wird nicht berücksichtigt) oder wenn dieser Parameter weggelassen wird, enthalten die zurückgegebenen Daten nur endgültige Daten. Wenn „hourly_all“ (Groß-/Kleinschreibung wird nicht berücksichtigt), enthalten die Daten eine stündliche Aufschlüsselung. Dies weist darauf hin, dass die stündlichen Daten unvollständig sind und beim Gruppieren nach der API-Dimension HOUR verwendet werden sollten. |
Antwort
Die Ergebnisse werden nach den in der Anfrage angegebenen Dimensionen gruppiert. Alle Werte mit demselben Satz von Dimensionswerten werden in einer einzigen Zeile gruppiert. Wenn Sie beispielsweise nach der Dimension „Land“ gruppieren, werden alle Ergebnisse für „usa“ zusammengefasst, alle Ergebnisse für „mdv“ zusammengefasst usw. Wenn Sie nach Land und Gerät gruppiert haben, werden alle Ergebnisse für „USA, Tablet“, alle Ergebnisse für „USA, Mobilgerät“ usw. gruppiert. In der Dokumentation zum Bericht „Suchanalyse“ finden Sie weitere Informationen dazu, wie Klicks, Impressionen usw. berechnet werden und was sie bedeuten.
Die Ergebnisse werden nach der Anzahl Klicks in absteigender Reihenfolge sortiert, es sei denn, Sie gruppieren nach Datum. In diesem Fall werden die Ergebnisse nach Datum in aufsteigender Reihenfolge sortiert (älteste zuerst, neueste zuletzt). Wenn zwei Zeilen denselben Wert haben, ist die Sortierreihenfolge beliebig.
In der Anfrage finden Sie die Property rowLimit, die die maximale Anzahl von Werten angibt, die zurückgegeben werden können.
{
"rows": [
{
"keys": [
string
],
"clicks": double,
"impressions": double,
"ctr": double,
"position": double
}
],
"responseAggregationType": string
}| Property-Name | Wert | Beschreibung | Hinweise |
|---|---|---|---|
rows[] |
list |
Eine Liste von Zeilen, die nach den Schlüsselwerten in der in der Abfrage angegebenen Reihenfolge gruppiert sind. | |
rows[].keys[] |
list |
Eine Liste der Dimensionswerte für diese Zeile, gruppiert nach den Dimensionen in der Anfrage, in der in der Anfrage angegebenen Reihenfolge. | |
rows[].clicks |
double |
Anzahl Klicks für die Zeile. | |
rows[].impressions |
double |
Anzahl der Impressionen für die Zeile. | |
rows[].ctr |
double |
Klickrate (CTR) für die Zeile. Die Werte reichen von 0 bis 1, 0 (einschließlich). | |
rows[].position |
double |
Durchschnittliche Position in den Suchergebnissen. | |
responseAggregationType |
string |
Wie die Ergebnisse aggregiert wurden. In der Hilfe erfahren Sie, wie sich die Berechnung von Daten nach Website von der Berechnung nach Seite unterscheidet.
Zulässige Werte sind:
|
|
metadata |
object |
Ein Objekt, das mit Ihren Abfrageergebnissen zurückgegeben werden kann und Kontext zum Status der Daten liefert. Wenn Sie aktuelle Daten anfordern (mit Alle in diesem Objekt angegebenen Datums- und Uhrzeitangaben beziehen sich auf die Zeitzone Das spezifische Feld, das in diesem Objekt zurückgegeben wird, hängt davon ab, wie Sie Ihre Daten in der Anfrage gruppiert haben:
|
Testen!
Verwenden Sie den unten angegebenen APIs Explorer, um diese Methode für Livedaten aufzurufen und die Antwort einzusehen.