Über die CrUX History API erhalten Sie mit niedriger Latenz Zugriff auf Verlaufsdaten zu echten Nutzererfahrungen, die sich sechs Monate lang auf der Seite und beim Ursprung unterscheiden.
Gängiger Anwendungsfall
Mit der CrUX History API können bisherige Messwerte zur Nutzererfahrung für einen bestimmten URI abgefragt werden, z. B. „Bisherige UX-Trends für den Ursprung https://example.com abrufen“.
Die History API hat dieselbe Struktur wie die tägliche CrUX API, mit dem Unterschied, dass Werte in einem Array angegeben und Schlüssel mit Pluralnamen gekennzeichnet werden, z. B. histogramTimeseries statt histogram oder p75s statt p75.
CrUX API-Schlüssel
Wie bei der Daily API ist auch für die CrUX History API ein Google Cloud API-Schlüssel erforderlich. Derselbe Schlüssel kann für die Daily API und die History API verwendet werden.
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 identifizieren eine bestimmte Gruppe von Daten, 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.
Die CrUX History API ist nur verfügbar, wenn sie nach Formfaktordimension zusammengefasst sind. Dies ist eine allgemeine Geräteklasse, die in PHONE, TABLET und DESKTOP unterteilt ist.
Messwert
Messwerte werden in Zeitreihen statistischer Aggregationen erfasst, bei denen es sich um Histogramme, Perzentile und Brüche handelt.
Histogramme
Wenn Messwerte in einem Histogrammarray ausgedrückt werden, stellt jeder Zeitreiheneintrag den Prozentsatz der Seitenladevorgänge dar, bei denen der Messwert proportional zu allen in ein Intervall fällt. Die Datenpunkte werden in der Reihenfolge der Datumsangaben für den Erfassungszeitraum angezeigt, die auch von der API zurückgegeben werden. Der erste Punkt ist der früheste Zeitraum und der letzte Punkt der jüngste Erhebungszeitraum.
Ein einfaches Histogramm mit drei Bins für einen Beispielmesswert sieht so aus:
{
"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]
}
],
}
Diese Daten zeigen, dass der Beispielmesswert für den ersten Erfassungszeitraum im Verlauf bei 91,90% der Seitenaufrufe zwischen 0 ms und 2.500 ms lag, gefolgt von 92,03%, 91,94%... Die Maßeinheiten sind in diesem Histogramm nicht enthalten. Hier gehen wir von Millisekunden aus.
Außerdem kam bei 5,21% der Seitenladevorgänge der Beispielmesswert im ersten Erfassungszeitraum zwischen 2.500 ms und 4.000 ms im ersten Erfassungszeitraum des Verlaufs auf. Bei 2,88% der Seitenladevorgänge war im ersten Erfassungszeitraum im Verlauf ein Wert von mehr als 4.000 ms aufgetreten.
Perzentile
Messwerte können auch Zeitreihen von Perzentilen enthalten, die für zusätzliche Analysen nützlich sein können.
Die Datenpunkte werden in der Reihenfolge der Datumsangaben für den Erfassungszeitraum angezeigt, die auch von der API zurückgegeben werden. Der erste Punkt ist der früheste Zeitraum und der letzte Punkt der jüngste Erhebungszeitraum.
{
"percentilesTimeseries": {
"p75s": [1362, 1352, 1344, 1356, 1366, 1377]
},
}
Diese Perzentile können bestimmte Messwerte am angegebenen Perzentil für diesen Messwert enthalten. 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.
Brüche
Messwerte können als Zeitreihen von mit Labels gekennzeichneten Bruchteilen ausgedrückt werden. Jedes Label beschreibt einen Seitenaufbau auf eine bestimmte Weise. Die Datenpunkte werden in der Reihenfolge der Datumsangaben für den Erfassungszeitraum angezeigt, die auch von der API zurückgegeben werden. Der erste Punkt ist der früheste Zeitraum und der letzte Punkt der jüngste Erhebungszeitraum.
Beispiel:
{
"fractionTimeseries": {
"desktop": {"fractions": [0.3195, 0.2115, 0.1421]},
"phone": {"fractions": [0.6295, 0.7544, 0.8288]},
"tablet": {"fractions": [0.051, 0.0341, 0.029]}
}
}
In diesem Beispiel zeigt der letzte Datenpunkt, dass 14,21% der Seitenladevorgänge von Computern und 82,88% von Smartphones stammen.
Messwerttypen
Für die CrUX History API werden dieselben Messwerttypen verwendet. Weitere Informationen finden Sie in der Dokumentation zu den täglichen Messwerttypen der CrUX API.
Voraussetzungen für Messwerte
Aufgrund der Voraussetzungen kommt eine Quelle oder URL möglicherweise nur für einige der von der CrUX History API abgedeckten Erhebungszeiträume infrage. In diesen Fällen gibt die CrUX History API "NaN" für die histogramTimeseries-Dichten und null für die percentilesTimeseries für die Erfassungszeiträume zurück, für die keine geeigneten Daten vorliegen. Der Grund für den Unterschied besteht darin, dass die Histogrammdichte immer Zahlen sind, während die Perzentile Zahlen oder Strings sein können. Bei der CLS werden Strings verwendet, auch wenn sie wie Zahlen aussehen.
Wenn beispielsweise für den zweiten Zeitraum keine geeigneten Daten vorliegen, würde das so angezeigt:
{
"histogramTimeseries": [
{
"start": 0,
"end": 2500,
"densities": [0.9190, "NaN", 0.9194, 0.9195, 0.9183, 0.9187]
},
{
"start": 2500,
"end": 4000,
"densities": [0.0521, "NaN", 0.0518, 0.0518, 0.0526, 0.0527]
},
{
"start": 4000,
"densities": [0.0288, "NaN", 0.0286, 0.0285, 0.0290, 0.0285]
}
],
"percentilesTimeseries": {
"p75s": [1362, null, 1344, 1356, 1366, 1377]
},
}
Bei URLs oder Quellen, die im Laufe der Zeit nicht mehr zulässig sind, kann es sein, dass viele Einträge fehlen.
Erfassungszeiträume
Die CrUX History API enthält ein collectionPeriods-Objekt mit einem Array aus firstDate- und endDate-Feldern, die das Start- und Enddatum jedes Aggregationsfensters darstellen. Beispiel:
"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 }
}
]
Diese Erfassungszeiträume sind in aufsteigender Reihenfolge angeordnet und stellen den Datumsbereich der einzelnen Datenpunkte in den anderen Abschnitten der Antwort dar.
Die History API wird jeden Montag aktualisiert und enthält Daten bis zum letzten Samstag (gemäß der standardmäßigen zweitägigen Verzögerung). Sie enthält die Daten der letzten 25 Wochen, also einen Erhebungszeitraum pro Woche.
Da jeder Erhebungszeitraum die aggregierten Daten der letzten 28 Tage enthält und die Erhebungszeiträume auf eine Woche fallen, bedeutet dies, dass sich die Erhebungszeiträume überschneiden. Sie ähneln einem gleitenden Durchschnitt von Daten, wobei in jedem nachfolgenden Zeitraum Daten aus drei Wochen enthalten sind, eine Woche jedoch unterschiedlich ist.
Beispielabfragen
Abfragen werden als JSON-Objekte mit einer POST-Anfrage an https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]" mit Abfragedaten als JSON-Objekt im POST-Text gesendet.
Hinweis: Die Verwendung von queryHistoryRecord ersetzt die queryRecord der täglichen CrUX API.
Hier ein Beispieltext:
{
"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:queryHistoryRecord?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_shiftfirst_contentful_paintfirst_input_delayinteraction_to_next_paintlargest_contentful_paintexperimental_time_to_first_bytenavigation_typesform_factors(nur gemeldet, wenn in der Anfrage keinformFactorangegeben ist)
Wenn kein formFactor-Wert angegeben ist, werden die Werte für alle Formfaktoren aggregiert.
Weitere Beispielabfragen finden Sie im Leitfaden CrUX History 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.
Die History API enthält eine Reihe von Erfassungszeiträumen, die sich jeweils über 28 Tage erstrecken. Da jeder Erhebungszeitraum die aggregierten Daten der letzten 28 Tage enthält und die Erhebungszeiträume auf eine Woche fallen, bedeutet dies, dass sich die Erhebungszeiträume überschneiden. Sie ähneln einem gleitenden Durchschnitt von Daten, wobei in jedem nachfolgenden Zeitraum Daten aus drei Wochen enthalten sind, eine Woche jedoch unterschiedlich ist.
Wöchentliche Updates
Die History API wird jeden Montag um 16:00 Uhr (UTC) aktualisiert und enthält Daten bis zum vorherigen Samstag (gemäß der standardmäßigen zweitägigen Verzögerung). Sie enthält die Daten der letzten 25 Wochen (ungefähr 6 Monate), eine Erhebung pro Woche.
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 History 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:queryHistoryRecord
Die URL verwendet die Syntax der gRPC-Transcodierung.
Anfragetext
Die CrUX History API verwendet dieselben Anfragetexte wie die tägliche CrUX API, mit der Ausnahme, dass das Anfragefeld effectiveConnectionType nicht unterstützt wird.
So fordern Sie beispielsweise die „Largest Contentful Paint“-Werte für Computer für die web.dev-Startseite an:
{
"origin": "https://web.dev/",
"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": {
"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 }
}, {
...
}
]
}
}
Schlüssel
Key definiert alle Dimensionen, mit denen dieser Datensatz als eindeutig identifiziert wird.
{
"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. |
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 |
„Origin“ gibt den Abflugort an, für den dieser Datensatz bestimmt ist. Hinweis: Wenn Sie einen Ursprung angeben, werden die Daten für Ladevorgänge unter diesem Ursprung auf allen Seiten zu Nutzerdaten auf Ursprungsebene zusammengefasst. |
url |
Hinweis: Bei Angabe von |
Messwerte
Ein metric ist ein Satz von Nutzererfahrungsdaten für einen einzelnen Web-Leistungsmesswert, z. B. First Contentful Paint. Es enthält ein zusammenfassendes Histogramm der realen Nutzung von Chrome als Serie von bins.
{
"histogramTimeseries": [
{
object (Bin)
}
],
"percentilesTimeseries": {
object (Percentiles)
}
}
oder
"fractionTimeseries": {
object (Fractions)
}
| Felder | |
|---|---|
histogramTimeseries[] |
Das Zeitachsen-Histogramm der Nutzererfahrung für einen Messwert. Das Zeitreihen-Histogramm enthält mindestens einen Klassen und die Dichten aller Klassen ergeben zusammen ~1. Fehlende Werte für diesen speziellen Erfassungszeitraum sind als |
percentilesTimeseries |
Allgemeine nützliche Perzentile des Messwerts. Der Werttyp für die Perzentile entspricht den Werttypen für die Histogrammgruppen. Fehlende Werte für diesen speziellen Erfassungszeitraum sind als |
fractionTimeseries |
Dieses Objekt enthält Zeitreihen gekennzeichneter Bruchteile, die zusammen ungefähr 1 pro Eintrag ergeben. Brüche werden auf vier Dezimalstellen gerundet. Fehlende Einträge werden als"NaN" für alle Brüche ausgedrückt. |
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,
"densities": [number, number, number...etc.]
}
| 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. |
densities |
Eine Zeitreihe des Anteils der Nutzer, bei denen der Wert dieses Containers für den angegebenen Messwert aufgetreten ist. 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 | |
|---|---|
p75s |
Zeitreihe der Werte, bei denen der angegebene Messwert bei 75% der Seitenladevorgänge bei oder unter diesem Wert liegt. |
Brüche
Fractions enthält Zeitreihen gekennzeichneter Brüche, die zusammen ungefähr 1 pro Eintrag ergeben.
Jedes Label beschreibt einen Seitenaufbau auf irgendeine Art und Weise. So können Sie sich die so dargestellten Messwerte als unterschiedliche Werte anstelle von numerischen Werten vorstellen. Die Bruchteile geben an, wie häufig ein bestimmter Wert gemessen wurde.
{
"label_1": { "fractions": array[fraction]},
"label_1": { "fractions": array[fraction]},
...
"label_n": { "fractions": array[fraction]}
}
Ähnlich wie die Dichtewerte in Histogrammklassen ist jeder fraction eine Zahl 0.0 <= value <= 1.0, deren Summe ungefähr 1, 0 ergibt. Wenn der Messwert für einen bestimmten Erfassungszeitraum nicht verfügbar ist, ist der entsprechende Eintrag in allen Arrays von Bruchteilen "NaN".
| Felder | |
|---|---|
p75s |
Zeitreihe der Werte, bei denen der angegebene Messwert bei 75% der Seitenladevorgänge bei oder unter diesem Wert liegt. |
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
Für die CrUX History API gilt dasselbe Limit wie die CrUX API für 150 Abfragen pro Minute und Google Cloud-Projekt für beide APIs, die kostenlos angeboten werden. 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.