Search Analytics: query

Autorisierung erforderlich

Daten zu Suchzugriffen mithilfe von 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 Zeitraum von einem oder mehreren Tagen festlegen.

Wenn das Datum eine der Dimensionen ist, werden alle Tage ohne Daten aus der Ergebnisliste ausgelassen. Um herauszufinden, an welchen Tagen Daten vorhanden sind, stellen Sie eine Abfrage ohne Filter, die nach Datum für den gewünschten Zeitraum gruppiert sind.

Die Ergebnisse werden absteigend nach der Klickanzahl sortiert. Wenn zwei Zeilen dieselbe Klickanzahl 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 garantiert nicht, dass alle Datenzeilen zurückgegeben werden, sondern nur die obersten.

Informationen zur Beschränkung der verfügbaren Datenmenge

Beispiel für einen 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 sie in der Search Console definiert wurde. 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).

Umfang
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
}
Attributname Wert Beschreibung Hinweise
startDate string [Erforderlich] Startdatum des angeforderten Zeitraums im Format JJJJ-MM-TT im Format 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 Zeitraums im Format JJJJ-MM-TT (UTC -7:80 Uhr) 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 und „Datum“ können Sie einen beliebigen Dimensionsnamen verwenden.Die Werte für die 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, aber Sie können nicht nach derselben Dimension gruppieren. Beispiel: [Land, Gerät]
searchType string Veraltet, stattdessen type verwenden
type string [Optional] Filtern Sie die Ergebnisse nach folgendem Typ:
  • „discover“: Ergebnisse entdecken
  • „googleNews“: Ergebnisse von news.google.com und der Google News App für Android und iOS. Enthält keine Ergebnisse vom Tab „News“ in der Google Suche.
  • „news“: Suchergebnisse auf dem Tab „News“ in der Google Suche.
  • „image“: Suchergebnisse auf dem Tab „Bild“ in der Google Suche.
  • „video“: Videosuchergebnisse
  • „web“: [Standard] Ergebnisse werden in der Google Suche nach dem Tab „Alle“ gefiltert. Discover- oder Google News-Ergebnisse werden nicht berücksichtigt.
dimensionFilterGroups[] list [Optional] Null oder mehr Filtergruppen, die auf die Werte der Dimensionsgruppierung angewendet werden. 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 übereinstimmen muss.
dimensionFilterGroups[].groupType string Gibt an, ob alle Filter in dieser Gruppe „wahr“ („und“) oder einen oder mehrere „wahr“ zurückgeben müssen (noch nicht unterstützt).

Folgende Werte sind zulässig:
  • „and“: Alle Filter in der Gruppe müssen für die Filtergruppe „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. Max. 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 allen hier aufgeführten Dimensionen filtern, auch wenn Sie nicht nach dieser Dimension gruppieren.

Folgende Werte sind zulässig:
  • „country“: Filter für das angegebene Land gemäß dem aus drei Buchstaben bestehenden Ländercode (ISO 3166-1 alpha-3).
  • „device“: Filtert Ergebnisse nach dem angegebenen Gerätetyp. Unterstützte Werte:
    • DESKTOP-COMPUTER
    • MOBILGERÄTE
    • TABELLE
  • „page“: Filtert nach dem angegebenen URI-String.
  • „query“: Filtert nach dem angegebenen Abfragestring.
  • „searchAppearance“: Nach einer bestimmten Suchergebnisfunktion filtern. Wenn Sie eine Liste der verfügbaren Werte aufrufen möchten, führen Sie eine Abfrage aus, die nach „searchDarstellung“ gruppiert ist.
dimensionFilterGroups[].filters[].operator string [Optional] Gibt an, wie der angegebene Wert mit dem Dimensionswert für die Zeile übereinstimmen muss.

Folgende Werte sind zulässig:
  • „contains“: Der Zeilenwert muss entweder Ihren Ausdruck enthalten oder mit ihm übereinstimmen (Groß-/Kleinschreibung wird nicht berücksichtigt).
  • "equals": [Standard] Ihr Ausdruck muss genau dem Zeilenwert entsprechen (Groß- und Kleinschreibung bei Seiten- und Abfragedimensionen).
  • „notContains“: Der Zeilenwert darf weder einen Teilstring noch eine vollständige Übereinstimmung ohne Berücksichtigung der Groß- und Kleinschreibung enthalten.
  • „notEquals“: Ihr Ausdruck darf nicht genau dem Zeilenwert entsprechen (Groß- und Kleinschreibung bei Seiten- und Abfragedimensionen).
  • „includingRegex“: Ein regulärer RE2-Syntaxausdruck, der abgeglichen werden muss.
  • „excludingRegex“: Ein regulärer RE2-Syntax-Ausdruck, der nicht abgeglichen werden darf.
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 der Aggregation nach Property werden alle Daten für dieselbe Property zusammengefasst. Bei der Aggregation nach Seite werden alle Daten nach kanonischem URI zusammengefasst. Wenn du nach Seite filterst oder gruppierst, wähle „Automatisch“ aus. Andernfalls kannst du abhängig von der Art der Datenberechnung entweder nach Property oder nach Seite aggregieren. In der Hilfe findest du Informationen dazu, wie Daten nach Website oder Seite unterschiedlich berechnet werden.

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

Wenn Sie einen anderen Wert als „auto“ angeben, stimmt der Zusammenfassungstyp im Ergebnis mit dem angeforderten Typ überein. Wenn Sie einen ungültigen Typ anfordern, wird eine Fehlermeldung angezeigt. Die API ändert niemals den Zusammenfassungstyp, wenn der angeforderte Typ ungültig ist.

Zulässige Werte:
  • "auto": [Standard] Der Dienst soll den geeigneten Zusammenfassungstyp auswählen.
  • „byPage“: Werte nach URI aggregieren
  • „byProperty“: Werte nach Property aggregieren Nicht unterstützt für type=discover oder type=googleNews
rowLimit integer [Optional; Gültiger Bereich ist 1–25.000; Standard ist 1.000] Die maximale Anzahl von Zeilen, die zurückgegeben werden sollen. Verwenden Sie den startRow-Versatz, 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“ (keine Berücksichtigung der Groß-/Kleinschreibung) erfolgt, enthalten die Daten aktuelle Daten. Wenn „final“ (keine Unterscheidung zwischen Groß- und Kleinschreibung) oder kein Wert angegeben 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 Dimension „Land“ gruppieren, werden alle Ergebnisse für „usa“ in Gruppen zusammengefasst, alle Ergebnisse für „mdv“ zusammengefasst usw. Wenn Sie nach Land und Gerät gruppieren, werden alle Ergebnisse für „usa, tablet“ gruppiert, alle Ergebnisse für „usa, mobile“ usw. In der Dokumentation zum Bericht „Suchanalyse“ erfahren Sie, wie Klicks und Impressionen 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 nach Datum in absteigender Reihenfolge sortiert (älteste zuerst). Bei einem Gleichstand zwischen zwei Zeilen kann die Sortierreihenfolge beliebig gewählt werden.

In der Anfrage wird die Eigenschaft rowLimit aufgeführt, um zu erfahren, wie viele Werte maximal zurückgegeben werden können.

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}
Attributname 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 Klickanzahl für die Zeile.
rows[].impressions double Anzahl der Impressionen für die Zeile
rows[].ctr double Die Klickrate für die Zeile. Die Werte reichen von 0 bis einschließlich 1, 0.
rows[].position double Durchschnittliche Position in den Suchergebnissen.
responseAggregationType string Wie die Ergebnisse aggregiert wurden.In der Hilfedokumentation erfahren Sie, wie die Daten je nach Website und Seite unterschiedlich berechnet werden.

Folgende Werte sind zulässig:
  • „auto“
  • „byPage“: Die Ergebnisse wurden nach Seite zusammengefasst.
  • „byProperty“: Die Ergebnisse wurden nach Property zusammengefasst.

Testen!

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