API CrUX

L'API CrUX offre accesso a bassa latenza ai dati aggregati sull'esperienza utente reale con granularità a livello di pagina e di origine.

Prova!

Caso d'uso comune

L'API CrUX consente di eseguire query sulle metriche relative all'esperienza utente per un URI specifico, ad esempio "Ottieni le metriche per l'origine https://example.com".

Chiave API CrUX

L'utilizzo dell'API CrUX richiede una chiave API Google Cloud di cui è stato eseguito il provisioning per l'utilizzo di Chrome UX Report API.

Acquisizione e utilizzo di una chiave API

Ottieni una chiave

In 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. Ogni dimensione avrà un determinato numero di valori e, implicitamente, la mancata specifica della dimensione comporterà l'aggregazione della dimensione su tutti i valori. Ad esempio, se non specifichi alcun fattore di forma, il record contiene informazioni sui caricamenti che si sono verificati su qualsiasi fattore di forma.

Fattore di forma

La classe del dispositivo utilizzata dall'utente finale per accedere alla pagina. Si tratta di una classe generale di dispositivi suddivisa in PHONE, TABLET e DESKTOP.

Metrica

Le metriche vengono registrate come aggregazioni statistiche, in istogrammi, percentile e frazioni.

I valori in virgola mobile vengono arrotondati a 4 cifre decimali (tieni presente che le metriche cumulative_layout_shift sono doppie codificate come stringa, quindi non sono considerate valori in virgola mobile e vengono riportate a 2 cifre decimali all'interno della stringa).

Istogramma

Quando le metriche sono espresse in un istogramma, mostriamo le percentuali di caricamenti di pagine che rientrano in determinati intervalli per la metrica in questione.

Un istogramma con tre intervalli per una metrica di esempio ha il seguente aspetto:

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

Questi dati indicano che per il 38, 18% dei caricamenti di pagina,la metrica di esempio è stata misurata tra 0 ms e 1000 ms. Le unità della metrica non sono contenute in questo istogramma, in questo caso assumeremo millisecondi.

Inoltre, il 49,91% dei caricamenti di pagine ha registrato un valore della metrica compreso tra 1000 ms e 3000 ms e l'11,92% ha registrato un valore superiore a 3000 ms.

Percentili

Le metriche possono contenere anche percentile che possono essere utili per analisi aggiuntive. Vengono registrati valori specifici della metrica nel percentile specificato per la metrica. Si basano sull'intero insieme di dati disponibili e non sui dati finali raggruppati, pertanto non corrispondono necessariamente a un percentile interpolato basato sull'istogramma finale raggruppato.

{
  "percentiles": {
    "p75": 2063
  }
}

In questo esempio, almeno il 75% dei caricamenti di pagine è stato misurato con un valore della metrica <= 2063.

Nota: i valori per ogni percentile sono ricavati in modo sintetico e non implicano che un utente abbia effettivamente riscontrato il valore indicato, ma solo che una certa percentuale di caricamenti di pagine abbia registrato un valore della metrica inferiore a quello indicato.

Frazioni

Le frazioni indicano le percentuali di caricamenti di pagine che possono essere etichettate in un determinato modo. In questo caso, i valori delle metriche sono queste etichette.

Ad esempio, la metrica form_factors è costituita da un oggetto fractions che elenca la suddivisione dei fattori di forma (o dei dispositivi) coperti dalla query specificata:

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

In questo caso, il 3,77% dei caricamenti di pagine è stato misurato su un computer, il 2,88% su un tablet e il 93,35% su uno smartphone, per un totale del 100%.

Tipi di valori delle metriche

Nome metrica dell'API CrUX	Tipo di dati	Unità di misura metriche	Aggregazioni statistiche	Documentazione
cumulative_layout_shift	2 cifre decimali con doppia codifica come stringa	senza unità	istogramma con tre intervalli, percentile con p75	cls
first_contentful_paint	int	millisecondi	istogramma con tre intervalli, percentile con p75	fcp
interaction_to_next_paint	int	millisecondi	istogramma con tre intervalli, percentile con p75	inp
largest_contentful_paint	int	millisecondi	istogramma con tre intervalli, percentile con p75	lcp
experimental_time_to_first_byte	int	millisecondi	istogramma con tre intervalli, percentile con p75	ttfb
form_factors	Doppio con 4 cifre decimali	percentuale	mappatura dal fattore di forma alla frazione	Fattori di forma
navigation_types	Doppio con 4 cifre decimali	percentuale	mappatura dal tipo di navigazione alla frazione	tipi di navigazione
round_trip_time	int	millisecondi	percentile con p75	rtt

Mappatura dei nomi delle metriche BigQuery

Nome metrica dell'API CrUX	Nome metrica BigQuery
cumulative_layout_shift	layout_instability.cumulative_layout_shift
first_contentful_paint	first_contentful_paint
interaction_to_next_paint	interaction_to_next_paint
largest_contentful_paint	largest_contentful_paint
experimental_time_to_first_byte	experimental.time_to_first_byte
navigation_types	navigation_types
form_factors	n/a
round_trip_time	n/a

Nota: in BigQuery CrUX, le densità dell'istogramma si sommano al 100% per origine nei vari fattori di forma, pertanto la metrica form_factors supportata nell'API è invece espressa come le densità dell'istogramma per first_contentful_paint.

Periodo di raccolta

A partire da ottobre 2022, l'API CrUX contiene un oggetto collectionPeriod con i campi firstDate e endDate che rappresentano le date di inizio e di fine della finestra di aggregazione. Ad esempio:

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

In questo modo è possibile comprendere meglio i dati e sapere se sono stati ancora aggiornati per quel giorno o se restituiscono gli stessi dati di ieri.

Tieni presente che l'API CrUX è indietro di circa due giorni rispetto alla data odierna perché attende i dati completi della giornata e sono necessari alcuni tempi di elaborazione prima che i dati siano disponibili nell'API. Il fuso orario utilizzato è il fuso orario del Pacifico (PST) senza modifiche per l'ora legale.

Inoltre, collectionPeriod mostrerà sempre 28 giorni, anche se i dati non riguardano l'intero periodo di 28 giorni (ad esempio se una pagina è stata lanciata meno di 28 giorni fa). collectionPeriod indica il periodo di tempo in cui sono stati aggregati i dati di CrUX, non necessariamente il periodo di tempo rappresentato dai dati.

Esempi di query

Le query vengono inviate come oggetti JSON utilizzando una richiesta POST a https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" con i dati di query come oggetto JSON nel corpo del POST:

{
  "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:queryRecord?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"]}'

Nota: l'esempio precedente è per sistemi basati su macOS o Linux, inclusa la shell Git BASH per Windows. Altri sistemi potrebbero richiedere lievi modifiche. Ad esempio, la riga di comando cmd.exe non consente virgolette singole per i parametri né le continue di riga (\), pertanto richiede l'utilizzo di virgolette doppie (escaping delle virgolette interne come appropriato con \") e anche di una singola riga.

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_shift
• first_contentful_paint
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• navigation_types
• form_factors (viene segnalato solo se nella richiesta non è specificato alcun formFactor)

Se non viene fornito alcun valore formFactor, i valori verranno aggregati in tutti i fattori di forma.

Per altri esempi di query, consulta Utilizzare l'API Report sull'esperienza utente di Chrome.

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.

Questo è simile al modo in cui il set di dati CrUX su BigQuery aggrega i report mensili.

Aggiornamenti giornalieri

I dati vengono aggiornati ogni giorno intorno alle 04:00 UTC. Non esiste un accordo sul livello del servizio per i tempi di aggiornamento; viene eseguito ogni giorno secondo il criterio del massimo impegno.

Attenzione: i dati non differiranno nello stesso giorno dopo l'aggiornamento intorno alle 04:00 UTC, le chiamate ripetute produrranno gli stessi risultati.

Schema

Esiste un unico endpoint per l'API CrUX che accetta richieste HTTP POST. L'API restituisce un record contenente uno o più metrics corrispondenti ai dati sulle prestazioni dell'origine o della pagina richiesta.

Richiesta HTTP

POST https://chromeuxreport.googleapis.com/v1/records:queryRecord

L'URL utilizza la sintassi di transcodifica gRPC.

Corpo della richiesta

Il corpo della richiesta deve contenere dati con la seguente struttura:

{
  "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.
}

Campi
formFactor	enum (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 DESKTOP, PHONE o TABLET. 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[]	string Le metriche da includere nella risposta. Se non viene specificata alcuna metrica, verranno restituite tutte le metriche trovate. Valori consentiti: ["cumulative_layout_shift", "first_contentful_paint", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
Campo unione url_pattern. url_pattern è l'identificatore principale per la ricerca di un record. Può essere solo uno dei seguenti:
origin	string "origin" url_pattern si riferisce a un pattern URL che è l'origine di un sito web. Esempi: "https://example.com", "https://cloud.google.com"
url	string url_pattern url fa riferimento a un pattern URL che può essere un URL arbitrario. Esempi: "https://example.com/, https://cloud.google.com/why-google-cloud/"

Ad esempio, per richiedere i valori Largest Contentful Paint per computer per la home page della documentazione per sviluppatori di Chrome:

{
  "url": "https://developer.chrome.com/docs/",
  "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": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.9815
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.0108
          },
          {
            "start": 4000,
            "density": 0.0077
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

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	enum (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_pattern. Il pattern URL è l'URL a cui si applica il record. url_pattern può essere solo uno dei seguenti:
origin	string origin specifica l'origine per la quale è destinato questo record. Nota: quando specifichi un origin, i dati relativi ai caricamenti sotto questa origine in tutte le pagine vengono aggregati nei dati sull'esperienza utente a livello di origine.
url	string url specifica un URL specifico a cui si riferisce questo record. Nota: quando specifichi un url, verranno aggregati solo i dati relativi a quell'URL specifico.

Metriche

Un metric è un insieme di dati aggregati sull'esperienza utente per una singola metrica sulle prestazioni web, come First Contentful Paint. Può contenere un istogramma di riepilogo dell'utilizzo di Chrome reale sotto forma di una serie di bins, dati percentile specifici (ad esempio p75) oppure può contenere frazioni etichettate.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

o

{
  "fractions": {
    object (Fractions)
  }
}

Campi
histogram[]	object (Bin) L'istogramma delle esperienze utente per una metrica. L'istogramma avrà almeno un intervallo e le densità di tutti gli intervalli daranno un totale di circa 1.
percentiles	object (Percentiles) 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.
fractions	object (Fractions) Questo oggetto contiene frazioni etichettate, che sommate danno un valore approssimativo di 1. Le frazioni vengono arrotondate a 4 cifre decimali.

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 le stringhe per il tipo di valore.

{
  "start": value,
  "end": value,
  "density": number
}

Campi
start	(integer | string) Start indica l'inizio del contenitore di dati.
end	(integer | string) 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.
density	number La 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
p75	(integer | string) Il 75% dei caricamenti di pagine ha registrato la metrica specificata pari o inferiore a questo valore.

Frazioni

Fractions contiene frazioni etichettate che sommate danno circa 1. 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": fraction,
  "label_2": fraction,
  ...
  "label_n": 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.

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 semplici modifiche 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	string L'URL originale richiesto prima di qualsiasi azione di normalizzazione.
normalizedUrl	string 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 è limitata a 150 query al minuto per progetto Google Cloud, che viene offerta 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.