Autorisierung erforderlich
Sie können Ihre Suchdaten mit von Ihnen definierten Filtern und Parametern abfragen. Die Methode gibt null oder mehr Zeilen zurück, die nach den von Ihnen definierten Zeilenschlüsseln (Dimensionen) gruppiert sind. Sie müssen einen Datumsbereich von einem oder mehreren Tagen definieren.
Wenn das Datum eine der Dimensionen ist, werden alle Tage ohne Daten aus der Ergebnisliste entfernt. 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 geben Sie den gewünschten Datumsbereich an.
Die Ergebnisse werden in absteigender Reihenfolge nach der Anzahl Klicks sortiert. Wenn zwei Zeilen die gleiche Anzahl Klicks haben, werden sie in einer beliebigen Reihenfolge sortiert.
Im Python-Beispiel erfahren Sie, wie Sie diese Methode aufrufen.
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.
Weitere Informationen zu den Einschränkungen der verfügbaren Datenmenge.
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
}| Name der Eigenschaft | Wert | Beschreibung | Hinweise |
|---|---|---|---|
startDate |
string |
[Erforderlich] Startdatum des angeforderten Datumsbereichs im Format JJJJ-MM-TT in PT (UTC - 7:00/8:00). Muss kleiner oder gleich dem Enddatum sein. Dieser Wert ist im Bereich enthalten. | |
endDate |
string |
[Erforderlich] Enddatum des angeforderten Datumsbereichs 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 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 Gruppierungsdimension 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 kombiniert. Die Anzahl der Dimensionen, nach denen Sie gruppieren können, ist nicht begrenzt. Sie können jedoch nicht zweimal nach derselben Dimension gruppieren. Beispiel : [country, device] | |
searchType |
string |
Veraltet, verwenden Sie stattdessen type
|
|
type |
string |
[Optional] Ergebnisse nach dem folgenden Typ filtern:
|
|
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 mindestens einer. | |
dimensionFilterGroups[].groupType |
string |
Gibt an, ob alle Filter in dieser Gruppe „true“ zurückgeben müssen („and“) oder ob mindestens einer „true“ zurückgeben muss (noch nicht unterstützt).
Zulässige Werte:
|
|
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:
|
|
dimensionFilterGroups[].filters[].operator |
string |
[Optional] Gibt an, wie der angegebene Wert mit dem Dimensionswert für die Zeile übereinstimmen muss (oder nicht übereinstimmen darf).
Zulässige Werte:
|
|
dimensionFilterGroups[].filters[].expression |
string |
Der Wert, mit dem der Filter übereinstimmen oder den er ausschließen soll, je nach Operator. | |
aggregationType |
string |
[Optional] Gibt an, wie Daten zusammengefasst werden. Wenn nach Property zusammengefasst wird, werden alle Daten für dieselbe Property zusammengefasst. Wenn nach Seite zusammengefasst wird, werden alle Daten nach kanonischer URI zusammengefasst. Wenn Sie nach Seite filtern oder gruppieren, wählen Sie „auto“ aus. Andernfalls können Sie je nach gewünschter Berechnung der Daten entweder nach Property oder nach Seite zusammenfassen. In der Hilfedokumentation erfahren Sie, wie Daten je nach Website oder 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, wird ein Fehler zurückgegeben. Die API ändert den Aggregationstyp niemals, wenn der angeforderte Typ ungültig ist. Zulässige Werte:
|
|
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: 0] Der nullbasierte Index der ersten Zeile in der Antwort. Muss eine nicht negative Zahl sein. Wenn startRow die Anzahl der Ergebnisse für die Abfrage übersteigt, ist die Antwort erfolgreich, enthält aber keine Zeilen. |
|
dataState |
string |
[Optional] Wenn "all" (ohne Berücksichtigung der Groß-/Kleinschreibung) angegeben ist, enthalten die Daten aktuelle Daten. Wenn „final“ (ohne Berücksichtigung der Groß-/Kleinschreibung) angegeben ist oder dieser Parameter weggelassen wird, enthalten die zurückgegebenen Daten nur endgültige Daten. Wenn „hourly_all“ (ohne Berücksichtigung der Groß-/Kleinschreibung) angegeben ist, enthalten die Daten eine stündliche Aufschlüsselung. Dies gibt an, dass die stündlichen Daten Teildaten enthalten und verwendet werden sollten, wenn nach der API-Dimension „HOUR“ gruppiert wird. |
Antwort
Die Ergebnisse werden nach den in der Anfrage angegebenen Dimensionen gruppiert. Alle Werte mit derselben Kombination von Dimensionswerten werden in einer einzigen Zeile gruppiert. Wenn Sie beispielsweise nach der Dimension „country“ 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“ zusammengefasst, alle Ergebnisse für „usa, mobile“ zusammengefasst usw. In der Dokumentation zum Bericht „Suchanalyse“ erfahren Sie, wie Klicks, Impressionen usw. berechnet werden und was sie bedeuten.
Die Ergebnisse werden in absteigender Reihenfolge nach der Anzahl der Klicks sortiert, es sei denn, Sie gruppieren nach Datum. In diesem Fall werden die Ergebnisse in aufsteigender Reihenfolge nach Datum sortiert (älteste zuerst, neueste zuletzt). Wenn zwei Zeilen gleich sind, ist die Sortierreihenfolge beliebig.
In der Eigenschaft „rowLimit“ in der Anfrage erfahren Sie, wie viele Werte maximal zurückgegeben werden können.
{
"rows": [
{
"keys": [
string
],
"clicks": double,
"impressions": double,
"ctr": double,
"position": double
}
],
"responseAggregationType": string
}| Name der Eigenschaft | Wert | Beschreibung | Hinweise |
|---|---|---|---|
rows[] |
list |
Eine Liste von Zeilen, die nach den Schlüsselwerten in der Reihenfolge gruppiert sind, die in der Abfrage angegeben ist. | |
rows[].keys[] |
list |
Eine Liste der Dimensionswerte für diese Zeile, gruppiert nach den Dimensionen in der Anfrage und in der in der Anfrage angegebenen Reihenfolge. | |
rows[].clicks |
double |
Anzahl Klicks für die Zeile. | |
rows[].impressions |
double |
Anzahl an Impressionen für die Zeile. | |
rows[].ctr |
double |
Klickrate (Click-through-Rate, CTR) für die Zeile. Die Werte liegen zwischen 0 und 1, 0 (einschließlich). | |
rows[].position |
double |
Durchschnittliche Position in den Suchergebnissen. | |
responseAggregationType |
string |
Gibt an, wie die Ergebnisse zusammengefasst wurden.Siehedie Hilfedokumentation , um zu erfahren, wie Daten je nach Website oder Seite unterschiedlich berechnet werden.
Zulässige Werte:
|
|
metadata |
object |
Ein Objekt, das mit den Abfrageergebnissen zurückgegeben werden kann und Kontext zum Status der Daten bietet. Wenn Sie aktuelle Daten anfordern (mit Alle in diesem Objekt angegebenen Datums- und Zeitangaben 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.