L'API CrUX History consente l'accesso a bassa latenza a sei mesi di dati storici sull'esperienza utente reale nella granularità della pagina e dell'origine.
Caso d'uso comune
L'API CrUX History consente di eseguire query sulle metriche storiche dell'esperienza utente per un URI specifico, come "Recupera le tendenze storiche dell'esperienza utente per l'origine https://example.com".
L'API History segue la stessa struttura dell'API CrUX giornaliera, ad eccezione del 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 l'API giornaliera, l'utilizzo dell'API CrUX History richiede una chiave API Google Cloud. La stessa chiave può essere utilizzata per l'API Daily e History.
Puoi crearne una nella pagina Credenziali ed eseguirne il provisioning per l'utilizzo di Chrome UX Report API.
Se disponi di una chiave API, l'applicazione può aggiungere il parametro di query key=[YOUR_API_KEY] a tutti gli URL della richiesta. Consulta Esempi di query.
La chiave API è sicura per l'incorporamento negli URL; non è necessaria alcuna codifica.
Modello dei dati
Questa sezione descrive in dettaglio la struttura dei dati nelle richieste e nelle risposte.
Record
Un'informazione discreta su una pagina o un sito. Un record può contenere dati specifici di un identificatore e di una specifica combinazione di dimensioni. Un record può contenere dati per una o più metriche.
Identificatori
Gli identificatori specificano i record da cercare. In CrUX questi identificatori sono pagine web e siti web.
Origine
Quando l'identificatore è un'origine, tutti i dati presenti per tutte le pagine in quell'origine vengono aggregati insieme. Ad esempio, supponiamo che l'origine http://www.example.com abbia delle 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 viene eseguita una query nel Report sull'esperienza utente di Chrome con l'origine impostata su http://www.example.com, vengono restituiti i dati relativi a http://www.example.com/, http://www.example.com/foo.html e http://www.example.com/bar.html, in quanto si tratta di tutte pagine appartenenti a quell'origine.
URL
Quando l'identificatore è un URL, vengono restituiti solo i dati relativi a quell'URL specifico. Rivediamo la Sitemap di origine di 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 per 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 PHONE indica che il record contiene informazioni sui caricamenti avvenuti su un dispositivo mobile.
L'API CrUX History è disponibile solo aggregata per dimensione del fattore di forma. Questa è una classe generica di dispositivi suddivisa in PHONE, TABLET e DESKTOP.
Metrica
Le metriche vengono registrate in serie temporali di aggregazioni statistiche, ovvero istogrammi, percentili e frazioni.
Istogrammi
Quando le metriche sono espresse in un array di istogrammi, ogni voce di serie temporale rappresenta la percentuale di caricamenti pagina durante il quale la metrica è rientrata in un intervallo, in modo proporzionale a tutti. I punti dati vengono presentati nell'ordine delle date del periodo di raccolta restituite anche dall'API. Il primo punto corrisponde al periodo di raccolta più recente e il punto finale al periodo di raccolta più recente.
Un semplice istogramma a tre bin 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 riscontrato il valore della metrica di esempio tra 0 ms e 2.500 ms per il primo periodo di raccolta nella cronologia, seguito da 92,03%, 91,94%... Le unità della metrica non sono contenute in questo istogramma, in questo caso supporremo i millisecondi.
Inoltre, il 5,21% dei caricamenti di pagine ha riscontrato 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 pagine ha riscontrato un valore superiore a 4000 ms nel primo periodo di raccolta della cronologia.
Percentili
Le metriche possono anche contenere serie temporali di percentili che possono essere utili per ulteriori analisi.
I punti dati vengono presentati nell'ordine delle date del periodo di raccolta restituite anche dall'API. Il primo punto corrisponde al periodo di raccolta più recente e il punto finale al periodo di raccolta più recente.
{
"percentilesTimeseries": {
"p75s": [1362, 1352, 1344, 1356, 1366, 1377]
},
}
Questi percentili possono mostrare valori specifici della metrica nel percentile specificato. Si basano sull'intero set di dati disponibili e non sui dati raggruppati finali, quindi non corrispondono necessariamente a un percentile interpolato basato sull'istogramma raggruppato finale.
Frazioni
Le metriche possono essere espresse come serie temporali di frazioni etichettate; ogni etichetta descrive un caricamento pagina in un determinato modo. I punti dati vengono presentati nell'ordine delle date del periodo di raccolta restituite anche dall'API. Il primo punto corrisponde al periodo di raccolta più recente e il punto finale 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 proveniva da computer e l'82,88% da telefoni.
Tipi di valori delle metriche
Poiché l'API CrUX History utilizza gli stessi tipi di valori delle metriche, puoi consultare la documentazione giornaliera sui tipi di valori delle metriche dell'API CrUX per ulteriori dettagli.
Idoneità delle metriche
In base ai criteri di idoneità, un'origine o un URL potrebbe essere idoneo soltanto per alcuni periodi di raccolta previsti 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 in cui non sono disponibili dati idonei. Il motivo della differenza è che le densità degli istogrammi sono sempre numeri, mentre i percentili possono essere numeri o stringhe (CLS utilizza stringhe, anche se somigliano a numeri).
Ad esempio, se il secondo periodo non conteneva dati idonei, verrà visualizzato il seguente risultato:
{
"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 rientrano o meno nell'idoneità 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 dati fino al sabato precedente (in base al ritardo standard di 2 giorni). Contiene i dati delle 25 settimane precedenti, un periodo di raccolta a settimana.
Poiché ogni periodo di raccolta contiene i dati aggregati degli ultimi 28 giorni e i periodi di raccolta sono su base settimanale, i periodi di raccolta 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 delle query come oggetto JSON nel corpo POST.
Tieni presente che l'utilizzo di queryHistoryRecord sostituisce la 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, puoi chiamare 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_paintfirst_input_delayinteraction_to_next_paintlargest_contentful_paintexperimental_time_to_first_bytenavigation_typesround_trip_timeform_factors(segnalato solo se nella richiesta non è specificato nessunformFactor)
Se non viene fornito alcun valore di formFactor, i valori verranno aggregati per tutti i fattori di forma.
Per altri esempi di query, consulta la guida Utilizzo dell'API CrUX History.
Pipeline di dati
Il set di dati CrUX viene elaborato attraverso una pipeline per consolidare, aggregare e filtrare i dati prima di diventare disponibile tramite l'API.
La media mobile
I dati del report sull'esperienza utente di Chrome sono una media mobile di 28 giorni di metriche aggregate. Ciò significa che i dati presentati in un determinato momento nel Report sull'esperienza utente di Chrome sono effettivamente dati degli ultimi 28 giorni aggregati.
L'API History contiene un certo numero di periodi di raccolta dei dati, ciascuno che comprende questi 28 giorni. Poiché ogni periodo di raccolta contiene i dati aggregati degli ultimi 28 giorni e i periodi di raccolta sono su base settimanale, i periodi di raccolta 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 dati fino al sabato precedente (in base al ritardo standard di 2 giorni). Contiene i dati delle ultime 25 settimane (circa 6 mesi), un periodo di raccolta a settimana.
Non esiste un accordo sul livello del servizio per i tempi di aggiornamento, che viene eseguito ogni giorno secondo il criterio del "best effort".
Schema
Esiste un unico endpoint per l'API CrUX History che accetta richieste HTTP POST. L'API restituisce un record che contiene uno o più metrics corrispondenti ai dati sulle prestazioni 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 gli stessi corpi di richiesta dell'API CrUX giornaliera, ad eccezione del supporto del campo di richiesta effectiveConnectionType.
Ad esempio, per richiedere i valori desktop Largest Contentful Paint per la home page web.dev:
{
"origin": "https://web.dev/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
]
}
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 unico.
{
"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 in questo record. Se il fattore di forma non è specificato, verranno restituiti i dati aggregati di 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 |
"Origin" (Origine) specifica l'origine a cui è destinato il record. Nota: quando specifichi un'origine, i dati per i caricamenti in questa origine su tutte le pagine vengono aggregati in dati sull'esperienza utente a livello di origine. |
url |
Nota: quando specifichi un valore |
Metriche
Un metric è un insieme di dati sull'esperienza utente per una singola metrica del rendimento sul web, ad esempio First Contentful Paint. Contiene un istogramma di riepilogo dell'utilizzo reale di Chrome in una serie di bins.
{
"histogramTimeseries": [
{
object (Bin)
}
],
"percentilesTimeseries": {
object (Percentiles)
}
}
o
"fractionTimeseries": {
object (Fractions)
}
| Campi | |
|---|---|
histogramTimeseries[] |
L'istogramma della serie temporale delle esperienze utente per una metrica. L'istogramma della serie temporale avrà almeno una fascia e la densità di tutte le fasce sarà ~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 percentili sarà lo stesso dei tipi di valori specificati per le fasce degli istogrammi. I valori mancanti per quel determinato periodo di raccolta verranno contrassegnati come |
fractionTimeseries |
Questo oggetto contiene serie temporali di frazioni etichettate, che sommano circa 1 per voce. Le frazioni vengono arrotondate a quattro cifre decimali. Le voci mancanti sono espresse come"NaN" in tutte le frazioni. |
Bin
Un bin è una porzione discreta di dati che si estende dall'inizio alla fine o se non è specificata una fine dall'inizio all'infinito positivo.
I valori di inizio e fine di una fascia sono indicati nel tipo di valore della metrica che rappresenta. Ad esempio, la First Contentful Paint viene misurata in millisecondi ed esposta come int. Di conseguenza, i bin delle metriche utilizzeranno int32s per i tipi di inizio e fine. Tuttavia, la variazione del layout cumulativa viene misurata in decimali senza unità ed è esposta come un numero decimale codificato come stringa, pertanto i bin delle metriche utilizzeranno le stringhe per il tipo di valore.
{
"start": value,
"end": value,
"densities": [number, number, number...etc.]
}
| Campi | |
|---|---|
start |
"Inizio" indica l'inizio del contenitore dati. |
end |
"Fine" indica la fine del contenitore dati. Se il campo end non è compilato, il contenitore non ha una fine ed è valido dall'inizio a +inf. |
densities |
Una serie temporale della proporzione di utenti che hanno riscontrato il valore di questa fascia per la metrica specificata. Le densità vengono arrotondate a quattro 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 a una percentuale di utenti rispetto al numero totale di utenti.
{
"P75": value
}
| Campi | |
|---|---|
p75s |
La serie temporale dei valori per cui il 75% dei caricamenti pagina ha riscontrato una metrica uguale o inferiore a questo valore. |
Frazioni
Fractions contiene serie temporali di frazioni etichettate che sommano fino a ~1, per voce.
Ogni etichetta descrive in qualche modo un caricamento pagina, quindi le metriche rappresentate in questo modo
possono essere considerate come la produzione di valori distinti invece di valori numerici e
le frazioni esprimono la frequenza con cui è stato misurato un particolare valore distinto.
{
"label_1": { "fractions": array[fraction]},
"label_1": { "fractions": array[fraction]},
...
"label_n": { "fractions": array[fraction]}
}
Proprio come i valori di densità nelle fascette di istogrammi, ogni fraction è un numero
0.0 <= value <= 1.0 e la somma è ~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 |
La serie temporale dei valori per cui il 75% dei caricamenti pagina ha riportato la metrica specificata in modo uguale o inferiore a questo valore. |
UrlNormalization
Oggetto che rappresenta le azioni di normalizzazione intraprese per normalizzare un URL e aumentare le probabilità di riuscita della ricerca. Si tratta di semplici modifiche automatiche che vengono apportate quando si cerca l'elemento url_pattern fornito potrebbe non riuscire. Le azioni complesse come i seguenti reindirizzamenti non vengono gestite.
{
"originalUrl": string,
"normalizedUrl": string
}
| Campi | |
|---|---|
originalUrl |
L'URL richiesto originale prima di qualsiasi azione di normalizzazione. |
normalizedUrl |
L'URL dopo qualsiasi azione di normalizzazione. Questo è un URL valido per l'esperienza utente 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, offerte senza costi aggiuntivi. Questo limite e l'utilizzo attuale possono essere visualizzati nella console Google Cloud. Questa quota generosa dovrebbe essere sufficiente per la maggior parte dei casi d'uso e non è possibile pagare per un aumento della quota.