Die CrUX API bietet Zugriff mit niedriger Latenz auf aggregierte Daten zur Nutzerfreundlichkeit auf Seite und Ursprung.
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. Sie können ein Passwort auf der Seite Anmeldedaten erstellen und es für die Chrome UX Report API
-Nutzung bereitstellen.
Sobald Sie einen API-Schlüssel haben, kann Ihre Anwendung den Suchparameter key=[YOUR_API_KEY]
an alle Anfrage-URLs anhängen. Beispielabfragen
Der API-Schlüssel lässt sich sicher in URLs einbetten. Eine Codierung ist nicht notwendig.
Datenmodell
In diesem Abschnitt wird die Struktur der Daten in Anfragen und Antworten beschrieben.
Datensatz
Eine einzelne Information zu einer Seite oder Website. Ein Datensatz kann Daten enthalten, die für eine Kennung und für eine bestimmte Kombination von Dimensionen spezifisch sind. Ein Datensatz kann Daten für einen oder mehrere Messwerte enthalten.
IDs
IDs geben an, welche Datensätze abgerufen werden sollen. In CrUX sind diese Kennungen Webseiten und Websites.
Ursprung
Wenn die Kennung ein Ursprung ist, werden alle Daten für alle Seiten dieses Ursprungs zusammengefasst. Angenommen, der Ursprung http://www.example.com
hatte Seiten gemäß dieser Sitemap:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Wenn also der UX-Bericht für Chrome abgefragt wird, für den der Ursprung auf http://www.example.com
gesetzt ist, werden Daten für http://www.example.com/
, http://www.example.com/foo.html
und http://www.example.com/bar.html
in aggregierter Form zurückgegeben, da es sich um alle Seiten dieses Ursprungs handelt.
URLs
Wenn es sich bei der Kennung um eine URL handelt, werden nur Daten für diese spezifische URL zurückgegeben. Noch einmal auf die ursprüngliche Sitemap von http://www.example.com
:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Wenn die Kennung auf eine URL mit dem Wert http://www.example.com/foo.html
gesetzt ist, werden nur Daten für diese Seite zurückgegeben.
Abmessungen
Dimensionen geben eine bestimmte Gruppe von Daten an, mit denen ein Datensatz aggregiert wird. Beispielsweise gibt der Formfaktor PHONE
an, dass der Datensatz Informationen zu Ladevorgängen enthält, die auf einem Mobilgerät stattgefunden haben. Jede Dimension hat eine bestimmte Anzahl von Werten. Wenn diese Dimension nicht angegeben wird, bedeutet das, dass sie für alle Werte zusammengefasst wird. Wird kein Formfaktor angegeben, bedeutet dies beispielsweise, dass der Datensatz Informationen zu Ladevorgängen enthält, 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.
Effektiver Verbindungstyp
Effektiver Verbindungstyp ist die geschätzte Verbindungsqualität des Geräts beim Aufrufen der Seite. Dies ist eine allgemeine Klasse, die in offline
, slow-2G
, 2G
, 3G
und 4G
aufgeteilt ist.
Messwert
Messwerte werden als statistische Aggregationen, in Histogrammen, Perzentilen und Brüchen angegeben.
Gleitkommawerte werden auf vier Dezimalstellen gerundet. Beachten Sie, dass die cumulative_layout_shift
-Messwerte doppelt als String codiert sind. Sie werden nicht als Gleitkommazahlen berücksichtigt und werden innerhalb des Strings auf zwei Dezimalstellen ausgegeben.
Histogramm
Wenn Messwerte in einem Histogramm dargestellt werden, werden die Prozentsätze der Seitenladevorgänge angezeigt, die in bestimmte Bereiche für diesen Messwert fallen.
Ein einfaches 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 Seitenaufrufe 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.
Außerdem sahen 49,91% der Seitenaufrufe einen Messwert zwischen 1.000 ms und 3.000 ms und 11,92 % einen Wert über 3.000 ms.
Perzentile
Messwerte können auch Perzentile enthalten, die für zusätzliche Analysen nützlich sein können. Es werden spezifische Messwerte auf Basis des jeweiligen Perzentils für diesen Messwert angegeben. Sie basieren auf dem vollständigen Satz verfügbarer Daten und nicht auf den endgültigen gruppierten Daten. Daher stimmen sie nicht unbedingt mit einem interpolierten Perzentil überein, das auf dem endgültigen gruppierten Histogramm basiert.
{
"percentiles": {
"p75": 2063
}
}
In diesem Beispiel wurden mindestens 75% der Seitenaufrufe mit dem Messwert <= 2063
gemessen.
Brüche
Bruchteile geben die Prozentsätze des Seitenaufbaus an, die unterschiedlich beschriftet werden können. In diesem Fall sind die Messwerte diese Labels.
Der Messwert form_factors
besteht beispielsweise aus einem fractions
-Objekt, das eine Aufschlüsselung der Formfaktoren (oder Geräte) auflistet, die in der angegebenen Abfrage enthalten sind:
"form_factors": {
"fractions": {
"desktop": 0.0377,
"tablet": 0.0288,
"phone": 0.9335
}
}
In diesem Fall wurden 3,77% der Seitenaufrufe auf einem Computer, 2,88% auf einem Tablet und 93,35% auf einem Smartphone gemessen, was insgesamt 100% ergibt.
Messwerttypen
CrUX API-Messwertname | Datentyp | Metrische Einheiten | Statistische Zusammenfassungen | Dokumentation |
---|---|---|---|---|
cumulative_layout_shift |
Zwei Dezimalstellen doppelt als String codiert | ohne Einheit | Histogramm mit drei Klassen, Perzentile mit p75 | cls |
first_contentful_paint |
int | Millisekunden | Histogramm mit drei Klassen, Perzentile mit p75 | FCP |
first_input_delay (eingestellt) |
int | Millisekunden | Histogramm mit drei Klassen, Perzentile mit p75 | Fid |
interaction_to_next_paint |
int | Millisekunden | Histogramm mit drei Klassen, Perzentile mit p75 | InP |
largest_contentful_paint |
int | Millisekunden | Histogramm mit drei Klassen, Perzentile mit p75 | lcp |
experimental_time_to_first_byte |
int | Millisekunden | Histogramm mit drei Klassen, Perzentile mit p75 | TTFB |
form_factors |
Doppelte Stelle mit 4 Dezimalstellen | Prozent | Zuordnung von Formfaktor zu Bruch | Formfaktoren |
navigation_types |
Doppelte Stelle mit 4 Dezimalstellen | Prozent | Zuordnung vom Navigationstyp zum Bruch | Navigationstypen |
Zuordnung von BigQuery-Messwertnamen
CrUX API-Messwertname | Name des BigQuery-Messwerts |
---|---|
cumulative_layout_shift |
layout_instability.cumulative_layout_shift |
first_contentful_paint |
first_contentful_paint |
first_input_delay |
first_input.delay |
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 |
– |
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 angeben. Beispiel:
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
So können Sie die Daten besser verstehen und feststellen, ob sie für diesen Tag noch aktualisiert wurden oder die gleichen Daten wie gestern zurückgegeben werden.
Beachten Sie, dass die CrUX API etwa zwei Tage hinter dem heutigen Datum liegt, da sie auf abgeschlossene Daten für den Tag wartet und einige Verarbeitungszeit erforderlich ist, bevor sie in der API verfügbar ist. Die verwendete Zeitzone ist Pacific Standard Time (PST) ohne Umstellung auf Sommer-/Winterzeit.
Beispielabfragen
Abfragen werden als JSON-Objekte mit einer POST-Anfrage an https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]"
mit Abfragedaten als JSON-Objekt im POST-Textkörper gesendet:
{
"origin": "https://example.com",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Sie kann beispielsweise über curl
mit der folgenden Befehlszeile aufgerufen werden. Dabei wird API_KEY
durch Ihren Schlüssel ersetzt:
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 statt origin
das Attribut url
in der Abfrage übergeben wird:
{
"url": "https://example.com/page",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Wenn das Attribut metrics
nicht festgelegt ist, werden alle verfügbaren Messwerte zurückgegeben:
cumulative_layout_shift
first_contentful_paint
first_input_delay
(eingestellt)interaction_to_next_paint
largest_contentful_paint
experimental_time_to_first_byte
navigation_types
form_factors
(nur gemeldet, wenn in der Anfrage keinformFactor
angegeben ist)
Wenn kein formFactor
-Wert angegeben ist, werden die Werte für alle Formfaktoren aggregiert.
Weitere Beispielabfragen finden Sie unter Chrome UX Report API verwenden.
Datenpipeline
Das CrUX-Dataset wird über eine Pipeline verarbeitet, um die Daten zu konsolidieren, zu aggregieren und zu filtern, bevor sie über die API verfügbar sind.
Der gleitende Durchschnitt
Bei den Daten im UX-Bericht für Chrome handelt es sich um einen gleitenden Durchschnitt über 28 Tage von aggregierten Messwerten. Das bedeutet, dass es sich bei den Daten, die jeweils im Bericht zur Nutzererfahrung von Chrome angezeigt werden, um Daten der letzten 28 Tage handelt.
Dies ähnelt der Zusammenfassung monatlicher Berichte im CrUX-Dataset in BigQuery.
Tägliche Updates
Die Daten werden täglich um 04:00 Uhr (UTC) aktualisiert. Es gibt kein Service Level Agreement (SLA) für Aktualisierungszeiten. Die Updates werden jeden Tag auf Best-Effort-Basis durchgeführt.
Schema
Für die CrUX API gibt es einen einzelnen Endpunkt, der POST
-HTTP-Anfragen akzeptiert. Die API gibt ein record
zurück, das eine oder mehrere metrics
enthält, die den Leistungsdaten zum angeforderten Ursprung oder zur angeforderten 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:
{
"effectiveConnectionType": string,
"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 | |
---|---|
effectiveConnectionType |
Der effektive Verbindungstyp ist eine Abfragedimension, die die effektive Netzwerkklasse angibt, zu der die Daten des Eintrags gehören sollen. In diesem Feld werden die Werte Hinweis: Wenn kein effektiver Verbindungstyp angegeben ist, wird ein spezieller Datensatz mit aggregierten Daten für alle effektiven Verbindungstypen zurückgegeben. |
formFactor |
Der Formfaktor ist eine Abfragedimension, die die Geräteklasse angibt, zu der die Daten des Eintrags gehören sollen. In diesem Feld werden die Werte Hinweis: Wenn kein Formfaktor angegeben ist, wird ein spezieller Datensatz mit aggregierten Daten für alle Formfaktoren zurückgegeben. |
metrics[] |
Die Messwerte, die in der Antwort enthalten sein sollen. Wenn keine angegeben sind, werden alle gefundenen Messwerte zurückgegeben. Zulässige Werte: |
Union-Feld url_ . url_pattern ist die Hauptkennung für eine Datensatzsuche. Folgende Optionen sind zulässig: |
|
origin |
„origin“ ( Beispiele: |
url |
Beispiele: |
So fordern Sie beispielsweise die größten Contentful Paint-Werte für Computer für die Startseite der Chrome-Entwicklerdokumentation an:
{
"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, mit denen dieser Datensatz als eindeutig identifiziert wird.
{
"effectiveConnectionType": string,
"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 |
Der Formfaktor ist die Geräteklasse, die alle Nutzer verwendet haben, um für diesen Eintrag auf die Website zuzugreifen. Wenn der Formfaktor nicht angegeben ist, werden aggregierte Daten zu allen Formfaktoren zurückgegeben. |
effectiveConnectionType |
Der effektive Verbindungstyp ist die allgemeine Verbindungsklasse, die alle Nutzer für diesen Eintrag festgestellt haben. In diesem Feld werden die Werte ["offline", "slow-2G", "2G", "3G", "4G"] verwendet, wie unter https://wicg.github.io/netinfo/#effective-connection-types angegeben. Wenn der effektive Verbindungstyp nicht angegeben ist, werden aggregierte Daten über alle effektiven Verbindungstypen zurückgegeben. |
Union-Feld url_ . Das URL-Muster ist die URL, für die der Eintrag gilt. Für url_ ist nur einer der folgenden Werte zulässig: |
|
origin |
Hinweis: Wenn Sie ein |
url |
Hinweis: Bei Angabe von |
Messwerte
Ein metric
ist ein Satz aggregierter Daten zur Nutzererfahrung für einen einzelnen Web-Leistungsmesswert, z. B. First Contentful Paint.
Es kann ein zusammenfassendes Histogramm der realen Chrome-Nutzung in Form einer Reihe von bins
, spezifischen Perzentildaten (z. B. P75) oder mit Labels versehene Bruchteile enthalten.
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
oder
{
"fractions": {
object (Fractions)
}
}
Felder | |
---|---|
histogram[] |
Das Histogramm der Nutzererfahrung für einen Messwert. Das Histogramm enthält mindestens einen Container und die Dichten aller Klassen ergeben zusammengenommen ungefähr 1. |
percentiles |
Allgemeine nützliche Perzentile des Messwerts. Der Werttyp für die Perzentile entspricht den Werttypen für die Histogrammgruppen. |
fractions |
Dieses Objekt enthält beschriftete Brüche, die zusammengenommen ~1 ergeben. Brüche werden auf vier Dezimalstellen gerundet. |
Klasse
Ein bin
ist ein diskreter Teil von Daten, der von Anfang bis Ende umfasst oder wenn kein Ende vom Anfang bis positiv unendlich angegeben wird.
Die Start- und Endwerte einer Klasse sind im Werttyp des dargestellten Messwerts angegeben. Beispielsweise wird First Contentful Paint in Millisekunden gemessen und als Ganzzahl dargestellt. Daher verwenden seine Messwertbins int32s für die Start- und Endtypen. Die kumulative Layoutverschiebung wird jedoch in Dezimalzahlen ohne Einheit gemessen und als Dezimalzahl codiert, die als String codiert ist. Daher verwenden die Messwertbinden Strings als Werttyp.
{
"start": value,
"end": value,
"density": number
}
Felder | |
---|---|
start |
„Start“ ist der Anfang des Datencontainers. |
end |
Ende ist das Ende der Datengruppe. Wenn das Feld end nicht ausgefüllt ist, hat der Container kein Ende und ist von Anfang bis +inf gültig. |
density |
Anteil der Nutzer, bei denen der Wert dieses Containers für den angegebenen Messwert erfasst wurde. Die Dichten werden auf 4 Dezimalstellen gerundet. |
Perzentile
Percentiles
enthält synthetische Werte eines Messwerts bei einem bestimmten statistischen Perzentil. Sie werden verwendet, um den Wert eines Messwerts so zu schätzen, wie er für einen Prozentsatz der Nutzer im Vergleich zur Gesamtzahl der Nutzer zu sehen ist.
{
"P75": value
}
Felder | |
---|---|
p75 |
Bei 75% der Seitenaufbauvorgänge war der angegebene Messwert unter diesem Wert. |
Brüche
Fractions
enthält mit Labels versehene Brüche, die zusammengenommen ~1 ergeben. Jedes Label beschreibt einen Seitenaufbau auf irgendeine Art und Weise. Die so dargestellten Messwerte erzeugen unterschiedliche Werte anstelle von numerischen Werten. Die Bruchteile geben an, wie häufig ein bestimmter bestimmter Wert gemessen wurde.
{
"label_1": fraction,
"label_2": fraction,
...
"label_n": fraction
}
Ähnlich wie die Dichtewerte in Histogrammklassen ist jeder fraction
eine Zahl 0.0 <= value <= 1.0
, deren Summe ungefähr 1, 0 ergibt.
UrlNormalization
Objekt, das die Normalisierungsaktionen darstellt, die zur Normalisierung einer URL erforderlich sind, um eine höhere Wahrscheinlichkeit einer erfolgreichen Suche zu erzielen. Dies sind einfache automatisierte Änderungen, die bei der Suche nach der bereitgestellten url_pattern
vorgenommen werden und scheitern. Komplexe Aktionen wie Weiterleitungen werden nicht berücksichtigt.
{
"originalUrl": string,
"normalizedUrl": string
}
Felder | |
---|---|
originalUrl |
Die ursprünglich angeforderte URL vor allen Normalisierungsaktionen. |
normalizedUrl |
Die URL nach allen Normalisierungsaktionen. Dies ist eine gültige URL, die Nutzer nachschlagen könnte. |
Ratenbegrenzungen
Die CrUX API ist auf 150 Abfragen pro Minute pro Google Cloud-Projekt beschränkt und wird kostenlos angeboten. Dieses Limit und Ihre aktuelle Nutzung können Sie in der Google Cloud Console einsehen. Dieses großzügige Kontingent sollte für die meisten Anwendungsfälle ausreichen und es ist nicht möglich, für ein erhöhtes Kontingent zu bezahlen.