Gepubliceerd: 7 februari 2023, Laatst bijgewerkt: 11 april 2025
Deze handleiding introduceert het Chrome UX Report (CrUX) History API- eindpunt, dat tijdreeksen van webprestatiegegevens levert. Deze gegevens worden wekelijks bijgewerkt en geven je inzicht in ongeveer 6 maanden aan historische gegevens, met 40 datapunten die met een tussenpoos van een week worden verzameld.
In combinatie met de dagelijkse updates van het oorspronkelijke CruX API- eindpunt kunt u nu snel zowel de meest recente gegevens als eerdere gebeurtenissen bekijken. Dit maakt het een krachtig hulpmiddel om wijzigingen aan webpagina's in de loop van de tijd te volgen.
Probeer de API op deze pagina.
Raadpleeg de dagelijkse CruX API.
Samenvattend, zoals beschreven in een eerder artikel over de CruX API , kunt u op de volgende manier een momentopname van de veldgegevens voor een specifieke oorsprong verkrijgen:
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 verzamelperiode van 28 dagen, in dit geval van 27 december 2022 tot en met 23 januari 2023.
Raadpleeg de CruX History API.
Om het history-eindpunt aan te roepen, wijzig queryRecord in de URL naar queryHistoryRecord in de curl opdracht. Het gebruik van dezelfde CruX API-sleutel als bij de vorige aanroep werkt. collectionPeriodCount specificeert het aantal tijdreeksitems dat moet worden geretourneerd; 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 algemene vorm van een respons is vergelijkbaar, maar er zijn veel meer gegevens! In plaats van één enkel datapunt zijn er nu tijdreeksen voor de velden die de 75e percentielwaarde (p75) en de histogramdichtheidswaarden bevatten.
{
"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 is de tijdreeks van densities voor het tijdvak van 0 tot 2500 ms van de Largest Contentful Paint (LCP) -metriek [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. Elk van deze dichtheden werd waargenomen tijdens de corresponderende collectionPeriods invoer. De vijfde dichtheid, 0,9183, was bijvoorbeeld de dichtheid voor de vijfde verzamelperiode, die eindigde op 3 september 2022, en 0,9187 was de dichtheid in de periode die de week daarna eindigde.
Met andere woorden, bij het interpreteren van de laatste tijdreeksgegevens in het voorbeeld voor https://web.dev werd vastgesteld dat van 14 augustus 2022 tot en met 10 september 2022 91,87% van de paginaladingen een LCP-waarde had die kleiner was dan 2500 ms, 5,27% een waarde tussen 2500 ms en 4000 ms, en 2,85% een waarde groter dan 4000 ms.
Op dezelfde manier is er een tijdreeks voor de p75-waarden: de LCP p75 voor de periode van 14 augustus 2022 tot en met 10 september 2022 was 1377 ms. Dit betekent dat gedurende deze verzamelperiode 75% van de gebruikerservaringen een LCP had van minder dan 1377 ms, en 25% van de gebruikerservaringen een LCP had van meer dan 1377 ms.
Hoewel het voorbeeld slechts 6 tijdreeksgegevens en verzamelperioden weergeeft, levert de API standaard 25 tijdreeksgegevens en maximaal 40 wanneer "collectionPeriodCount": 40 in het verzoek is gespecificeerd. Aangezien de einddatums van elk van deze verzamelperioden zaterdagen zijn met een tussenpoos van 7 dagen, dekt dit met "collectionPeriodCount": 40 een periode van 10 maanden.
In elke gegeven respons is de lengte van de tijdreeks voor de histogrambindichtheden en voor de p75-waarden exact gelijk 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 ook toegang tot historische gegevens op paginaniveau. Hoewel de gegevens op oorsprongsniveau al eerder beschikbaar waren via de CrUX-dataset op BigQuery , waren de historische gegevens op paginaniveau alleen beschikbaar als sites deze 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 url in plaats van de 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 oorsprongniveau) zijn onderworpen aan dezelfde geschiktheidseisen als de rest van CruX, waardoor het mogelijk is dat bepaalde pagina's geen volledig historisch overzicht hebben. In deze gevallen worden de "ontbrekende" gegevens weergegeven als "NaN" voor de histogramTimeseries tijdreeksdichtheden en null voor de percentilesTimeseries . De reden voor dit verschil is dat de histogramdichtheden altijd getallen zijn, terwijl de percentielen getallen of tekenreeksen kunnen zijn (CLS gebruikt tekenreeksen, zelfs als ze op getallen lijken).
Visualiseer de gegevens
De eenvoudigste manier om de gegevens 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 maken, hebben we een voorbeeld- Colab gemaakt. Een Colab, of 'colaboratorium', stelt je in staat om Python-code te schrijven en uit te voeren vanuit je browser. De CrUX History API Colab ( bron ) gebruikt Python om API-aanroepen te doen en de gegevens in grafieken weer te geven.
Met deze Colab-omgeving kun je p75-grafieken en tri-bin-grafieken maken, gegevens in tabelvorm ophalen en de request-response-paren 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 natuurlijk bekijken en aanpassen tot iets fantastisch! Veel plezier ermee en laat gerust weten wat je ervan vindt!
Uiteraard bent u niet beperkt tot Colab of Python, en dit is slechts één voorbeeld van hoe u deze nieuwe API kunt gebruiken. Als JSON-gebaseerd HTTP-eindpunt is de API toegankelijk vanuit elke technologie.
Conclusie
Vóór de introductie van het CrUX History API-eindpunt waren site-eigenaren beperkt in de historische informatie die ze van CrUX konden verkrijgen. Maandelijkse gegevens op oorsprongsniveau waren beschikbaar via BigQuery, maar wekelijkse gegevens en historische gegevens op paginaniveau ontbraken. Site-eigenaren konden deze gegevens zelf vastleggen met behulp van de dagelijkse API, maar vaak werd de behoefte hieraan pas ontdekt na een terugval in de statistieken.
De hoop is dat de introductie van deze CruX History API website-eigenaren een beter inzicht zal geven in de veranderende statistieken van hun site, en dat het een diagnostisch hulpmiddel zal zijn bij het detecteren van problemen. Als u de nieuwe API gebruikt, is feedback welkom in de Google-groep Chrome UX Report (Discussies) .
Dankbetuigingen
Hoofdafbeelding door Dave Herring op Unsplash