Search Analytics: query

Erfordert Autorisierung

Fragen Sie Ihre Daten zum Traffic über das Suchnetzwerk mit von Ihnen definierten Filtern und Parametern ab. 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 weggelassen. 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 zwar für den gewünschten Zeitraum.

Die Ergebnisse sind nach der Anzahl Klicks absteigend sortiert. Wenn zwei Zeilen dieselbe Anzahl Klicks haben, werden sie in beliebiger Reihenfolge sortiert.

Ein Beispiel für den Aufruf dieser Methode finden Sie im Python-Beispiel.

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.

Informationen zu den Einschränkungen bei der Menge der verfügbaren Daten

JSON-POST-Beispiel:
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 ist. 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
        }
      ],
      "filterLists": [
        {
          "dimension": string,
          "expressions": [
            string
          ]
        }
      ]
    }
  ],
  "aggregationType": string,
  "rowLimit": integer,
  "startRow": integer
}
Name der Eigenschaft Wert Beschreibung Hinweise
startDate string [Erforderlich] Startdatum des angeforderten Zeitraums im Format JJJJ-MM-TT, in PT-Zeit (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, 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 diese Dimensionen angeben. Sie können jeden Dimensionsnamen in dimensionFilterGroups[].filters[].dimension sowie „date“ und „hour“ verwenden. Die Werte der Gruppierungsdimensionen 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 zusammengefasst. Die Anzahl der Dimensionen, nach denen Sie gruppieren können, ist nicht begrenzt. Sie können jedoch nicht zweimal nach derselben Dimension gruppieren. Beispiel: [Land, Gerät]
searchType string Verworfen, verwenden Sie stattdessen type
type string [Optional] Filtern Sie die Ergebnisse nach dem folgenden Typ:
  • „discover“: Discover-Ergebnisse
  • „googleNews“: Ergebnisse von news.google.com und aus der Google News App für Android und iOS. Ergebnisse vom Tab „News“ in der Google Suche sind nicht enthalten.
  • „news“: Suchergebnisse auf dem Tab „News“ in der Google Suche.
  • „image“: Suchergebnisse auf dem Tab „Bilder“ in der Google Suche.
  • „video“: Suchergebnisse für Videos
  • „web“: [Standard] Die Ergebnisse werden auf den kombinierten Tab („Alle“) in der Google Suche beschränkt. Discover- oder Google News-Ergebnisse sind nicht enthalten.
  • „webMultimodal“: Suchergebnisse von Google Lens, Circle to Search auf Android-Geräten und Bilduploads in der Google Suche.
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 ob mindestens einer übereinstimmen muss.
dimensionFilterGroups[].groupType string Gibt an, ob alle Filter in dieser Gruppe „true“ zurückgeben müssen („and“) oder ob ein oder mehrere 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, 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 sind:
  • „country“: Filtert nach dem angegebenen Land, das durch den dreistelligen Ländercode (ISO 3166-1 alpha-3) angegeben wird.
  • „device“: Filtert die Ergebnisse nach dem angegebenen Gerätetyp. Unterstützte Werte:
    • DESKTOP
    • MOBIL
    • TABLET
  • „page“: Filtert nach dem angegebenen URI-String.
  • „query“: Filtert nach dem angegebenen Abfragestring.
  • „searchAppearance“: Nach einem bestimmten Suchergebnis-Spezialformat filtern. Wenn Sie eine Liste der verfügbaren Werte sehen möchten, führen Sie eine Abfrage aus, die nach „searchAppearance“ gruppiert ist. Die vollständige Liste der Werte und Beschreibungen finden Sie auch in der Hilfedokumentation.
  • „brandedClassification“: Filtert die Ergebnisse nach der angegebenen Klassifizierung für markenbezogene Suchanfragen (nur der Operator „equals“ wird unterstützt). Das Filtern oder Gruppieren nach „brandedClassification“ kann nicht mit einem „query“-Filter in derselben Anfrage kombiniert werden. Die Daten sind ab dem 21. Februar 2026 und nur für Properties auf oberster Ebene mit ausreichendem Suchanfragen- und Impressionsvolumen verfügbar (siehe Ankündigung zu markenbezogenen Suchanfragen). Unterstützte Werte:
    • MARKENBEZOGEN
    • NON_BRANDED
dimensionFilterGroups[].filters[].operator string [Optional] Wie der angegebene Wert mit dem Dimensionswert für die Zeile übereinstimmen (oder nicht übereinstimmen) muss.

Zulässige Werte sind:
  • „contains“: Der Zeilenwert muss Ihren Ausdruck enthalten oder ihm entsprechen (Groß-/Kleinschreibung wird nicht berücksichtigt).
  • „equals“: [Standard] Der Ausdruck muss genau mit dem Zeilenwert übereinstimmen (bei Seiten- und Abfragedimensionen wird zwischen Groß- und Kleinschreibung unterschieden).
  • „notContains“: Der Zeilenwert darf den Ausdruck weder als Teilstring noch als vollständige Übereinstimmung (ohne Berücksichtigung der Groß-/Kleinschreibung) enthalten.
  • „notEquals“: Der Ausdruck darf nicht genau mit dem Zeilenwert übereinstimmen (bei Seiten- und Suchanfragedimensionen wird zwischen Groß- und Kleinschreibung unterschieden).
  • „includingRegex“: Ein regulärer Ausdruck in RE2-Syntax, der übereinstimmen muss.
  • „excludingRegex“: Ein regulärer Ausdruck in RE2-Syntax, der nicht übereinstimmen darf.
dimensionFilterGroups[].filters[].expression string Der Wert, den der Filter je nach Operator abgleichen oder ausschließen soll.
dimensionFilterGroups[].filterLists[] list [Optional] Null oder mehr Dimensionsfilter mit mehreren Werten, die für die Zeile getestet werden sollen. Im Gegensatz zu filters[], das einen einzelnen Wert pro Eintrag abgleicht, ermöglicht filterLists[] den Abgleich mit mehreren genau passenden Werten für eine einzelne Dimension in einem Filter. Eine Zeile entspricht einer Filterliste, wenn ihr Wert für die angegebene dimension mit einer der angegebenen expressions übereinstimmt. Beachten Sie, dass in einer einzelnen Anfrage nicht gleichzeitig in filters und filterLists nach derselben Dimension gefiltert werden kann.
dimensionFilterGroups[].filterLists[].dimension string [Erforderlich] Die Dimension, auf die diese Filterliste angewendet wird.

Zulässige Werte sind:
  • „country“: Filtert nach den angegebenen Ländern. Verwenden Sie dazu dreistellige Ländercodes (ISO 3166-1 alpha-3).
  • „device“: Filtert nach den angegebenen Gerätetypen (DESKTOP, MOBILE, TABLET).
dimensionFilterGroups[].filterLists[].expressions[] list [Erforderlich] Die Liste der Werte (string), nach denen gefiltert werden soll.
aggregationType string

[Optional] Wie Daten aggregiert werden. Wenn die Daten nach Property zusammengefasst werden, werden alle Daten für dieselbe Property zusammengefasst. Wenn die Daten nach Seite zusammengefasst werden, werden alle Daten nach kanonischem URI zusammengefasst. Wenn Sie nach Seite filtern oder gruppieren, wählen Sie „Automatisch“ aus. Andernfalls können Sie entweder nach Property oder nach Seite zusammenfassen, je nachdem, wie Ihre Daten berechnet werden sollen. In der Hilfedokumentation erfahren Sie, wie Daten nach Website und nach 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, erhalten Sie einen Fehler. Die API ändert den Aggregationstyp nie, wenn der angeforderte Typ ungültig ist.

Zulässige Werte sind:
  • „auto“: [Standard] Der Dienst entscheidet, welcher Aggregationstyp am besten geeignet ist.
  • „byNewsShowcasePanel“: Werte nach News Showcase-Bereich aggregieren. Dies 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“: Werte nach URI aggregieren.
  • „byProperty“: Werte nach Property zusammenfassen. Nicht unterstützt für type=discover oder type=googleNews
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 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“ (Groß-/Kleinschreibung wird nicht berücksichtigt) angegeben ist, enthalten die Daten aktuelle Daten. Wenn „final“ (Groß-/Kleinschreibung wird nicht berücksichtigt) oder wenn dieser Parameter weggelassen wird, enthalten die zurückgegebenen Daten nur endgültige Daten. Wenn „hourly_all“ (Groß-/Kleinschreibung wird nicht berücksichtigt), enthalten die Daten eine stündliche Aufschlüsselung. Dies weist darauf hin, dass die stündlichen Daten unvollständig sind und beim Gruppieren nach der API-Dimension HOUR verwendet werden sollten.

Antwort

Die Ergebnisse werden nach den in der Anfrage angegebenen Dimensionen gruppiert. Alle Werte mit demselben Satz von Dimensionswerten werden in einer einzigen Zeile gruppiert. Wenn Sie beispielsweise nach der Dimension „Land“ 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“, alle Ergebnisse für „USA, Mobilgerät“ usw. gruppiert. In der Dokumentation zum Bericht „Suchanalyse“ finden Sie weitere Informationen dazu, wie Klicks, Impressionen usw. berechnet werden und was sie bedeuten.

Die Ergebnisse werden nach der Anzahl 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). Wenn zwei Zeilen denselben Wert haben, ist die Sortierreihenfolge beliebig.

In der Anfrage finden Sie die Property rowLimit, die die maximale Anzahl von Werten angibt, 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, in der in der Anfrage angegebenen Reihenfolge.
rows[].clicks double Anzahl Klicks für die Zeile.
rows[].impressions double Anzahl der Impressionen für die Zeile.
rows[].ctr double Klickrate (CTR) für die Zeile. Die Werte reichen von 0 bis 1, 0 (einschließlich).
rows[].position double Durchschnittliche Position in den Suchergebnissen.
responseAggregationType string Wie die Ergebnisse aggregiert wurden. In der Hilfe erfahren Sie, wie sich die Berechnung von Daten nach Website von der Berechnung nach Seite unterscheidet.

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

Ein Objekt, das mit Ihren Abfrageergebnissen zurückgegeben werden kann und Kontext zum Status der Daten liefert.

Wenn Sie aktuelle Daten anfordern (mit all oder hourly_all für dataState), können einige der zurückgegebenen Zeilen unvollständige Daten enthalten. Das bedeutet, dass die Daten noch erfasst und verarbeitet werden. Anhand dieses Metadatenobjekts können Sie genau erkennen, wann die Werbeunterbrechung beginnt und endet.

Alle in diesem Objekt angegebenen Datums- und Uhrzeitangaben beziehen sich auf die Zeitzone America/Los_Angeles.

Das spezifische Feld, das in diesem Objekt zurückgegeben wird, hängt davon ab, wie Sie Ihre Daten in der Anfrage gruppiert haben:

  • first_incomplete_date (string): Das erste Datum, für das die Daten noch erfasst und verarbeitet werden, im Format YYYY-MM-DD (erweitertes lokales Datumsformat nach ISO-8601).

    Dieses Feld wird nur ausgefüllt, wenn der dataState der Anfrage all ist, die Daten nach date gruppiert sind und der angeforderte Zeitraum unvollständige Datenpunkte enthält.

    Alle Werte nach dem first_incomplete_date können sich noch merklich ändern.

  • first_incomplete_hour (string): Die erste Stunde, für die die Daten noch erfasst und verarbeitet werden, im Format YYYY-MM-DDThh:mm:ss[+|-]hh:mm (ISO-8601-Format für erweitertes Offset-Datum und -Uhrzeit).

    Dieses Feld wird nur ausgefüllt, wenn die dataState der Anfrage hourly_all ist, die Daten nach hour gruppiert sind und der angeforderte Zeitraum unvollständige Datenpunkte enthält.

    Alle Werte nach dem first_incomplete_hour können sich noch merklich ändern.

Testen!

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