CrUX API

Die CrUX API bietet Zugriff auf aggregierte Daten zur Nutzererfahrung auf Seiten- und Ursprungsebene mit geringer Latenz.

Testen!

Gängiger Anwendungsfall

Mit der CrUX API können Messwerte zur Nutzererfahrung für einen bestimmten URI abgefragt werden, z. B. „Messwerte für den Ursprung https://example.com abrufen“.

CrUX API-Schlüssel

Für die Verwendung der CrUX API ist ein Google Cloud API-Schlüssel erforderlich, der für die Nutzung von Chrome UX Report API bereitgestellt ist.

API-Schlüssel erhalten und nutzen

Schlüssel anfordern

Alternativ können Sie auf der Seite "Anmeldedaten" einen Schlüssel erstellen.

Nachdem Sie einen API-Schlüssel haben, kann Ihre Anwendung den Abfrageparameter key=yourAPIKey an alle Anfrage-URLs anhängen.

Der API-Schlüssel lässt sich sicher in URLs einbetten. Eine Codierung ist nicht notwendig.

Weitere Informationen finden Sie unter Beispielabfragen.

Datenmodell

In diesem Abschnitt wird die Struktur der Daten in Anfragen und Antworten beschrieben.

Aufnehmen

Eine einzelne Information zu einer Seite oder Website. Ein Eintrag kann Daten enthalten, die für eine Kennung und eine bestimmte Kombination von Dimensionen spezifisch sind. Ein Eintrag kann Daten für einen oder mehrere Messwerte enthalten.

IDs

Mithilfe von IDs wird festgelegt, welche Datensätze gesucht werden sollen. In CrUX sind dies Webseiten und Websites.

Ursprung

Wenn die Kennung eine Quelle ist, werden alle Daten für alle Seiten in dieser Quelle zusammengefasst. Angenommen, die Quelle http://www.example.com hatte Seiten wie in dieser Sitemap dargestellt:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Wenn Sie den Chrome UX-Bericht mit dem Ursprung http://www.example.com abfragen, werden also Daten für http://www.example.com/, http://www.example.com/foo.html und http://www.example.com/bar.html zurückgegeben, die zusammengefasst werden, da es sich bei diesen Seiten alle um Seiten mit diesem Ursprung handelt.

URLs

Wenn die Kennung eine URL ist, werden nur Daten für diese URL zurückgegeben. Sehen wir uns noch einmal die Sitemap der Quelle http://www.example.com an:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Wenn die Kennung auf „URL“ mit dem Wert „http://www.example.com/foo.html“ festgelegt ist, werden nur Daten für diese Seite zurückgegeben.

Dimensionen

Mithilfe von Dimensionen wird eine bestimmte Datengruppe angegeben, anhand derer ein Eintrag zusammengefasst wird. Ein Formfaktor von PHONE gibt beispielsweise an, dass der Eintrag Informationen zu Ladevorgängen auf einem Mobilgerät enthält. Jede Dimension hat eine bestimmte Anzahl von Werten. Wenn Sie diese Dimension nicht angeben, wird sie implizit über alle Werte aggregiert. Wenn Sie beispielsweise keinen Formfaktor angeben, enthält der Eintrag Informationen zu Belastungen, die auf einem beliebigen Formfaktor stattgefunden haben.

Formfaktor

Die Geräteklasse, mit der der Endnutzer die Seite aufgerufen hat. Dies ist eine allgemeine Geräteklasse, die in PHONE, TABLET und DESKTOP unterteilt ist.

Messwert

Messwerte werden als statistische Aggregationen, in Histogrammen, als Prozentile und als Brüche dargestellt.

Gleitkommawerte werden auf vier Dezimalstellen gerundet. Hinweis: Die cumulative_layout_shift-Messwerte sind Doubles, die als String codiert sind. Sie gelten daher nicht als Gleitkommazahlen und werden im String auf zwei Dezimalstellen gerundet.

Histogramm

Wenn Messwerte in einem Histogramm dargestellt werden, sehen Sie den Prozentsatz der Seitenladezeiten, die in bestimmte Bereiche für diesen Messwert fallen.

Ein Histogramm mit drei Bins für einen Beispielmesswert sieht so aus:

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

Diese Daten zeigen, dass der Beispielmesswert bei 38,18% der Seitenladevorgänge zwischen 0 ms und 1.000 ms gemessen wurde. Die Einheiten des Messwerts sind in diesem Histogramm nicht enthalten. In diesem Fall gehen wir von Millisekunden aus.

Bei 49,91% der Seitenladevorgänge wurde ein Messwert zwischen 1.000 ms und 3.000 ms erfasst. Bei 11,92 % der Seitenladevorgänge war der Wert höher als 3.000 ms.

Perzentile

Messwerte können auch Perzentile enthalten, die für zusätzliche Analysen nützlich sein können. Wir erfassen bestimmte Messwertwerte für den angegebenen Perzentilwert. Sie basieren auf dem gesamten Datenpool und nicht auf den endgültigen geclusterten Daten. Daher stimmen sie nicht unbedingt mit einem interpolierten Prozentrang überein, der auf dem endgültigen geclusterten Histogramm basiert.

{
  "percentiles": {
    "p75": 2063
  }
}

In diesem Beispiel wurden mindestens 75% der Seitenladezeiten mit dem Messwert <= 2063 gemessen.

Brüche

Brüche geben den Prozentsatz der Seitenladevorgänge an, die auf eine bestimmte Weise gekennzeichnet werden können. In diesem Fall sind die Messwertwerte diese Labels.

Der Messwert form_factors besteht beispielsweise aus einem fractions-Objekt, das die Aufschlüsselung der Formfaktoren (oder Geräte) enthält, die von der jeweiligen Abfrage abgedeckt werden:

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

In diesem Fall wurden 3,77% der Seitenladevorgänge auf einem Computer, 2,88% auf einem Tablet und 93,35% auf einem Smartphone gemessen, was insgesamt 100% ergibt.

Messwerttypen

Name des CrUX API-Messwerts Datentyp Metrische Einheiten Statistische Aggregationen Dokumentation
cumulative_layout_shift 2 Dezimalstellen doppelt als String codiert ohne Einheit Histogramm mit drei Bins, Perzentile mit p75 cls
first_contentful_paint int Millisekunden Histogramm mit drei Bins, Perzentile mit p75 fcp
interaction_to_next_paint int Millisekunden Histogramm mit drei Bins, Perzentile mit p75 inp
largest_contentful_paint int Millisekunden Histogramm mit drei Bins, Perzentile mit p75 lcp
experimental_time_to_first_byte int Millisekunden Histogramm mit drei Bins, Perzentile mit p75 ttfb
form_factors Doppelt mit 4 Dezimalstellen Prozent Zuordnung von Formfaktor zu Bruchteil Formfaktoren
navigation_types Doppelt mit 4 Dezimalstellen Prozent Zuordnung von Navigationstyp zu Bruchteil Navigationstypen
round_trip_time int Millisekunden Perzentile mit p75 rtt

BigQuery-Messwertnamenzuordnung

Name des CrUX API-Messwerts BigQuery-Messwertname
cumulative_layout_shift layout_instability.cumulative_layout_shift
first_contentful_paint first_contentful_paint
interaction_to_next_paint interaction_to_next_paint
largest_contentful_paint largest_contentful_paint
experimental_time_to_first_byte experimental.time_to_first_byte
navigation_types navigation_types
form_factors –
round_trip_time –

Erhebungszeitraum

Seit Oktober 2022 enthält die CrUX API ein collectionPeriod-Objekt mit den Feldern firstDate und endDate, die das Start- und Enddatum des Aggregationszeitraums darstellen. Beispiel:

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

So können Sie die Daten besser nachvollziehen und erkennen, ob sie für den jeweiligen Tag bereits aktualisiert wurden oder ob dieselben Daten wie gestern zurückgegeben werden.

Die CrUX API ist ungefähr zwei Tage im Rückstand, da auf vollständige Daten für den Tag gewartet wird. Außerdem ist eine gewisse Verarbeitungszeit erforderlich, bevor die Daten in der API verfügbar sind. Die verwendete Zeitzone ist Pacific Standard Time (PST) ohne Änderungen für die Sommerzeit.

Außerdem wird für collectionPeriod immer ein Zeitraum von 28 Tagen angezeigt, auch wenn die Daten nicht für die vollen 28 Tage vorliegen (z. B. wenn eine Seite vor weniger als 28 Tagen veröffentlicht wurde). Der Wert collectionPeriod ist der Zeitraum, über den die CrUX-Daten aggregiert wurden, nicht unbedingt der Zeitraum, den die Daten repräsentieren.

Beispielabfragen

Abfragen werden als JSON-Objekte mit einer POST-Anfrage an https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" gesendet. Die Abfragedaten sind dabei als JSON-Objekt im POST-Body enthalten:

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Sie können ihn beispielsweise über curl mit der folgenden Befehlszeile aufrufen (ersetzen Sie API_KEY durch Ihren Schlüssel):

curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=API_KEY' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'

Daten auf Seitenebene sind über die API verfügbar, wenn Sie in der Abfrage eine url-Property anstelle von origin übergeben:

{
  "url": "https://example.com/page",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Wenn die Property metrics nicht festgelegt ist, werden alle verfügbaren Messwerte zurückgegeben:

  • cumulative_layout_shift
  • first_contentful_paint
  • interaction_to_next_paint
  • largest_contentful_paint
  • experimental_time_to_first_byte
  • navigation_types
  • form_factors (wird nur gemeldet, wenn in der Anfrage kein formFactor angegeben ist)

Wenn kein formFactor-Wert angegeben ist, werden die Werte für alle Formfaktoren zusammengefasst.

Weitere Beispielabfragen finden Sie unter Chrome UX Report API verwenden.

Datenpipeline

Der CrUX-Datensatz wird in einer Pipeline verarbeitet, um die Daten zu konsolidieren, zu aggregieren und zu filtern, bevor sie über die API verfügbar gemacht werden.

Der gleitende Durchschnitt

Die Daten im UX-Bericht für Chrome sind ein gleitender Durchschnitt von 28 Tagen aus zusammengefassten Messwerten. Das bedeutet, dass die Daten, die im Chrome UX Report zu einem bestimmten Zeitpunkt angezeigt werden, in Wirklichkeit Daten der letzten 28 Tage sind, die zusammengefasst wurden.

Das entspricht der Vorgehensweise beim Zusammenfassen monatlicher Berichte im CrUX-Dataset in BigQuery.

Tägliche Updates

Die Daten werden täglich um etwa 04:00 Uhr UTC aktualisiert. Es gibt kein Service Level Agreement für die Aktualisierungszeit. Die Aktualisierung erfolgt täglich auf Best-Effort-Basis.

Schema

Es gibt einen einzelnen Endpunkt für die CrUX API, der POST HTTP-Anfragen akzeptiert. Die API gibt eine record zurück, die eine oder mehrere metrics enthält, die den Leistungsdaten für den angeforderten Ursprung oder die angeforderte Seite entsprechen.

HTTP-Anfrage

POST https://chromeuxreport.googleapis.com/v1/records:queryRecord

Die URL verwendet die Syntax der gRPC-Transcodierung.

Anfragetext

Der Anfragetext sollte Daten mit folgender Struktur enthalten:

{
  "formFactor": enum (FormFactor),
  "metrics": [
    string
  ],

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}
Felder
formFactor

enum (FormFactor)

Der Formfaktor ist eine Abfragedimension, die die Geräteklasse angibt, zu der die Daten des Datensatzes gehören sollten.

In diesem Feld werden die Werte DESKTOP, PHONE oder TABLET verwendet.

Hinweis: Wenn kein Formfaktor angegeben ist, wird ein spezieller Datensatz mit aggregierten Daten für alle Formfaktoren zurückgegeben.
metrics[]

string

Die Messwerte, die in der Antwort enthalten sein sollen. Wenn keine angegeben sind, werden alle gefundenen Messwerte zurückgegeben.

Zulässige Werte: ["cumulative_layout_shift", "first_contentful_paint", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
Union-Feld url_pattern. Die url_pattern ist die Hauptkennzeichnung für die Datensatzsuche. Mögliche Werte:
origin

string

„url_pattern origin“ bezieht sich auf ein URL-Muster, das der Ursprung einer Website ist.

Beispiele: "https://example.com", "https://cloud.google.com"
url

string

url_pattern url bezieht sich auf ein URL-Muster, das eine beliebige URL ist.

Beispiele: "https://example.com/, https://cloud.google.com/why-google-cloud/"

So rufen Sie beispielsweise die Werte für Largest Contentful Paint auf dem Computer für die Startseite der Chrome-Entwicklerdokumentation ab:

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

Antworttext

Bei erfolgreichen Anfragen werden Antworten mit einem record-Objekt und urlNormalizationDetails in der folgenden Struktur zurückgegeben:

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

Die Antwort auf den Anfragetext in der vorherigen Anfrage könnte beispielsweise so aussehen:

{
  "record": {
    "key": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.9815
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.0108
          },
          {
            "start": 4000,
            "density": 0.0077
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

Schlüssel

Key definiert alle Dimensionen, die diesen Datensatz als eindeutig identifizieren.

{
  "formFactor": enum (FormFactor),

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}
Felder
formFactor

enum (FormFactor)

Der Formfaktor ist die Geräteklasse, die alle Nutzer für den Zugriff auf die Website für diesen Datensatz verwendet haben.

Wenn der Formfaktor nicht angegeben ist, werden aggregierte Daten für alle Formfaktoren zurückgegeben.
Union-Feld url_pattern. Das URL-Muster ist die URL, auf die sich der Eintrag bezieht. Für url_pattern ist nur einer der folgenden Werte zulässig:
origin

string

origin gibt den Ursprung an, für den dieser Datensatz gilt.

Hinweis: Wenn Sie eine origin angeben, werden Daten für Ladevorgänge unter diesem Ursprung auf allen Seiten zu Nutzererfahrungsdaten auf Ursprungsebene zusammengefasst.
url

string

Mit url wird eine bestimmte URL angegeben, für die dieser Eintrag gilt.

Hinweis: Wenn Sie eine url angeben, werden nur Daten für diese bestimmte URL zusammengefasst.

Messwerte

Ein metric ist eine Reihe aggregierter Daten zur Nutzerfreundlichkeit für einen einzelnen Web-Leistungsmesswert, z. B. „First Contentful Paint“. Es kann ein zusammenfassendes Histogramm der tatsächlichen Chrome-Nutzung als Reihe von bins, bestimmte Perzentildaten (z. B. p75) oder beschriftete Brüche enthalten.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

oder

{
  "fractions": {
    object (Fractions)
  }
}
Felder
histogram[]

object (Bin)

Das Histogramm der Nutzererfahrungen für einen Messwert. Das Histogramm hat mindestens einen Bin und die Dichten aller Bins summieren sich auf etwa 1.
percentiles

object (Percentiles)

Gängige nützliche Perzentile des Messwerts. Der Werttyp für die Perzentile ist derselbe wie der Werttyp für die Histogrammbalken.
fractions

object (Fractions)

Dieses Objekt enthält beschriftete Brüche, die zusammen etwa 1 ergeben.

Brüche werden auf vier Dezimalstellen gerundet.

Klasse

Ein bin ist ein diskreter Datenbereich, der vom Anfang bis zum Ende reicht oder, wenn kein Ende angegeben ist, vom Anfang bis unendlich.

Die Start- und Endwerte eines Bins sind im Werttyp des Messwerts angegeben, den er darstellt. „First Contentful Paint“ wird beispielsweise in Millisekunden gemessen und als Ganzzahl dargestellt. Daher werden für die Messwert-Bins int32-Werte für die Start- und Endtypen verwendet. Die kumulative Layoutverschiebung wird jedoch in dezimalen Werten ohne Einheit gemessen und als Dezimalzahl codiert als String dargestellt. Daher werden für die Messwertgruppen Strings als Werttyp verwendet.

{
  "start": value,
  "end": value,
  "density": number
}
Felder
start

(integer | string)

„Start“ ist der Beginn des Datenbins.
end

(integer | string)

„End“ ist das Ende des Datenbins. Wenn „end“ nicht angegeben ist, hat der Bin kein Ende und ist von „start“ bis +inf gültig.
density

number

Der Anteil der Nutzer, für die der Wert dieses Bins für den angegebenen Messwert aufgetreten ist.

Dichten werden auf 4 Dezimalstellen gerundet.

Perzentile

Percentiles enthält synthetische Werte eines Messwerts bei einem bestimmten statistischen Perzentil. Mithilfe dieser Messwerte lässt sich der Wert eines Messwerts für einen Prozentsatz der Nutzer im Vergleich zur Gesamtzahl der Nutzer schätzen.

{
  "P75": value
}
Felder
p75

(integer | string)

Bei 75% der Seitenladevorgänge wurde der angegebene Messwert nicht überschritten.

Brüche

Fractions enthält beschriftete Fraktionen, die zusammen etwa 1 ergeben. Jedes Label beschreibt eine Seitenladezeit. Daher können Messwerte, die auf diese Weise dargestellt werden, als eindeutige Werte anstelle von numerischen Werten betrachtet werden. Die Brüche geben an, wie oft ein bestimmter eindeutiger Wert gemessen wurde.

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

Ähnlich wie die Dichtewerte in Histogrammbalken ist jeder fraction eine Zahl 0.0 <= value <= 1.0 und ihre Summe beträgt etwa 1,0.

UrlNormalization

Objekt, das die Normalisierungsaktionen darstellt, die durchgeführt wurden, um eine URL zu normalisieren und so die Wahrscheinlichkeit einer erfolgreichen Suche zu erhöhen. Das sind einfache automatisierte Änderungen, die vorgenommen werden, wenn beim Abrufen der angegebenen url_pattern bekannt ist, dass ein Fehler auftritt. Komplexe Aktionen wie das Folgen von Weiterleitungen werden nicht verarbeitet.

{
  "originalUrl": string,
  "normalizedUrl": string
}
Felder
originalUrl

string

Die ursprünglich angeforderte URL vor jeglichen Normalisierungsaktionen.
normalizedUrl

string

Die URL nach allen Normalisierungsaktionen. Dies ist eine gültige URL für die Nutzerfreundlichkeit, die in angemessener Weise aufgerufen werden kann.

Ratenlimits

Die CrUX API ist auf 150 Abfragen pro Minute und Google Cloud-Projekt beschränkt. Die Nutzung ist kostenlos. Dieses Limit und Ihre aktuelle Nutzung finden Sie in der Google Cloud Console. Dieses großzügige Kontingent sollte für die meisten Anwendungsfälle ausreichen. Es ist nicht möglich, ein höheres Kontingent zu erwerben.