Come usare l'API CrUX History

Johannes Henkel

Jasmine Yan

Barry Pollard

Pubblicato: 7 febbraio 2023, ultimo aggiornamento: 11 aprile 2025

Questa guida introduce l'endpoint dell'API Chrome UX Report (CrUX) History, 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 utilizzata con gli aggiornamenti giornalieri dell'endpoint API CrUX originale, ora puoi visualizzare rapidamente sia i dati più recenti sia quelli precedenti, il che la rende uno strumento potente per monitorare le modifiche alle pagine web nel tempo.

Prova l'API in questa pagina

Fai una prova!

Eseguire query sull'API CrUX giornaliera

Per riepilogare quanto detto in un articolo precedente sull'API CrUX, puoi ottenere un'istantanea dei dati sul 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 percentili per un determinato periodo di raccolta di 28 giorni, in questo caso dal 27 dicembre 2022 al 23 gennaio 2023.

Eseguire 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 della serie temporale da restituire; il 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 complessiva di una risposta è simile, ma ci sono molti più dati. Anziché un singolo punto dati, ora sono presenti serie temporali per i campi contenenti i valori del 75° percentile (p75) e della 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].. Ciascuna 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 termina il 3 settembre 2022, mentre 0,9187 era la densità nel periodo che termina la settimana successiva.

In altre parole, interpretando le ultime voci delle serie temporali nell'esempio per https://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: il valore 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 ha avuto un valore LCP inferiore a 1377 ms e il 25% delle esperienze utente ha avuto un valore LCP superiore a 1377 ms.

Anche se l'esempio elenca 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 i sabati a distanza di 7 giorni, con "collectionPeriodCount": 40 coprono 10 mesi.

Nota:a differenza dell'API giornaliera, l'API CrUX History viene aggiornata solo una volta alla settimana, il lunedì (inclusi i dati fino al sabato precedente). Tuttavia, come l'API giornaliera, ogni valore nell'API CrUX History viene misurato in base ai 28 giorni precedenti. Ciò significa che l'API History deve rappresentare gli stessi dati disponibili utilizzando l'API giornaliera per la data specificata. Ora è possibile eseguire query in modo retrospettivo. Tuttavia, ciò significa che l'API History contiene periodi di dati sovrapposti, ma, in quanto analisi delle tendenze, è utile per monitorare la variazione delle metriche nel tempo.

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.

Eseguire query sui dati a livello di pagina

Oltre ai dati a livello di origine, l'API CrUX History consente l'accesso 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 memorizzavano autonomamente. 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 densità histogramTimeseries 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ù nella documentazione di CrUX Vis.

Per generare grafici simili, abbiamo creato un Colab di esempio. Colab, o "Colaboratory", ti permette di scrivere ed eseguire Python dal browser. L'API CrUX History Colab (origine) utilizza Python per effettuare chiamate all'API e tracciare i dati.

Questo Colab ti consente di creare grafici p75 e tri-bin, ottenere dati in formato tabellare e visualizzare la coppia richiesta/risposta per l'API CrUX compilando un breve modulo. Non è necessario essere un programmatore per utilizzarlo, ma puoi sicuramente esaminare il codice Python e modificarlo per creare qualcosa di straordinario. Buona lettura e non esitare a inviarci un feedback su ciò che trovi.

Naturalmente non sei limitato a Colab o Python e questo è solo un esempio di come utilizzare questa nuova API. In quanto endpoint HTTP basato su JSON, l'API può essere interrogata da qualsiasi tecnologia.

Conclusione

Prima dell'introduzione dell'endpoint API CrUX History, i proprietari dei siti potevano ottenere solo una quantità limitata di informazioni storiche da CrUX. I dati mensili a livello di origine erano disponibili utilizzando BigQuery, ma i dati settimanali e i dati storici a livello di pagina non erano disponibili. I proprietari dei siti potrebbero registrare questi dati autonomamente utilizzando l'API giornaliera, ma spesso la necessità di farlo viene scoperta solo dopo una regressione delle metriche.

L'introduzione di questa API CrUX History ha lo scopo di consentire ai proprietari dei siti di comprendere meglio le metriche del sito in evoluzione e di utilizzarla come strumento diagnostico in caso di problemi. Se utilizzi la nuova API, ti invitiamo a inviare feedback al gruppo Google Chrome UX Report (Discussioni).

Ringraziamenti

Hero image di Dave Herring su Unsplash