Fragen Sie Ihre Daten zu Suchzugriffen mit von Ihnen definierten Filtern und Parametern ab. Die Methode gibt null oder mehr Zeilen zurück, gruppiert nach den von Ihnen definierten Zeilenschlüsseln (Dimensionen). Sie müssen einen Zeitraum von einem oder mehreren Tagen festlegen.
Wenn das Datum eine der Dimensionen ist, werden alle Tage ohne Daten in der Ergebnisliste weggelassen. Wenn Sie wissen möchten, für welche Tage Daten verfügbar sind, führen Sie für den gewünschten Zeitraum eine Abfrage ohne nach Datum gruppierte Filter durch.
Die Ergebnisse werden absteigend nach der Anzahl der Klicks sortiert. Wenn zwei Zeilen dieselbe Anzahl an Klicks haben, werden sie auf beliebige Weise sortiert.
Informationen zum Aufrufen dieser Methode finden Sie im Python-Beispiel.
Die API ist durch interne Einschränkungen der Search Console begrenzt und kann nicht garantieren, dass alle Datenzeilen, sondern nur die ersten ausgegeben werden.
Weitere Informationen zu Limits für die 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 in der Search Console definiert. 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
}
]
}
],
"aggregationType": string,
"rowLimit": integer,
"startRow": integer
}
| Property-Name | Wert | Beschreibung | Hinweise |
|---|---|---|---|
startDate |
string |
[Erforderlich] Startdatum des angeforderten Zeitraums im Format JJJJ-MM-TT, in PT (UTC - 7:00/8:00). Muss vor dem Enddatum liegen oder diesem entsprechen. Dieser Wert ist im Bereich enthalten. | |
endDate |
string |
[Erforderlich] Enddatum des angeforderten Zeitraums im Format JJJJ-MM-TT in PT (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 Ergebnisse gruppiert werden sollen.Die Ergebnisse werden in der Reihenfolge gruppiert, in der Sie diese Dimensionen angeben.In dimensionFilterGroups[].filters[].dimension können Sie einen beliebigen Dimensionsnamen sowie „Datum“ verwenden.Die Werte der Gruppierungsdimension werden kombiniert, um einen eindeutigen Schlüssel für jede Ergebniszeile zu erstellen. Wenn keine Dimensionen angegeben werden, werden alle Werte in einer Zeile zusammengefasst. Es gibt keine Beschränkung für die Anzahl der Dimensionen, nach denen Sie gruppieren können, aber Sie können nicht zweimal nach derselben Dimension gruppieren. Beispiel: [Land, Gerät] | |
searchType |
string |
Eingestellt. Verwende stattdessen type.
|
|
type |
string |
[Optional] Filtern Sie die Ergebnisse nach dem folgenden Typ:
|
|
dimensionFilterGroups[] |
list |
[Optional] Null oder mehr Gruppen von Filtern, die auf die Werte für die Dimensionsgruppierung angewendet werden sollen. Alle Filtergruppen müssen übereinstimmen, damit eine Zeile in der Antwort zurückgegeben wird. Innerhalb einer Filtergruppe können Sie festlegen, ob alle Filter oder mindestens ein Filter übereinstimmen müssen. | |
dimensionFilterGroups[].groupType |
string |
Gibt an, ob alle Filter in dieser Gruppe „true“ („und“) oder mindestens einer der Filter „true“ zurückgeben müssen (noch nicht unterstützt).
Zulässige Werte sind:
|
|
dimensionFilterGroups[].filters[] |
list |
[Optional] Null oder mehr Filter zum Testen in der Zeile. 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] Legt fest, wie der angegebene Wert mit dem Dimensionswert in der Zeile übereinstimmen muss.
Zulässige Werte sind:
|
|
dimensionFilterGroups[].filters[].expression |
string |
Der Wert für den Filter, der je nach Operator abgeglichen oder ausgeschlossen werden soll. | |
aggregationType |
string |
[Optional] Wie Daten aggregiert werden. Bei Zusammenfassung nach Property werden alle Daten für dieselbe Property zusammengefasst. Bei Aggregation nach Seite werden alle Daten nach kanonischen URI zusammengefasst. Wenn du nach Seite filtern oder gruppieren möchtest, wähle „Automatisch“ aus. Andernfalls kannst du die Daten entweder nach Property oder nach Seite zusammenfassen, je nachdem, wie deine Daten berechnet werden sollen. In der Hilfedokumentation erfährst du, wie Daten je nach Website oder Seite unterschiedlich berechnet werden. Hinweis:Wenn Sie nach Seite gruppieren oder filtern, ist keine Aggregation nach Property möglich. Wenn Sie einen anderen Wert als „automatisch“ angeben, entspricht der Aggregationstyp im Ergebnis dem angeforderten Typ. Wenn Sie einen ungültigen Typ anfordern, erhalten Sie eine Fehlermeldung. Die API ändert den Zusammenfassungstyp nie, wenn der angeforderte Typ ungültig ist. Zulässige Werte sind:
|
|
rowLimit |
integer |
[Optional; Gültiger Bereich ist 1–25.000; Standardwert ist 1.000] Die maximale Anzahl von Zeilen, die zurückgegeben werden sollen. 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“ angegeben ist (Groß-/Kleinschreibung wird nicht berücksichtigt), enthalten die Daten aktuelle Daten. Wenn „endgültig“ (Groß-/Kleinschreibung nicht berücksichtigt wird) oder dieser Parameter weggelassen wird, enthalten die zurückgegebenen Daten nur endgültige Daten. |
Antwort
Die Ergebnisse werden nach den in der Anfrage angegebenen Dimensionen gruppiert. Alle Werte mit denselben Dimensionswerten werden in einer einzigen Zeile gruppiert. Wenn Sie beispielsweise nach der Länderdimension gruppieren, werden alle Ergebnisse für „usa“, alle Ergebnisse für „mdv“ und so weiter gruppiert. Wenn Sie nach Land und Gerät gruppieren, werden alle Ergebnisse für „usa, Tablet“ gruppiert, alle Ergebnisse für „usa, mobile“ usw. Weitere Informationen zur Berechnung von Klicks, Impressionen usw. finden Sie in der Dokumentation zum Bericht „Suchanalyse“.
Die Ergebnisse werden nach der Anzahl der Klicks in absteigender Reihenfolge sortiert, es sei denn, Sie gruppieren nach Datum. In diesem Fall werden die Ergebnisse nach Datum in aufsteigender Reihenfolge (älteste zuerst, neueste zuletzt) sortiert. Bei einem Gleichstand zwischen zwei Zeilen ist die Sortierreihenfolge beliebig.
Die maximale Anzahl von Werten, die zurückgegeben werden können, finden Sie unter dem Attribut rowLimit in der Anfrage.
{
"rows": [
{
"keys": [
string
],
"clicks": double,
"impressions": double,
"ctr": double,
"position": double
}
],
"responseAggregationType": string
}
| Property-Name | Wert | Beschreibung | Hinweise |
|---|---|---|---|
rows[] |
list |
Eine Liste von Zeilen, gruppiert nach den Schlüsselwerten in der in der Abfrage angegebenen Reihenfolge. | |
rows[].keys[] |
list |
Eine Liste der Dimensionswerte für die Zeile, gruppiert nach den Dimensionen in der Anfrage, in der in der Anfrage angegebenen Reihenfolge. | |
rows[].clicks |
double |
Anzahl der Klicks für die Zeile. | |
rows[].impressions |
double |
Anzahl an Impressionen für die Zeile. | |
rows[].ctr |
double |
Klickrate (CTR) für die Zeile. Die Werte reichen von 0 bis einschließlich 1, 0. | |
rows[].position |
double |
Durchschnittliche Position in den Suchergebnissen | |
responseAggregationType |
string |
Die Art und Weise, wie die Ergebnisse aggregiert wurden.In der Hilfe erfahren Sie, wie Daten je nach Website oder Seite unterschiedlich berechnet werden.
Zulässige Werte sind:
|
Jetzt testen
Verwenden Sie den unten angegebenen APIs Explorer, um diese Methode für Livedaten aufzurufen und die Antwort einzusehen.