Veröffentlicht am 7. Februar 2023, zuletzt aktualisiert am 11. April 2025
In diesem Leitfaden wird der Endpunkt der CrUX History API (Chrome UX Report History API) vorgestellt, der Zeitreihen mit Daten zur Webleistung bereitstellt. Diese Daten werden wöchentlich aktualisiert und umfassen einen Verlauf von etwa sechs Monaten mit 40 Datenpunkten im Abstand von einer Woche.
In Kombination mit den täglichen Updates vom ursprünglichen CrUX API-Endpunkt können Sie jetzt schnell sowohl die neuesten Daten als auch die bisherigen Daten sehen. So lassen sich Änderungen an Webseiten im Zeitverlauf nachvollziehen.
API auf dieser Seite testen
Tägliche CrUX API abfragen
Wie bereits in einem früheren Artikel zur CrUX API beschrieben, 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 Perzentilwerte für einen bestimmten Erhebungszeitraum von 28 Tagen, in diesem Fall vom 27. Dezember 2022 bis zum 23. Januar 2023.
CrUX History API abfragen
Um den Verlaufsendpunkt aufzurufen, ändern Sie queryRecord in der URL zu queryHistoryRecord im curl-Befehl. Sie können denselben CrUX API-Schlüssel wie für den vorherigen Aufruf verwenden.
collectionPeriodCount gibt die Anzahl der zurückzugebenden Zeitreiheneinträge an. Der Maximalwert ist 40. Wenn nichts angegeben ist, 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 Form einer Reaktion ist ähnlich, aber es gibt viel mehr Daten. Anstelle eines einzelnen Datenpunkts gibt es jetzt Zeitreihen für die Felder mit den Werten für das 75. Perzentil (p75) und die Histogrammdichte.
{
"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 die densities-Zeitreihe für den Bereich von 0 bis 2.500 ms des Messwerts Largest Contentful Paint (LCP) [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. 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 Erfassungszeitraum, der am 3.September 2022 endete.Die Dichte im Zeitraum, der in der Woche danach endete, betrug 0,9187.
Anders ausgedrückt: Wenn wir die letzten Zeitreiheneinträge im Beispiel für https://web.dev interpretieren, sehen wir, dass vom 14. August 2022 bis zum 10. September 2022 91,87% der Seitenaufrufe LCP-Werte unter 2.500 ms, 5,27% Werte zwischen 2.500 ms und 4.000 ms und 2,85% Werte über 4.000 ms hatten.
Ebenso gibt es eine Zeitreihe für die P75-Werte: Der LCP-P75-Wert für den Zeitraum vom 14. August 2022 bis zum 10. September 2022 betrug 1377. Das bedeutet, dass in diesem Erhebungszeitraum 75% der Nutzererfahrungen einen LCP-Wert von weniger als 1.377 ms und 25% der Nutzererfahrungen einen LCP-Wert von mehr als 1.377 ms hatten.
Im Beispiel sind nur 6 Zeitreiheneinträge und Erfassungszeiträume aufgeführt. In Antworten der API werden standardmäßig 25 Zeitreiheneinträge und maximal 40 Zeitreiheneinträge bereitgestellt, wenn "collectionPeriodCount": 40 in der Anfrage angegeben ist. Da die Enddaten für die einzelnen Erhebungszeiträume Samstage sind, die 7 Tage auseinanderliegen, deckt dies mit "collectionPeriodCount": 40 10 Monate ab.
In jeder Antwort ist die Länge der Zeitreihe für die Histogramm-Bin-Dichten und für die P75-Werte genau dieselbe wie die Länge des Arrays im Feld collectionPeriods. Es gibt eine Eins-zu-eins-Entsprechung 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 bereits über das CrUX-Dataset in BigQuery verfügbar. Die Verlaufsdaten auf Seitenebene waren jedoch nur verfügbar, wenn die Daten von den Websites selbst erhoben und gespeichert wurden. Mit der neuen API sind diese Verlaufsdaten auf Seitenebene jetzt verfügbar.
Die Daten auf Seitenebene können auf dieselbe Weise abgefragt werden, aber 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 denselben Berechtigungsvoraussetzungen 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 durch null für die percentilesTimeseries dargestellt. Der Grund für den Unterschied ist, dass Histogrammdichten immer Zahlen sind, während die Perzentile Zahlen oder Strings sein können. CLS verwendet Strings, auch wenn sie wie Zahlen aussehen.
Daten visualisieren
Am einfachsten lassen sich die Daten mit CrUX Vis visualisieren. Dieses Tool wurde speziell entwickelt, um die Leistungsfähigkeit der CrUX History API zu demonstrieren. Weitere Informationen
Wenn Sie ähnliche Diagramme selbst erstellen möchten, haben wir ein Beispiel-Colab erstellt. Mit Colab oder „Colaboratory“ können Sie Python-Code in Ihrem Browser schreiben und ausführen. Im CrUX History API Colab (Quelle) wird Python verwendet, um API-Aufrufe auszuführen und die Daten in Diagrammen darzustellen.
In diesem Colab können Sie durch Ausfüllen eines kurzen Formulars P75-Diagramme und Tri-Bin-Diagramme erstellen, Daten in Tabellenform abrufen und das Anfrage- und Antwortpaar für die CrUX API aufrufen. Sie müssen kein Programmierer sein, um dieses Tool zu verwenden. Sie können sich aber den Python-Code ansehen und ihn in etwas Tolles verwandeln. Wir wünschen Ihnen viel Spaß und freuen uns auf Ihr Feedback.
Sie sind natürlich nicht auf Colab oder Python beschränkt. Dies ist nur ein Beispiel für die Verwendung dieser neuen API. Da die API ein JSON-basierter HTTP-Endpunkt ist, kann sie mit jeder Technologie abgefragt werden.
Fazit
Vor der Einführung des CrUX History API-Endpunkts konnten Websiteinhaber nur eingeschränkt auf Verlaufsdaten aus CrUX zugreifen. Monatliche Daten auf Ursprungsebene waren über BigQuery verfügbar, wöchentliche Daten und historische Daten auf Seitenebene jedoch nicht. Websiteinhaber konnten diese Daten selbst mit der Daily API aufzeichnen, aber oft wurde der Bedarf erst nach einer Regression bei den Messwerten festgestellt.
Wir hoffen, dass Websiteinhaber mit der Einführung dieser CrUX History API ein besseres Verständnis für die sich ändernden Websitemesswerte erhalten und sie als Diagnosetool bei Problemen nutzen können. Wenn Sie die neue API verwenden, können Sie uns gerne Feedback in der Google-Gruppe „Chrome UX Report (Discussions)“ geben.
Danksagungen
Hero-Image von Dave Herring auf Unsplash