Pubblicato: 7 febbraio 2023, ultimo aggiornamento: 11 aprile 2025
Questa guida illustra l'endpoint dell'API History del Report sull'esperienza utente di Chrome (CrUX), che fornisce serie temporali di dati sulle prestazioni web. Questi dati vengono aggiornati settimanalmente e ti consentono di visualizzare circa 6 mesi di cronologia, con 40 punti dati distanziati di una settimana.
Se utilizzato con gli aggiornamenti giornalieri dell'endpoint dell'API CrUX originale, ora puoi visualizzare rapidamente sia i dati più recenti sia ciò che è accaduto in precedenza, il che lo rende uno strumento efficace per vedere le modifiche alle pagine web nel tempo.
Prova l'API in questa pagina
Esegui query sull'API CrUX giornaliera
Per riepilogare quanto descritto in un articolo precedente sull'API CrUX, puoi ottenere uno snapshot dei dati di campo per una determinata origine in questo modo:
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 }
}
}
}
Questa istantanea include i valori di densità dell'istogramma e i valori percentile per un determinato periodo di raccolta di 28 giorni, in questo caso dal 27 dicembre 2022 al 23 gennaio 2023.
Esegui query sull'API History di CrUX
Per chiamare l'endpoint della cronologia, sostituisci queryRecord nell'URL con queryHistoryRecord nel comando curl. Puoi utilizzare la stessa chiave API CrUX utilizzata per la chiamata precedente.
collectionPeriodCount specifica il numero di voci delle serie temporali da restituire; il valore massimo è 40. Se non specificato, il valore predefinito è 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}'
La forma generale di una risposta è simile, ma ci sono molti più dati. Anziché un singolo punto dati, ora sono disponibili serie temporali per i campi contenenti il 75° percentile (p75) e i valori di densità dell'istogramma.
{
"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 questo esempio, la serie temporale densities per il bucket da 0 a 2500 ms della metrica Largest Contentful Paint (LCP) è [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].. Ognuna di queste densità è stata osservata durante la voce collectionPeriods corrispondente. Ad esempio, la quinta densità, 0,9183, era la densità del quinto periodo di raccolta, che terminava il 3 settembre 2022, mentre 0,9187 era la densità del periodo che terminava la settimana successiva.
In altre parole, dall'interpretazione delle ultime voci della serie temporale nell'esempio per https://web.dev, è emerso che dal 14 agosto 2022 al 10 settembre 2022 il 91,87% dei caricamenti di pagine aveva valori LCP inferiori a 2500 ms, il 5,27% aveva valori compresi tra 2500 ms e 4000 ms e il 2,85% aveva valori superiori a 4000 ms.
Allo stesso modo, esiste una serie temporale per i valori p75: il valore p75 LCP dal 14 agosto 2022 al 10 settembre 2022 è stato 1377. Ciò significa che, per questo periodo di raccolta, il 75% delle esperienze utente ha avuto un LCP inferiore a 1377 ms e il 25% delle esperienze utente ha avuto un LCP superiore a 1377 ms.
Sebbene l'esempio elenchi solo 6 voci di serie temporali e periodi di raccolta, le risposte dell'API forniscono 25 voci di serie temporali per impostazione predefinita e un massimo di 40 quando "collectionPeriodCount": 40 è specificato nella richiesta. Poiché le date di fine di ciascuno di questi periodi di raccolta sono sabati distanti 7 giorni, con "collectionPeriodCount": 40 vengono coperti 10 mesi.
In una determinata risposta, la lunghezza della serie temporale per le densità dei bin dell'istogramma e per i valori p75 sarà esattamente uguale alla lunghezza dell'array nel campo collectionPeriods: esiste una corrispondenza uno a uno in base all'indice di questi array.
Esegui query sui dati a livello di pagina
Oltre ai dati a livello di origine, l'API CrUX History consente di accedere ai dati storici a livello di pagina. Sebbene i dati a livello di origine fossero disponibili in precedenza utilizzando il set di dati CrUX su BigQuery (o la dashboard CrUX), i dati storici a livello di pagina erano disponibili solo se i siti raccoglievano e archiviavano i dati stessi. La nuova API ora consente di accedere a questi dati storici a livello di pagina.
È possibile eseguire query sui dati a livello di pagina nello stesso modo, ma utilizzando url anziché origin nel 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/"}'
I dati storici a livello di pagina (e di origine) sono soggetti agli stesse requisiti di idoneità del resto di CrUX, pertanto le pagine in particolare potrebbero non avere un record storico completo. In questi casi, i dati "mancanti" saranno rappresentati da "NaN" per le densità histogramTimeseries e da null per percentilesTimeseries. La ragione della differenza è che le densità dell'istogramma sono sempre numeri, mentre i percentile possono essere numeri o stringhe (CLS utilizza stringhe, anche se sembrano numeri).
Visualizzare i dati
Il modo più semplice per visualizzare i dati è tramite CrUX Vis, uno strumento creato appositamente per dimostrare la potenza dell'API CrUX History. Scopri di più nella documentazione di CrUX Vis.
Per generare autonomamente grafici simili, abbiamo creato un Colab di esempio. Un Colab, o "Colaboratory", ti consente di scrivere ed eseguire Python dal browser. Colab dell'API CrUX History (source) utilizza Python per effettuare chiamate all'API e creare grafici dei dati.
Questo Colab ti consente di creare grafici p75, grafici a tre intervalli, ottenere dati in formato tabulare e visualizzare la coppia di richiesta e risposta per l'API CrUX compilando un breve modulo. Non è necessario essere programmatori per utilizzarlo, ma puoi sicuramente esaminare il codice Python e modificarlo in modo sorprendente. Buon divertimento e non esitare a inviarci un feedback su ciò che trovi.
Ovviamente non sei limitato a Colab o Python e questo è solo un esempio di come utilizzare questa nuova API. Poiché è un endpoint HTTP basato su JSON, l'API è disponibile per query da qualsiasi tecnologia.
Conclusione
Prima dell'introduzione dell'endpoint dell'API CrUX History, i proprietari di siti potevano ottenere informazioni storiche limitate da CrUX. I dati mensili a livello di origine erano disponibili utilizzando BigQuery e la dashboard CrUX, ma non erano disponibili i dati settimanali né i dati storici a livello di pagina. I proprietari di siti potevano registrare questi dati autonomamente utilizzando l'API giornaliera, ma spesso la necessità di farlo è stata scoperta solo dopo una regressione nelle metriche.
L'introduzione di questa API CrUX History dovrebbe consentire ai proprietari di siti di comprendere meglio le metriche in evoluzione del loro sito e di utilizzarla come strumento di diagnostica in caso di problemi. Se utilizzi la nuova API, puoi inviare un feedback nel gruppo Google Chrome UX Report (Discussions).
Ringraziamenti
Immagine hero di Dave Herring su Unsplash