Search Analytics: query

Autorisierung erforderlich

Sie können Ihre Suchtraffic-Daten mit Filtern und Parametern abfragen, die Sie selbst definieren. 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 mindestens einem Tag definieren.

Wenn „Datum“ eine der Dimensionen ist, werden alle Tage ohne Daten aus der Ergebnisliste entfernt. Wenn Sie wissen möchten, an welchen Tagen Daten vorhanden sind, führen Sie eine Abfrage ohne Filter aus, die nach Datum gruppiert ist, und geben Sie den gewünschten Zeitraum an.

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

Python-Beispiel für den Aufruf dieser Methode

Die API unterliegt internen Einschränkungen der Search Console und gibt nicht garantiert alle Datenzeilen, sondern nur die wichtigsten zurück.

Weitere Informationen zu den Einschränkungen für die verfügbare Datenmenge

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

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 Zeitraums im Format JJJJ-MM-TT in PT-Zeit (UTC – 7:00/8:00). Muss vor dem Enddatum liegen oder ihm entsprechen. Dieser Wert ist im Bereich enthalten.
endDate string [Erforderlich] Das 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 in dimensionFilterGroups[].filters[].dimension einen beliebigen Dimensionsnamen 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 zusammengefasst. Es gibt keine Beschränkung für die Anzahl der Dimensionen, nach denen Sie gruppieren können. 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. Er enthält keine Ergebnisse vom Tab „News“ in der Google Suche.
  • „news“: Suchergebnisse vom Tab „News“ in der Google Suche.
  • „image“: Suchergebnisse vom Tab „Bilder“ in der Google Suche.
  • „video“: Video-Suchergebnisse
  • „web“: [Standard] Ergebnisse werden auf den kombinierten Tab „Alle“ in der Google Suche gefiltert. Ergebnisse aus Discover oder Google News sind nicht enthalten.
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 einer übereinstimmen müssen.
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 sind:
  • „and“: Alle Filter in der Gruppe müssen „true“ zurückgeben, damit die Filtergruppe„true“ zurückgibt.
dimensionFilterGroups[].filters[] list [Optional] Null oder mehr Filter, die für die Zeile getestet 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 sich dieser Filter bezieht. 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“: Ergebnisse nach dem angegebenen Gerätetyp filtern. Unterstützte Werte:
    • DESKTOP
    • MOBIL
    • TABLET
  • „page“: Filtert nach dem angegebenen URI-String.
  • „query“: Filtert nach dem angegebenen Suchstring.
  • „searchAppearance“: Filtert nach einem bestimmten Suchergebnis-Spezialformat. 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.
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 Ihren Ausdruck enthalten oder mit ihm übereinstimmen (Groß-/Kleinschreibung wird nicht berücksichtigt).
  • „equals“: [Standard] Ihr Ausdruck muss genau dem Zeilenwert entsprechen. Bei Seiten- und Abfragedimensionen wird zwischen Groß- und Kleinschreibung unterschieden.
  • „notContains“: Der Zeilenwert darf Ihren Ausdruck weder als Teilstring noch als (nicht case-sensitive) vollständige Übereinstimmung enthalten.
  • „notEquals“: Ihr Ausdruck darf nicht genau dem Zeilenwert entsprechen (bei Seiten- und Abfragedimensionen wird zwischen Groß- und Kleinschreibung unterschieden).
  • „includingRegex“: Ein regulärer Ausdruck in RE2-Syntax, der abgeglichen werden muss.
  • „excludingRegex“: Ein regulärer Ausdruck in RE2-Syntax, der nicht abgeglichen werden darf.
dimensionFilterGroups[].filters[].expression string Der Wert, der je nach Operator mit dem Filter übereinstimmen oder ausgeschlossen 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 sie 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 die Daten je nach gewünschter Berechnung 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 aggregieren.

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 eine Fehlermeldung. Die API ändert den Zusammenfassungstyp nie, wenn der angeforderte Typ ungültig ist.

Akzeptable Werte sind:
  • „auto“: [Standard] Der Dienst entscheidet über den geeigneten Aggregationstyp.
  • „byNewsShowcasePanel“: Werte nach News Showcase-Bereich aggregieren. Dieser Filter 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 zusammenfassen.
  • „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. Mit dem startRow-Offset können Sie durch die Ergebnisse 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 beachtet) angegeben wird, enthalten die Daten aktuelle Daten. Wenn „final“ (Groß-/Kleinschreibung wird nicht beachtet) angegeben oder dieser Parameter weggelassen wird, enthalten die zurückgegebenen Daten nur endgültige Daten. Wenn „hourly_all“ (Groß-/Kleinschreibung wird nicht berücksichtigt) angegeben ist, enthalten die Daten eine stündliche Aufschlüsselung. Das bedeutet, dass stündliche 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 Gruppe 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“ gruppiert, alle Ergebnisse für „usa, mobile“ gruppiert usw. In der Dokumentation zum Bericht „Suchanalyse“ finden Sie Informationen dazu, wie Klicks, Impressionen usw. berechnet werden und was sie bedeuten.

Die Ergebnisse werden nach 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 (ältestes zuerst, neuestes zuletzt). Bei Gleichstand zwischen zwei Zeilen ist die Sortierreihenfolge beliebig.

In der Anfrage finden Sie unter der Property rowLimit die maximale Anzahl der Werte, 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 Reihenfolge der Abfrage 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 der Impressionen für die Zeile.
rows[].ctr double Klickrate (CTR) 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. Weitere Informationen 

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

Wenn Sie aktuelle Daten anfordern (mit all oder hourly_all für dataState), können einige der zurückgegebenen Zeilen Daten enthalten, die unvollständig sind. Das bedeutet, dass die Daten noch erhoben und verarbeitet werden. Dieses Metadatenobjekt hilft Ihnen, genau zu bestimmen, wann der Zeitraum beginnt und endet.

Alle in diesem Objekt angegebenen Datums- und Zeitangaben 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 erhoben und verarbeitet werden, im Format YYYY-MM-DD (erweitertes lokales Datumsformat gemäß ISO 8601).

    Dieses Feld wird nur ausgefüllt, wenn dataState der Anfrage all ist und 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 deutlich ändern.

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

    Dieses Feld wird nur ausgefüllt, wenn dataState der Anfrage hourly_all ist und 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 deutlich ändern.

Testen!

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