Search Analytics: query

Autorisierung erforderlich

Sie können Ihre Daten zu Suchzugriffen 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 festlegen.

Wenn „Datum“ eine der Dimensionen ist, werden alle Tage ohne Daten aus der Ergebnisliste ausgeschlossen. Um zu erfahren, für welche Tage Daten verfügbar sind, geben Sie für den gewünschten Zeitraum eine Abfrage ohne nach Datum gruppierte Filter aus.

Die Ergebnisse werden absteigend nach der Anzahl der Klicks sortiert. Wenn zwei Zeilen die gleiche Anzahl an Klicks aufweisen, werden sie beliebig sortiert.

Informationen zum Aufrufen dieser Methode finden Sie im Python-Beispiel.

Die API unterliegt internen Einschränkungen der Search Console und garantiert nicht, dass alle Datenzeilen zurückgegeben werden, sondern nur die obersten.

Hier finden Sie Informationen zu den Limits für die verfügbare Datenmenge.

Beispiel für JSON POST: 
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"]
}
Jetzt testen

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] Das Startdatum des angeforderten Zeitraums im Format JJJJ-MM-TT in PT-Zeit (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-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 die Dimensionen angeben.Sie können einen beliebigen Dimensionsnamen in dimensionFilterGroups[].filters[].dimension 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 einzelnen Zeile zusammengefasst. Es gibt keine Begrenzung für die Anzahl der Dimensionen, nach denen Sie gruppieren können. Es ist jedoch nicht möglich, zweimal nach derselben Dimension zu gruppieren. Beispiel: [Land, Gerät]
searchType string Eingestellt, stattdessen type verwenden
type string [Optional] Filtern Sie Ergebnisse nach dem folgenden Typ:
  • „discover“: Discover-Ergebnisse
  • „googleNews“: Ergebnisse von news.google.com und der Google News App unter Android und iOS. Enthält keine Ergebnisse auf dem Tab „News“ in der Google Suche.
  • „news“: Suchergebnisse aus dem Tab „News“ in der Google Suche.
  • „image“: Suchergebnisse aus dem Tab „Bild“ in der Google Suche.
  • „video“: Videosuchergebnisse
  • „web“: [Standard] Filtert Ergebnisse auf den kombinierten Tab „Alle“ in der Google Suche. Discover- oder Google News-Ergebnisse werden nicht berücksichtigt.
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 Filtergruppe können Sie angeben, ob alle Filter oder mindestens ein Filter übereinstimmen muss.
dimensionFilterGroups[].groupType string Gibt an, ob alle Filter in dieser Gruppe „true“ („and“) oder mindestens „true“ zurückgeben müssen (noch nicht unterstützt).

Zulässige Werte sind:
  • "and": Alle Filter in der Gruppe müssen für die Filtergruppe den Wert "true" zurückgeben.
dimensionFilterGroups[].filters[] list [Optional] Null oder mehr Filter zum Testen 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:
  • "country": Nach dem angegebenen Land gemäß dem aus drei Buchstaben bestehenden Ländercode (ISO 3166-1 alpha-3) filtern
  • „device“: Filtert Ergebnisse nach dem angegebenen Gerätetyp. Unterstützte Werte:
    • DESKTOP-COMPUTER
    • MOBILGERÄTE
    • TABLET
  • „page“: Filtert nach dem angegebenen URI-String.
  • "query": Filtert nach dem angegebenen Abfragestring.
  • „searchAppearance“: Nach einer bestimmten Suchergebnisfunktion filtern. Führen Sie eine nach „searchAppearance“ gruppierte Abfrage aus, um eine Liste der verfügbaren Werte aufzurufen.
dimensionFilterGroups[].filters[].operator string [Optional] Gibt an, wie der angegebene Wert mit dem Dimensionswert für die Zeile übereinstimmen muss oder nicht.

Zulässige Werte sind:
  • "contains": Der Zeilenwert muss entweder Ihren Ausdruck enthalten oder diesem entsprechen (Groß-/Kleinschreibung wird nicht berücksichtigt).
  • "equals": [Standard] Der Ausdruck muss genau mit dem Zeilenwert übereinstimmen (bei den Seiten- und Abfragedimensionen wird zwischen Groß- und Kleinschreibung unterschieden).
  • "notContains": Der Zeilenwert darf den Ausdruck nicht als Teilstring oder als vollständige Übereinstimmung (Groß- und Kleinschreibung nicht berücksichtigen) enthalten.
  • "notEquals": Der Ausdruck darf nicht genau mit dem Zeilenwert übereinstimmen (bei den Seiten- und Abfragedimensionen wird zwischen Groß- und Kleinschreibung unterschieden).
  • „includingRegex“: Ein regulärer Ausdruck der RE2-Syntax, der abgeglichen werden muss.
  • „excludingRegex“: Ein regulärer Ausdruck mit RE2-Syntax, der nicht abgeglichen werden darf.
dimensionFilterGroups[].filters[].expression string Der Wert für den Filter, der je nach Operator übereinstimmt oder ausgeschlossen werden soll.
aggregationType string

[Optional] So werden Daten aggregiert. Bei der Zusammenfassung nach Property werden alle Daten für dieselbe Property zusammengefasst. Bei der Zusammenfassung nach Seite werden alle Daten über den kanonischen URI aggregiert. Wenn Sie nach Seite filtern oder gruppieren, wählen Sie „Automatisch“ aus. Andernfalls können Sie entweder nach Property oder nach Seite aggregieren, je nachdem, wie Ihre Daten berechnet werden sollen. In der Hilfedokumentation erfahren Sie, wie Daten je nach Website und Seite anders berechnet werden.

Hinweis:Wenn Sie nach Seite gruppieren oder filtern, können Sie nicht nach Property aggregieren.

Wenn Sie einen anderen Wert als „Automatisch“ angeben, entspricht der Zusammenfassungstyp im Ergebnis dem angeforderten Typ. Wenn Sie einen ungültigen Typ anfordern, erhalten Sie eine Fehlermeldung. Die API ändert den Zusammenfassungstyp niemals, wenn der angeforderte Typ ungültig ist.

Zulässige Werte sind:
  • "auto": [Standard] Der Dienst entscheidet über den geeigneten Zusammenfassungstyp.
  • „byNewsShowcasePanel“: Aggregierte Werte nach News Showcase-Bereich. Muss in Kombination mit dem Filter NEWS_SHOWCASE searchAppearance und entweder type=discover oder type=googleNews verwendet werden. Wenn Sie nach Seite gruppieren, nach Seite filtern oder nach einer anderen searchAppearance filtern, können Sie nicht nach byNewsShowcasePanel aggregieren.
  • "byPage": Aggregiert Werte nach URI.
  • „byProperty“: Aggregiert Werte nach Property. Nicht unterstützt für type=discover oder type=googleNews
rowLimit integer [Optional; gültiger Bereich ist 1–25.000; der Standardwert ist 1.000] Die maximale Anzahl der zurückzugebenden Zeilen. Verwenden Sie den Offset von 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 „alle“ ausgewählt ist (Groß-/Kleinschreibung nicht berücksichtigend), umfassen die Daten aktuelle Daten. Wenn „final“ (Groß-/Kleinschreibung nicht berücksichtigend) oder dieser Parameter weggelassen wird, enthalten die zurückgegebenen Daten nur abgeschlossene Daten.

Antwort

Die Ergebnisse werden nach den in der Anfrage angegebenen Dimensionen gruppiert. Alle Werte mit denselben Dimensionswerten werden in einer einzelnen Zeile zusammengefasst. Wenn Sie beispielsweise nach der Dimension „Land“ gruppieren, werden alle Ergebnisse für „USA“, alle Ergebnisse für „mdv“ usw. gruppiert. Wenn Sie die Ansicht nach Land und Gerät gruppieren, werden alle Ergebnisse für „USA, Tablet“ gruppiert, alle Ergebnisse für „USA, Mobilgerät“ usw. In der Dokumentation zum Bericht „Suchanalyse“ erfahren Sie, wie Klicks, Impressionen usw. berechnet werden und was sie bedeuten.

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 letzte) sortiert. Bei einem Gleichstand zwischen zwei Zeilen ist die Sortierreihenfolge beliebig.

Die Property rowLimit in der Anfrage enthält Informationen zur maximalen Anzahl von Werten, 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 und 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 (Click-through-Rate, CTR) für die Zeile. Die Werte reichen von 0 bis einschließlich 1, 0.
rows[].position double Die durchschnittliche Position in den Suchergebnissen.
responseAggregationType string Wie die Ergebnisse aggregiert wurden.In der Hilfedokumentation erfahren Sie, wie Daten je nach Website und Seite unterschiedlich berechnet werden.

Zulässige Werte sind:
  • "auto"
  • "byPage": Die Ergebnisse wurden nach Seite zusammengefasst.
  • „byProperty“: Die Ergebnisse wurden nach Property zusammengefasst.

Jetzt testen

Verwenden Sie den unten angegebenen APIs Explorer, um diese Methode für Livedaten aufzurufen und die Antwort einzusehen.