Search Analytics: query

Autorisierung erforderlich

Sie können die Daten zu den 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 Zeitraum von einem oder mehreren Tagen festlegen.

Wenn das Datum eine der Dimensionen ist, werden alle Tage ohne Daten aus der Ergebnisliste ausgeschlossen. 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 unterliegt internen Einschränkungen der Search Console und garantiert nicht, dass alle Datenzeilen zurückgegeben werden, sondern nur die ersten.

Weitere Informationen zu Limits für die Menge der verfügbaren Daten

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).

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
}
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 können.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 für jede Ergebniszeile einen eindeutigen Schlüssel zu erstellen. Wenn keine Dimensionen angegeben sind, werden alle Werte in einer einzigen Zeile zusammengefasst. Sie können beliebig viele Dimensionen gruppieren, jedoch nicht zweimal nach derselben Dimension. Beispiel: [Land, Gerät]
searchType string Eingestellt. Verwende stattdessen type.
type string [Optional] Filtern Sie die Ergebnisse nach dem folgenden Typ:
  • discover“: Discover-Ergebnisse
  • googleNews“: Ergebnisse von news.google.com und der Google News App für Android und iOS. Ergebnisse vom Tab „News“ in der Google Suche sind nicht enthalten.
  • news“: Suchergebnisse aus dem Tab „News“ in der Google Suche.
  • image“: Suchergebnisse aus dem Tab „Bilder“ in der Google Suche.
  • video“: Videosuchergebnisse
  • web“: [Standard] Filtert die Ergebnisse nach dem Tab „Alle“ in der Google Suche. Discover- oder Google News-Ergebnisse sind nicht enthalten.
dimensionFilterGroups[] list [Optional] Null oder mehr Gruppen von Filtern, die auf die Werte der Dimensionsgruppierung angewendet werden sollen. Alle Filtergruppen müssen übereinstimmen, damit in der Antwort eine Zeile zurückgegeben wird. Innerhalb einer Filtergruppe können Sie angeben, ob alle oder mindestens einer der Filter übereinstimmen muss.
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:
  • "and": Alle Filter in der Gruppe müssen „true“ zurückgeben, damit die Filtergruppe „true“ ist.
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:
  • country“: Filtert anhand des angegebenen Landes gemäß dem dreistelligen Ländercode (ISO 3166-1 alpha-3).
  • device“: Ergebnisse nach dem angegebenen Gerätetyp filtern. Unterstützte Werte:
    • DESKTOP-COMPUTER
    • MOBILGERÄT
    • TABLET
  • "page": Filtert anhand des angegebenen URI-Strings.
  • "query": Filtert anhand des angegebenen Abfragestrings.
  • searchAppearance“: Nach einer bestimmten Suchergebnisfunktion filtern. Wenn Sie eine Liste der verfügbaren Werte aufrufen möchten, führen Sie eine nach „searchAppearance“ gruppierte Abfrage aus.
dimensionFilterGroups[].filters[].operator string [Optional] Gibt an, ob der angegebene Wert mit dem Dimensionswert für die Zeile übereinstimmen bzw. nicht übereinstimmen muss.

Zulässige Werte sind:
  • contains“: Der Zeilenwert muss Ihren Ausdruck entweder enthalten oder diesem entsprechen (Groß-/Kleinschreibung wird nicht berücksichtigt).
  • "equals": [Standard] Der Ausdruck muss genau dem Zeilenwert entsprechen (Groß-/Kleinschreibung für Seiten- und Abfragedimensionen beachten).
  • "notContains": Der Zeilenwert darf Ihren Ausdruck weder als Teilstring noch als vollständige Übereinstimmung (ohne Berücksichtigung der Groß-/Kleinschreibung) enthalten.
  • "notEquals": Der Ausdruck darf nicht genau dem Zeilenwert entsprechen (Groß-/Kleinschreibung für Seiten- und Abfragedimensionen beachten).
  • "includingRegex": Ein regulärer Ausdruck der RE2-Syntax, der abgeglichen werden muss.
  • "excludingRegex": Ein regulärer Ausdruck der RE2-Syntax, 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 Zusammenfassung nach Property werden alle Daten für dieselbe Property zusammengefasst. Wenn sie nach Seite zusammengefasst werden, werden alle Daten nach dem kanonischen URI zusammengefasst. Wenn Sie nach Seite filtern oder gruppieren, wählen Sie die Option „Automatisch“ aus. Andernfalls können Sie abhängig davon, wie Ihre Daten berechnet werden sollen, entweder nach Property oder nach Seite aggregieren. In der Hilfe erfahren Sie, wie Daten je nach Website und 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, entspricht der Zusammenfassungstyp im Ergebnis dem angeforderten Typ. Wenn Sie einen ungültigen Typ anfordern, wird eine Fehlermeldung angezeigt. Die API ändert den Zusammenfassungstyp nie, wenn der angeforderte Typ ungültig ist.

Zulässige Werte sind:
  • "auto": [Standard] Der Dienst entscheidet über den geeigneten Aggregationstyp.
  • byNewsShowcasePanel“: Werte nach News Showcase-Bereich aggregieren. Dieser Parameter 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 einem anderen searchAppearance filtern, können Sie nicht nach byNewsShowcasePanel aggregieren.
  • "byPage": Aggregiert Werte nach URI.
  • 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: 1.000] Die maximale Anzahl von Zeilen, die zurückgegeben werden sollen. Mit dem Offset startRow können Sie durch die Ergebnisse blättern.
startRow integer [Optional. Der Standardwert ist 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 überschreitet, ist die Antwort eine erfolgreiche Antwort mit null Zeilen.
dataState string [Optional] Bei der Einstellung „all“ (Groß-/Kleinschreibung wird nicht berücksichtigt) enthalten die Daten aktuelle Daten. Wenn „final“ (Groß-/Kleinschreibung nicht berücksichtigt) 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 gruppiert. Wenn Sie beispielsweise nach der Dimension „Land“ gruppieren, werden alle Ergebnisse für „usa“ und alle Ergebnisse für „mdv“ gruppiert usw. Wenn Sie nach Land und Gerät gruppieren, werden alle Ergebnisse für „USA, Tablet“ gruppiert, alle Ergebnisse für „USA, Mobilgerät“ werden usw. gruppiert. Weitere Informationen zur Berechnung von Klicks und Impressionen sowie zu deren Bedeutung 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 sortiert (älteste zuerst, neueste zuletzt). 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, die nach den Schlüsselwerten in der in der Abfrage angegebenen Reihenfolge gruppiert sind.
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 (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 Hilfe können Sie nachlesen, 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.