Pubblicato il 7 febbraio 2023, ultimo aggiornamento l'11 aprile 2025
Questa guida introduce l'endpoint dell'API CrUX History (Chrome UX Report), che fornisce serie temporali di dati sul rendimento 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 quelli accaduti in precedenza, il che lo rende uno strumento potente per visualizzare le modifiche delle pagine web nel tempo.
Prova l'API in questa pagina
Esegui query sull'API CrUX giornaliera
Per riassumere un articolo precedente sull'API CrUX, puoi ottenere un'istantanea dei dati dei campi per un'origine specifica 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 percentili per un periodo di raccolta specifico di 28 giorni, in questo caso dal 27 dicembre 2022 al 23 gennaio 2023.
Esegui query sull'API CrUX History
Per chiamare l'endpoint della cronologia, modifica queryRecord nell'URL in queryHistoryRecord nel comando curl. L'utilizzo della stessa
chiave API CrUX della chiamata precedente funzionerà.
collectionPeriodCount specifica il numero di voci di serie temporali da restituire; il valore massimo è 40. Se non viene 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 presenti 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à per il quinto periodo di raccolta, terminato il 3 settembre 2022, e 0,9187 era la densità nel periodo terminato la settimana successiva.
In altre parole, interpretando le ultime voci della serie temporale nell'esempio per web.dev, è stato rilevato che dal 14 agosto 2022 al 10 settembre 2022, il 91, 87% dei caricamenti di pagina 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: l'LCP p75 dal 14 agosto 2022 al 10 settembre 2022 era 1377. Ciò significa che, per questo periodo di raccolta, il 75% delle esperienze utente aveva un LCP inferiore a 1377 ms e il 25% delle esperienze utente aveva 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 nella richiesta viene specificato "collectionPeriodCount": 40. Poiché le
date di fine di ciascuno di questi periodi di raccolta sono i sabati a distanza di 7 giorni
l'uno dall'altro, con "collectionPeriodCount": 40 si coprono 10 mesi.
In una risposta specifica, la lunghezza della serie temporale per le densità dei bucket dell'istogramma e per i valori p75 sarà esattamente la stessa della lunghezza dell'array nel campo collectionPeriods: esiste una corrispondenza uno a uno basata sull'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, i dati storici a livello di pagina erano disponibili solo se i siti li raccoglievano e li memorizzavano. La nuova API ora sblocca 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 stessi 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
histogramTimeseries densità e da null per percentilesTimeseries. Il motivo della differenza è che le densità dell'istogramma sono sempre numeri, mentre i percentili 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ù in nella documentazione di CrUX Vis.
Per generare autonomamente grafici simili, abbiamo creato un esempio Colab. Un Colab, o "Colaboratory", ti consente di scrivere ed eseguire codice Python direttamente dal browser. Il Colab dell'API CrUX History (origine) utilizza Python per effettuare chiamate all'API e rappresentare i dati in un grafico.
Questo Colab ti consente di creare grafici p75, grafici a tre bucket, ottenere dati in formato tabellare e visualizzare la coppia richiesta-risposta per l'API CrUX, compilando un breve modulo. Non devi essere un programmatore per utilizzarlo, ma puoi esaminare il codice Python e modificarlo per creare qualcosa di straordinario.
Questo è solo un esempio di come utilizzare questa nuova API. Essendo un endpoint HTTP basato su JSON, è possibile eseguire query sull'API da qualsiasi tecnologia.
Conclusione
Prima dell'introduzione dell'endpoint dell'API CrUX History, i proprietari dei siti avevano informazioni storiche limitate che potevano ottenere da CrUX. I dati mensili a livello di origine erano disponibili tramite BigQuery, ma non erano disponibili dati settimanali né dati storici a livello di pagina. I proprietari dei siti potevano registrare questi dati autonomamente utilizzando l'API giornaliera, ma spesso la necessità di farlo veniva scoperta solo dopo una regressione delle metriche.
Ci auguriamo che l'introduzione di questa API CrUX History consenta ai proprietari dei siti di comprendere meglio le metriche dei siti in continua evoluzione e di utilizzarla come strumento di diagnostica in caso di problemi. Se utilizzi la nuova API, ti invitiamo a lasciare un feedback nel gruppo Google Chrome UX Report (Discussions).