Gepubliceerd: 7 feb. 2023, Laatst bijgewerkt: 11 apr. 2025
Deze handleiding introduceert het Chrome UX Report (CrUX) History API- eindpunt, dat tijdreeksen van webprestatiegegevens levert. Deze gegevens worden wekelijks bijgewerkt en geven u inzicht in de geschiedenis van ongeveer 6 maanden, met 40 datapunten met een tussenpoos van een week.
Wanneer u dit gebruikt in combinatie met de dagelijkse updates van het oorspronkelijke CrUX API- eindpunt, kunt u nu snel zowel de meest recente gegevens als wat er eerder is gebeurd, bekijken. Dit is een krachtig hulpmiddel om wijzigingen in webpagina's in de loop van de tijd te bekijken.
Probeer de API op deze pagina
Vraag de dagelijkse CrUX API op
Om een eerder artikel over de CrUX API samen te vatten: u kunt op deze manier een momentopname van de veldgegevens voor een bepaalde oorsprong krijgen:
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 }
}
}
}
Deze momentopname bevat histogramdichtheidswaarden en percentielwaarden voor een specifieke verzamelingsperiode van 28 dagen, in dit geval van 27 december 2022 tot en met 23 januari 2023.
Vraag de CrUX History API op
Om het geschiedenis-eindpunt aan te roepen, wijzigt u queryRecord in de URL in queryHistoryRecord in de curl opdracht. Het gebruik van dezelfde CrUX API-sleutel als bij de vorige aanroep werkt. collectionPeriodCount specificeert het aantal te retourneren tijdreeksitems; het maximum is 40. Indien niet gespecificeerd, is de standaardwaarde 25.
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}'
De algehele vorm van een respons is vergelijkbaar, maar er zijn veel meer gegevens! In plaats van één enkel gegevenspunt zijn er nu tijdreeksen voor de velden met het 75e percentiel (p75) en histogramdichtheidswaarden.
{
"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 dit voorbeeld zijn de tijdreeksen voor de densities van de bucket van 0 tot 2500 ms van de metriek Largest Contentful Paint (LCP) [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. Elk van deze dichtheden werd waargenomen tijdens de bijbehorende collectionPeriods invoer. De vijfde dichtheid, 0,9183, was bijvoorbeeld de dichtheid voor de vijfde verzamelingsperiode, eindigend op 3 september 2022, en 0,9187 was de dichtheid in de periode die de week erna eindigde.
Met andere woorden, bij interpretatie van de laatste tijdreeksvermeldingen in het voorbeeld voor https://web.dev werd vastgesteld dat van 14 augustus 2022 tot 10 september 2022 91,87% van de paginaladingen LCP-waarden had die kleiner waren dan 2500 ms, 5,27% had waarden tussen 2500 ms en 4000 ms en 2,85% had waarden die groter waren dan 4000 ms.
Er is eveneens een tijdreeks voor de p75-waarden: de LCP p75 voor de periode van 14 augustus 2022 tot en met 10 september 2022 was 1377 Dit betekent dat in deze verzamelperiode 75% van de gebruikerservaringen een LCP van minder dan 1377 ms had en 25% van de gebruikerservaringen een LCP van meer dan 1377 ms.
Hoewel het voorbeeld slechts 6 tijdreeksitems en verzamelperioden bevat, leveren de API-antwoorden standaard 25 tijdreeksitems en maximaal 40 items op wanneer "collectionPeriodCount": 40 in de aanvraag is opgegeven. Omdat de einddatums voor elk van deze verzamelperioden zaterdagen zijn die 7 dagen uit elkaar liggen, beslaat "collectionPeriodCount": 40 10 maanden.
In elk gegeven antwoord zal de lengte van de tijdreeks voor de histogrambindichtheden en voor de p75-waarden exact gelijk zijn aan de lengte van de array in het veld collectionPeriods : er is een één-op-één-correspondentie op basis van de index in deze arrays.
Gegevens op paginaniveau opvragen
Naast gegevens op oorsprongsniveau biedt de CrUX History API toegang tot historische gegevens op paginaniveau. Hoewel de gegevens op oorsprongsniveau voorheen beschikbaar waren via de CrUX-dataset op BigQuery (of via het CrUX Dashboard ), waren de historische gegevens op paginaniveau alleen beschikbaar als sites de gegevens zelf verzamelden en opsloegen. De nieuwe API ontsluit nu die historische gegevens op paginaniveau.
De gegevens op paginaniveau kunnen op dezelfde manier worden opgevraagd, maar dan met behulp van url in plaats van origin in de payload:
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/"}'
Historische gegevens op paginaniveau (en bronniveau) vallen onder dezelfde toelatingseisen als de rest van CrUX, waardoor met name pagina's mogelijk geen volledig historisch overzicht hebben. In deze gevallen worden de "ontbrekende" gegevens weergegeven als "NaN" voor de histogramTimeseries -dichtheden en null voor de percentilesTimeseries . De reden voor dit verschil is dat de histogram-dichtheden altijd getallen zijn, terwijl de percentielen getallen of strings kunnen zijn (CLS gebruikt strings, zelfs als ze op getallen lijken).
Visualiseer de gegevens
De eenvoudigste manier om de data te visualiseren is via CrUX Vis, een tool die speciaal is ontwikkeld om de kracht van de CrUX History API te demonstreren. Lees meer in de CrUX Vis-documentatie .
Om zelf vergelijkbare grafieken te genereren, hebben we een voorbeeld gemaakt van Colab . Met een Colab, of 'Colaboratory', kun je Python schrijven en uitvoeren vanuit je browser. De CrUX History API van Colab ( bron ) gebruikt Python om de API aan te roepen en de gegevens in kaart te brengen.
Met deze Colab kun je p75-grafieken en tri-bin-grafieken maken, gegevens in tabelvorm ophalen en het verzoek- en antwoordpaar voor de CrUX API bekijken door een kort formulier in te vullen. Je hoeft geen programmeur te zijn om dit te gebruiken, maar je kunt de Python-code zeker bekijken en er iets fantastisch van maken! Veel plezier ermee en aarzel niet om feedback te geven op je bevindingen!
Natuurlijk ben je niet beperkt tot Colab of Python; dit is slechts één voorbeeld van hoe je deze nieuwe API kunt gebruiken. Als JSON-gebaseerd HTTP-eindpunt is de API vanaf elke technologie raadpleegbaar.
Conclusie
Vóór de introductie van het CrUX History API-eindpunt waren site-eigenaren beperkt in de historische informatie die ze uit CrUX konden verkrijgen. Maandelijkse gegevens op oorsprongsniveau waren beschikbaar via BigQuery en het CrUX Dashboard, maar wekelijkse gegevens waren niet beschikbaar, evenmin als historische gegevens op paginaniveau. Site-eigenaren konden deze gegevens zelf registreren met de dagelijkse API, maar vaak werd de noodzaak hiervan pas ontdekt na een terugval in de statistieken.
Met de introductie van deze CrUX History API hopen we website-eigenaren meer inzicht te geven in de veranderende statistieken van hun site en het te gebruiken als diagnosetool bij problemen. Als u de nieuwe API gebruikt, is feedback welkom in de Chrome UX Report (Discussies) Google-groep .
Dankbetuigingen
Heldenafbeelding door Dave Herring op Unsplash