L'API CrUX History offre accesso a bassa latenza a sei mesi di dati storici sull'esperienza utente reale con granularità a livello di pagina e di origine.
Caso d'uso comune
L'API CrUX History consente di eseguire query sulle metriche storiche dell'esperienza utente per un URI specifico, ad esempio "Ottieni le tendenze storiche dell'esperienza utente per l'origine https://example.com".
L'API History segue la stessa struttura dell'API CrUX giornaliera, tranne per il fatto che i valori sono forniti in un array e le chiavi sono etichettate con nomi plurali (ad esempio histogramTimeseries anziché histogram o p75s anziché p75).
Chiave API CrUX
Come per l'API giornaliera, l'utilizzo dell'API CrUX History richiede una chiave API Google Cloud di cui è stato eseguito il provisioning per l'utilizzo di Chrome UX Report API. La stessa chiave può essere utilizzata per le API giornaliere e della cronologia.
Acquisizione e utilizzo di una chiave API
Ottieni una chiaveIn alternativa, creane uno nella pagina Credenziali.
Una volta ottenuta una chiave API, la tua applicazione può aggiungere il parametro di querykey=yourAPIKey a tutti gli URL di richiesta.
La chiave API è sicura per l'inserimento negli URL e non richiede alcuna codifica.
Consulta la sezione Esempi di query.
Modello dei dati
Questa sezione descrive in dettaglio la struttura dei dati nelle richieste e nelle risposte.
Registra
Un'informazione specifica su una pagina o un sito. Un record può contenere dati specifici per un identificatore e per una combinazione specifica di dimensioni. Un record può contenere i dati di una o più metriche.
Identificatori
Gli identificatori specificano quali record devono essere cercati. In CrUX questi identificatori sono pagine web e siti web.
Origine
Quando l'identificatore è un'origine, tutti i dati presenti per tutte le pagine dell'origine vengono aggregati. Ad esempio, supponiamo che l'origine http://www.example.com abbia pagine come indicato da questa sitemap:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Ciò significa che, quando esegui una query sul Report sull'esperienza utente di Chrome con l'origine impostata su http://www.example.com, i dati relativi a http://www.example.com/, http://www.example.com/foo.html e http://www.example.com/bar.html verranno restituiti aggregati, perché sono tutte pagine di questa origine.
URL
Quando l'identificatore è un URL, verranno restituiti solo i dati relativi a quell'URL specifico. Esamina di nuovo la sitemap di origine http://www.example.com:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Se l'identificatore è impostato su URL con il valore http://www.example.com/foo.html, verranno restituiti solo i dati relativi a quella pagina.
Dimensioni
Le dimensioni identificano un gruppo specifico di dati in base al quale viene aggregato un record. Ad esempio, un fattore di forma pari a PHONE indica che il record contiene informazioni sui caricamenti effettuati su un dispositivo mobile.
Fattore di forma
L'API CrUX History è disponibile solo aggregata per la dimensione del fattore di forma. Si tratta di una classe generale di dispositivi suddivisa in PHONE, TABLET e DESKTOP.
Metrica
Registriamo le metriche nelle serie temporali di aggregazioni statistiche, ovvero istogrammi, percentile e frazioni.
Istogrammi
Quando le metriche sono espresse in un array di istogrammi, ogni voce della serie temporale rappresenta la percentuale di caricamenti di pagine per i quali la metrica rientra in un intervallo, proporzionalmente a tutti. I punti dati sono presentati nell'ordine delle date del periodo di raccolta restituite anche dall'API, con il primo punto che corrisponde al periodo più antico e il punto finale che corrisponde al periodo di raccolta più recente.
Un istogramma con tre intervalli per una metrica di esempio ha il seguente aspetto:
{
"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]
}
],
}
Questi dati indicano che il 91,90% dei caricamenti di pagine ha registrato il valore della metrica di esempio compreso tra 0 ms e 2500 ms per il primo periodo di raccolta nella cronologia, seguito dal 92,03%, 91,94%... Le unità della metrica non sono contenute in questo istogramma, in questo caso assumeremo millisecondi.
Inoltre, il 5,21% dei caricamenti di pagina ha registrato un valore della metrica di esempio compreso tra 2500 ms e 4000 ms nel primo periodo di raccolta della cronologia e il 2,88% dei caricamenti di pagina ha registrato un valore superiore a 4000 ms nel primo periodo di raccolta della cronologia.
Percentili
Le metriche possono anche contenere serie temporali di percentile che possono essere utili per analisi aggiuntive.
I punti dati sono presentati nell'ordine delle date del periodo di raccolta restituite anche dall'API, con il primo punto che corrisponde al periodo più antico e il punto finale che corrisponde al periodo di raccolta più recente.
{
"percentilesTimeseries": {
"p75s": [1362, 1352, 1344, 1356, 1366, 1377]
},
}
Questi percentile possono mostrare valori specifici della metrica nel percentile specificato per la metrica. Si basano sull'insieme completo di dati disponibili e non sui dati finali raggruppati, pertanto non corrispondono necessariamente a un percentile interpolato basato sull'istogramma finale raggruppato.
Frazioni
Le metriche possono essere espresse come serie temporali di frazioni etichettate; ogni etichetta descrive un caricamento di pagina in un determinato modo. I punti dati sono presentati nell'ordine delle date del periodo di raccolta restituite anche dall'API, con il primo punto che corrisponde al periodo più antico e il punto finale che corrisponde al periodo di raccolta più recente.
Esempio:
{
"fractionTimeseries": {
"desktop": {"fractions": [0.3195, 0.2115, 0.1421]},
"phone": {"fractions": [0.6295, 0.7544, 0.8288]},
"tablet": {"fractions": [0.051, 0.0341, 0.029]}
}
}
In questo esempio, il punto dati più recente indica che il 14,21% dei caricamenti di pagine proviene da computer e l'82,88% da smartphone.
Tipi di valori delle metriche
Poiché l'API CrUX History utilizza gli stessi tipi di valori delle metriche, per ulteriori dettagli puoi consultare la documentazione sui tipi di valori delle metriche giornaliere dell'API CrUX.
Idoneità delle metriche
In base ai criteri di idoneità, un'origine o un URL potrebbe essere idoneo solo per alcuni dei periodi di raccolta coperti dall'API CrUX History. In questi casi, l'API CrUX History restituirà "NaN" per le densità histogramTimeseries e null per percentilesTimeseries per i periodi di raccolta che non hanno dati idonei. 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).
Ad esempio, se il secondo periodo non conteneva dati idonei, verrà visualizzato come segue:
{
"histogramTimeseries": [
{
"start": 0,
"end": 2500,
"densities": [0.9190, "NaN", 0.9194, 0.9195, 0.9183, 0.9187]
},
{
"start": 2500,
"end": 4000,
"densities": [0.0521, "NaN", 0.0518, 0.0518, 0.0526, 0.0527]
},
{
"start": 4000,
"densities": [0.0288, "NaN", 0.0286, 0.0285, 0.0290, 0.0285]
}
],
"percentilesTimeseries": {
"p75s": [1362, null, 1344, 1356, 1366, 1377]
},
}
Per gli URL o le origini che diventano idonei o meno nel tempo, potresti notare molte voci mancanti.
Periodi di raccolta
L'API CrUX History contiene un oggetto collectionPeriods con un array di campi firstDate e endDate che rappresentano le date di inizio e di fine di ogni finestra di aggregazione. Ad esempio:
"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 }
}
]
Questi periodi di raccolta sono in ordine crescente e rappresentano l'intervallo di date di ciascuno dei punti dati nelle altre sezioni della risposta.
L'API History viene aggiornata ogni lunedì e contiene i dati fino al sabato precedente (in base al ritardo standard di 2 giorni). Contiene i dati delle 40 settimane precedenti, ovvero un periodo di raccolta per settimana. Per impostazione predefinita, vengono restituiti 25 periodi di raccolta. Questo valore può essere modificato impostando "collectionPeriodCount" nella richiesta su un numero compreso tra 1 e 40.
Poiché ogni periodo di raccolta contiene i dati aggregati dei 28 giorni precedenti e i periodi di raccolta sono settimanali, questi periodi si sovrappongono. Sono simili a una media mobile dei dati, con tre settimane di dati inclusi in ogni periodo successivo e una settimana diversa.
Esempi di query
Le query vengono inviate come oggetti JSON utilizzando una richiesta POST a https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]" con i dati di query come oggetto JSON nel corpo del POST.
Tieni presente che queryHistoryRecord sostituisce queryRecord dell'API CrUX giornaliera.
Un corpo di esempio è:
{
"origin": "https://example.com",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Ad esempio, può essere chiamato da curl con la seguente riga di comando (sostituendo API_KEY con la tua chiave):
curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'
I dati a livello di pagina sono disponibili tramite l'API passando una proprietà url nella query anziché origin:
{
"url": "https://example.com/page",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Se la proprietà metrics non è impostata, verranno restituite tutte le metriche disponibili:
cumulative_layout_shiftfirst_contentful_paintinteraction_to_next_paintlargest_contentful_paintexperimental_time_to_first_bytelargest_contentful_paint_resource_typelargest_contentful_paint_image_time_to_first_bytelargest_contentful_paint_image_resource_load_delaylargest_contentful_paint_image_resource_load_durationlargest_contentful_paint_image_element_render_delaynavigation_typesround_trip_timeform_factors(viene segnalato solo se nella richiesta non è specificato alcunformFactor)
Se non viene fornito alcun valore formFactor, i valori verranno aggregati in tutti i fattori di forma.
Per altri esempi di query, consulta la guida Utilizzo dell'API History di CrUX.
Pipeline di dati
Il set di dati CrUX viene elaborato tramite una pipeline per consolidare, aggregare e filtrare i dati prima che diventino disponibili tramite l'API.
La media mobile
I dati del report sull'esperienza utente di Chrome sono una media mobile di 28 giorni delle metriche aggregate. Ciò significa che i dati presentati nel Report sull'esperienza utente di Chrome in un determinato momento sono in realtà i dati degli ultimi 28 giorni aggregati.
L'API History contiene una serie di periodi di raccolta, ciascuno dei quali si estende per 28 giorni. Poiché ogni periodo di raccolta contiene i dati aggregati dei 28 giorni precedenti e i periodi di raccolta sono settimanali, questi periodi si sovrappongono. Sono simili a una media mobile dei dati, con tre settimane di dati inclusi in ogni periodo successivo e una settimana diversa.
Aggiornamenti settimanali
L'API History viene aggiornata ogni lunedì intorno alle 04:00 UTC e contiene i dati fino al sabato precedente (in base al ritardo standard di 2 giorni). Contiene i dati delle 40 settimane precedenti (circa 10 mesi), ovvero un periodo di raccolta a settimana. Tieni presente che per impostazione predefinita vengono restituite 25 voci per serie temporale, ma questo valore può essere ignorato specificando il parametro di richiesta collectionPeriodCount.
Non esiste un accordo sul livello del servizio per i tempi di aggiornamento; viene eseguito ogni giorno secondo il criterio del massimo impegno.
Schema
Esiste un unico endpoint per l'API CrUX History che accetta richieste HTTP POST. L'API restituisce un record contenente uno o più metrics corrispondenti ai dati sul rendimento dell'origine o della pagina richiesta.
Richiesta HTTP
POST https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord
L'URL utilizza la sintassi di transcodifica gRPC.
Corpo della richiesta
L'API CrUX History utilizza intestazioni di richiesta simili a quelle dell'API CrUX giornaliera, con un campo "collectionPeriodCount" facoltativo aggiuntivo:
{
"formFactor": enum (FormFactor),
"metrics": [
string
],
// Union field url_pattern can be only one of the following:
"origin": string,
"url": string,
// End of list of possible types for union field url_pattern.
"collectionPeriodCount": int32 // Optional: Number of periods to collect
}
| Campi | |
|---|---|
formFactor |
Il fattore di forma è una dimensione di query che specifica la classe di dispositivo a cui devono appartenere i dati del record. Questo campo utilizza i valori Nota: se non viene specificato alcun fattore di forma, verrà restituito un record speciale con i dati aggregati per tutti i fattori di forma. |
metrics[] |
Le metriche da includere nella risposta. Se non viene specificata alcuna metrica, verranno restituite tutte le metriche trovate. Valori consentiti: |
Campo unione url_. url_pattern è l'identificatore principale per la ricerca di un record. Può essere solo uno dei seguenti: |
|
origin |
"origin" Esempi: |
url |
Esempi: |
Fine del campo unione url_. |
|
collectionPeriodCount |
Il numero di periodi di raccolta da restituire deve essere compreso tra 1 e 40. Il valore predefinito è 25. Tieni presente che se non viene specificato |
Ad esempio, per richiedere i valori Largest Contentful Paint per computer per la home page di web.dev:
{
"url": "https://web.dev/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
]
}
Questa richiesta simile include il campo facoltativo collectionPeriodCount e genera 40 voci delle serie temporali che forniscono circa 10 mesi di cronologia delle prestazioni web per l'origine https://web.dev:
{
"url": "https://web.dev/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
],
"collectionPeriodCount": 40
}
Corpo della risposta
Le richieste riuscite restituiscono risposte con un oggetto record e urlNormalizationDetails nella seguente struttura:
{
"record": {
"key": {
object (Key)
},
"metrics": [
string: {
object (Metric)
}
]
},
"urlNormalizationDetails": {
object (UrlNormalization)
}
}
Ad esempio, la risposta al corpo della richiesta nella richiesta precedente potrebbe essere:
{
"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 }
}, {
...
}
]
}
}
Chiave
Key definisce tutte le dimensioni che identificano questo record come univoco.
{
"formFactor": enum (FormFactor),
// Union field url_pattern can be only one of the following:
"origin": string,
"url": string
// End of list of possible types for union field url_pattern.
}
| Campi | |
|---|---|
formFactor |
Il fattore di forma è la classe del dispositivo utilizzata da tutti gli utenti per accedere al sito per questo record. Se il fattore di forma non è specificato, verranno restituiti i dati aggregati per tutti i fattori di forma. |
Campo unione url_. Il pattern URL è l'URL a cui si applica il record. url_ può essere solo uno dei seguenti: |
|
origin |
Origine specifica l'origine per la quale è destinato questo record. Nota: quando specifichi un'origine, i dati relativi ai caricamenti sotto questa origine in tutte le pagine vengono aggregati nei dati sull'esperienza utente a livello di origine. |
url |
Nota: quando specifichi un |
Metriche
Un metric è un insieme di dati sull'esperienza utente per una singola metrica sul rendimento del web, ad esempio First Contentful Paint. Contiene un istogramma di riepilogo dell'utilizzo di Chrome in condizioni reali sotto forma di una serie di bins.
{
"histogramTimeseries": [
{
object (Bin)
}
],
"percentilesTimeseries": {
object (Percentiles)
}
}
o
"fractionTimeseries": {
object (Fractions)
}
| Campi | |
|---|---|
histogramTimeseries[] |
L'istogramma delle serie temporali delle esperienze utente per una metrica. L'istogramma delle serie temporali avrà almeno un intervallo e le densità di tutti gli intervalli daranno un totale di circa 1. I valori mancanti per quel determinato periodo di raccolta verranno contrassegnati come |
percentilesTimeseries |
Percentili utili comuni della metrica. Il tipo di valore per i percentile sarà lo stesso dei tipi di valore specificati per gli intervalli dell'istogramma. I valori mancanti per quel determinato periodo di raccolta verranno contrassegnati come |
fractionTimeseries |
Questo oggetto contiene serie temporali di frazioni etichettate, che ammontano a circa 1 per voce. Le frazioni vengono arrotondate a 4 cifre decimali. Le voci mancanti sono espresse come"NaN" in tutte le frazioni. |
Bin
Un bin è una porzione discreta di dati che va dall'inizio alla fine oppure, se non viene specificata una fine, dall'inizio all'infinito positivo.
I valori iniziale e finale di un intervallo sono indicati nel tipo di valore della metrica che rappresenta. Ad esempio, la prima visualizzazione con contenuti viene misurata in millisecondi ed è esposta come interi, pertanto i relativi intervalli di metriche utilizzeranno interi a 32 bit per i tipi di inizio e fine. Tuttavia, lo spostamento cumulativo del layout viene misurato in decimali senza unità ed è visualizzato come decimale codificato come stringa, pertanto i relativi intervalli di metriche utilizzeranno stringhe per il tipo di valore.
{
"start": value,
"end": value,
"densities": [number, number, number...etc.]
}
| Campi | |
|---|---|
start |
Start indica l'inizio del contenitore di dati. |
end |
Fine indica la fine dell'intervallo di dati. Se il campo end non è compilato, il bucket non ha fine ed è valido da start a +inf. |
densities |
Una serie temporale della proporzione di utenti che hanno registrato il valore di questo intervallo per la metrica specificata. Le densità vengono arrotondate a 4 cifre decimali. |
Percentili
Percentiles contiene valori sintetici di una metrica in un determinato percentile statistico. Vengono utilizzati per stimare il valore di una metrica in base all'esperienza di una percentuale di utenti rispetto al numero totale di utenti.
{
"P75": value
}
| Campi | |
|---|---|
p75s |
Serie temporali dei valori per i quali il 75% dei caricamenti di pagine ha registrato la metrica specificata pari o inferiore a questo valore. |
Frazioni
Fractions contiene serie temporali di frazioni etichettate che sommate danno circa 1 per voce.
Ogni etichetta descrive in qualche modo un caricamento di pagina, pertanto le metriche rappresentate in questo modo possono essere considerate come produttrici di valori distinti anziché numerici e le frazioni esprimono la frequenza con cui è stato misurato un determinato valore distinto.
{
"label_1": { "fractions": array[fraction]},
"label_1": { "fractions": array[fraction]},
...
"label_n": { "fractions": array[fraction]}
}
Come i valori di densità nei bucket dell'istogramma, ogni fraction è un numero
0.0 <= value <= 1.0 e la loro somma è pari a circa 1, 0. Quando la metrica non è disponibile per un determinato periodo di raccolta, la voce corrispondente sarà "NaN" in tutti gli array di frazioni.
| Campi | |
|---|---|
p75s |
Serie temporali dei valori per i quali il 75% dei caricamenti di pagine ha registrato la metrica specificata pari o inferiore a questo valore. |
UrlNormalization
Oggetto che rappresenta le azioni di normalizzazione intraprese per normalizzare un URL al fine di ottenere maggiori probabilità di ricerca riuscita. Si tratta di modifiche di base automatiche che vengono apportate quando la ricerca del valore url_pattern fornito non andrebbe a buon fine. Le azioni complesse come i reindirizzamenti non vengono gestite.
{
"originalUrl": string,
"normalizedUrl": string
}
| Campi | |
|---|---|
originalUrl |
L'URL originale richiesto prima di qualsiasi azione di normalizzazione. |
normalizedUrl |
L'URL dopo eventuali azioni di normalizzazione. Si tratta di un URL dell'esperienza utente valido che potrebbe essere ragionevolmente cercato. |
Limiti di frequenza
L'API CrUX History condivide lo stesso limite con l'API CrUX per 150 query al minuto per progetto Google Cloud per entrambe le API, che vengono offerte senza costi. Questo limite e il tuo utilizzo attuale sono visibili nella console Google Cloud. Questa quota generosa dovrebbe essere sufficiente per la maggior parte dei casi d'uso e non è possibile pagare per una quota maggiore.