Veröffentlicht: 7. Februar 2023, zuletzt aktualisiert: 11. April 2025
In diesem Leitfaden wird der Endpunkt der Chrome UX Report History API (CrUX) vorgestellt, über den Zeitreihen mit Webleistungsdaten bereitgestellt werden. Diese Daten werden wöchentlich aktualisiert und umfassen einen Zeitraum von etwa sechs Monaten mit 40 Datenpunkten, die jeweils einen Abstand von einer Woche haben.
In Kombination mit den täglichen Aktualisierungen vom ursprünglichen CrUX API-Endpunkt können Sie jetzt schnell sowohl die neuesten Daten als auch die bisherigen Ereignisse sehen. Dies ist ein leistungsstarkes Tool, um Webseitenänderungen im Zeitverlauf zu beobachten.
API auf dieser Seite testen
Tägliche CrUX API abfragen
Wie in einem früheren Artikel zur CrUX API erläutert, können Sie so einen Snapshot der Felddaten für einen bestimmten Ursprung abrufen:
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" --header 'Content-Type: application/json' --data '{"origin": "https://web.dev"}'
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [{
"start": 0, "end": 2500, "density": 0.9192
}, {
"start": 2500, "end": 4000, "density": 0.0513
}, {
"start": 4000, "density": 0.0294
}],
"percentiles": {
"p75": 1303
}
}
// ...
},
"collectionPeriod": {
"firstDate": { "year": 2022, "month": 12, "day": 27 },
"lastDate": { "year": 2023, "month": 1, "day": 23 }
}
}
}
Dieser Snapshot enthält Histogrammdichtewerte und Prozentrangwerte für einen bestimmten Erhebungszeitraum von 28 Tagen, in diesem Fall vom 27. Dezember 2022 bis zum 23. Januar 2023.
CrUX History API abfragen
Wenn Sie den Verlaufsendpunkt aufrufen möchten, ändern Sie queryRecord in der URL in queryHistoryRecord im Befehl curl. Sie können denselben CrUX API-Schlüssel wie beim vorherigen Aufruf verwenden.
Mit collectionPeriodCount wird die Anzahl der zurückzugebenden Zeitreiheneinträge angegeben. Die maximale Anzahl ist 40. Wenn keine Angabe erfolgt, wird standardmäßig 25 verwendet.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"origin": "https://web.dev", "collectionPeriodCount": 40}'
Die allgemeine Struktur einer Antwort ist ähnlich, aber es gibt viel mehr Daten. Anstelle eines einzelnen Datenpunkts gibt es jetzt Zeitreihen für die Felder mit dem 75. Perzentil (p75) und den Histogrammdichtewerten.
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogramTimeseries": [{
"start": 0, "end": 2500, "densities": [
0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187
]
}, {
"start": 2500, "end": 4000, "densities": [
0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527
]
}, {
"start": 4000, "densities": [
0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285
]
}
],
"percentilesTimeseries": {
"p75s": [
1362, 1352, 1344, 1356, 1366, 1377
]
}
}
// ...
},
"collectionPeriods": [{
"firstDate": { "year": 2022, "month": 7, "day": 10 },
"lastDate": { "year": 2022, "month": 8, "day": 6 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 17 },
"lastDate": { "year": 2022, "month": 8, "day": 13 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 24 },
"lastDate": { "year": 2022, "month": 8, "day": 20 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 31 },
"lastDate": { "year": 2022, "month": 8, "day": 27 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 7 },
"lastDate": { "year": 2022, "month": 9, "day": 3 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 14 },
"lastDate": { "year": 2022, "month": 9, "day": 10 }
}
]
}
}
In diesem Beispiel ist [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. die densities-Zeitreihe für den Bucket von 0 bis 2.500 ms des Messwerts Largest Contentful Paint (LCP). Jede dieser Dichten wurde während des entsprechenden collectionPeriods-Eintrags beobachtet. Die fünfte Dichte, 0,9183, war beispielsweise die Dichte für den fünften Erhebungszeitraum, der am 3. September 2022 endete, und 0,9187 war die Dichte im Zeitraum, der in der Woche darauf endete.
Mit anderen Worten: Bei der Auswertung der letzten Zeitreiheneinträge im Beispiel für https://web.dev wurde festgestellt, dass vom 14. August 2022 bis zum 10. September 2022 91,87% der Seitenladezeiten LCP-Werte unter 2.500 ms hatten, 5,27% Werte zwischen 2.500 ms und 4.000 ms und 2,85% Werte über 4.000 ms.
Ebenso gibt es eine Zeitreihe für die P75-Werte: Der LCP-P75 vom 14. August 2022 bis zum 10. September 2022 betrug 1377. Das bedeutet, dass bei 75% der Nutzererfahrungen in diesem Erfassungszeitraum der LCP unter 1.377 Millisekunden lag und bei 25% der Nutzererfahrungen über 1.377 Millisekunden.
Im Beispiel sind nur sechs Zeitreiheneinträge und Erfassungszeiträume aufgeführt. In den Antworten der API sind standardmäßig 25 Zeitreiheneinträge und maximal 40 einträge enthalten, wenn "collectionPeriodCount": 40 in der Anfrage angegeben ist. Da die Enddaten für jeden dieser Erfassungszeitraume Samstage sind, die 7 Tage auseinander liegen, umfasst "collectionPeriodCount": 40 10 Monate.
In jeder Antwort ist die Länge der Zeitreihe für die Histogramm-Bin-Dichten und für die p75-Werte genau gleich der Länge des Arrays im Feld collectionPeriods. Es gibt eine Eins-zu-Eins-Beziehung basierend auf dem Index in diesen Arrays.
Daten auf Seitenebene abfragen
Neben Daten auf Ursprungsebene ermöglicht die CrUX History API auch den Zugriff auf Verlaufsdaten auf Seitenebene. Die Daten auf Ursprungsebene waren bisher über das CrUX-Dataset in BigQuery oder über das CrUX-Dashboard verfügbar. Die Verlaufsdaten auf Seitenebene waren nur verfügbar, wenn die Daten von den Websites selbst erfasst und gespeichert wurden. Mit der neuen API können Sie jetzt auf diese Verlaufsdaten auf Seitenebene zugreifen.
Die Daten auf Seitenebene können auf die gleiche Weise abgefragt werden, jedoch mit url anstelle von origin in der Nutzlast:
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/blog/"}'
Verlaufsdaten auf Seiten- und Ursprungsebene unterliegen den gleichen Teilnahmevoraussetzungen wie der Rest von CrUX. Daher sind für Seiten möglicherweise keine vollständigen Verlaufsdaten verfügbar. In diesen Fällen werden die „fehlenden“ Daten durch "NaN" für die histogramTimeseries-Dichten und null für die percentilesTimeseries dargestellt. Der Grund für den Unterschied ist, dass die Histogrammdichten immer Zahlen sind, während die Perzentile Zahlen oder Strings sein können. In CLS werden Strings verwendet, auch wenn sie wie Zahlen aussehen.
Daten visualisieren
Die Daten lassen sich am einfachsten mit CrUX Vis visualisieren, einem Tool, das speziell entwickelt wurde, um die Leistungsfähigkeit der CrUX History API zu demonstrieren. Weitere Informationen finden Sie in der CrUX Vis-Dokumentation.
Wenn Sie ähnliche Diagramme selbst erstellen möchten, haben wir ein Beispiel-Colab für Sie erstellt. Mit einem Colab (kurz für „Colaboratory“) können Sie Python-Code direkt in Ihrem Browser schreiben und ausführen. Im CrUX History API Colab (Quelle) werden Python-Aufrufe an die API gesendet und die Daten in Diagrammen dargestellt.
In diesem Colab können Sie P75-Diagramme, Dreifach-Bin-Diagramme erstellen, Daten in Tabellenform abrufen und das Anfrage- und Antwortpaar für die CrUX API aufrufen, indem Sie ein kurzes Formular ausfüllen. Sie müssen kein Programmierer sein, um dieses Tool zu verwenden. Sie können sich aber den Python-Code ansehen und ihn zu etwas Tollem umwandeln. Viel Spaß beim Entdecken und gib uns gerne Feedback zu deinen Eindrücken.
Natürlich sind Sie nicht auf Colab oder Python beschränkt. Dies ist nur ein Beispiel dafür, wie Sie diese neue API verwenden können. Da es sich um einen JSON-basierten HTTP-Endpunkt handelt, kann die API mit jeder Technologie abgefragt werden.
Fazit
Vor der Einführung des CrUX History API-Endpunkts waren die Verlaufsinformationen, die Websiteinhaber über CrUX abrufen konnten, begrenzt. Mit BigQuery und dem CrUX-Dashboard waren monatliche Daten auf Herkunftsebene verfügbar, aber keine wöchentlichen Daten und keine Verlaufsdaten auf Seitenebene. Websiteinhaber konnten diese Daten selbst mit der täglichen API erfassen. Oft wurde dies jedoch erst nach einer Regression der Messwerte erforderlich.
Wir hoffen, dass die Einführung dieser CrUX History API Websiteinhabern dabei helfen wird, ihre sich ändernden Websitemesswerte besser zu verstehen und bei Problemen ein Diagnosetool zu haben. Wenn Sie die neue API verwenden, freuen wir uns über Feedback in der Google-Gruppe Chrome UX Report (Discussions).
Danksagungen
Hero-Image von Dave Herring auf Unsplash