API CrUX

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

Fai una prova!

Caso d'uso comune

L'API CrUX consente di eseguire query sulle metriche relative all'esperienza utente per un URI specifico, ad esempio "Recupera 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

In alternativa, creane una nella pagina Credenziali.

Dopo aver ottenuto una chiave API, la tua applicazione può aggiungere il parametro di query key=yourAPIKey a tutti gli URL delle richieste.

La chiave API è sicura per l'incorporamento negli URL e non richiede alcuna codifica.

Consulta Query di esempio.

Modello dei dati

Questa sezione descrive in dettaglio la struttura dei dati nelle richieste e nelle risposte.

Registra

Un'informazione discreta 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 dati per 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 di quell'origine vengono aggregati. Ad esempio, supponiamo che l'origine http://www.example.com abbia pagine disposte come in 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 Chrome UX Report 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, aggregati insieme, perché sono tutte pagine di quell'origine.

URL

Se l'identificatore è un URL, verranno restituiti solo i dati relativi a quell'URL specifico. Torniamo alla 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 per quella pagina.

Dimensioni

Le dimensioni identificano un gruppo specifico di dati in base ai quali viene aggregato un record. Ad esempio, un fattore di forma PHONE indica che il record contiene informazioni sui caricamenti avvenuti su un dispositivo mobile. Ogni dimensione avrà un determinato numero di valori e, implicitamente, la mancata specifica di quella dimensione significherà che la dimensione viene aggregata su tutti i valori. Ad esempio, se non viene specificato alcun fattore di forma, il record contiene informazioni sui caricamenti avvenuti su qualsiasi fattore di forma.

Fattore di forma

La classe di 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 riportate come aggregazioni statistiche, in istogrammi, percentili e frazioni.

I valori in virgola mobile vengono arrotondati a 4 cifre decimali (tieni presente che le metriche cumulative_layout_shift sono valori double codificati come stringa, quindi non sono considerati valori in virgola mobile e vengono riportati con 2 cifre decimali all'interno della stringa).

Istogramma

Quando le metriche sono espresse in un istogramma, mostriamo le percentuali di caricamenti di pagina che rientrano in intervalli particolari per quella metrica.

Un istogramma a tre bin 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 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 pagina 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 percentili che possono essere utili per ulteriori analisi. Riportiamo valori di metriche specifici al percentile indicato per quella metrica. Si basano sull'intero insieme di dati disponibili e non sui dati bin finali, pertanto non corrispondono necessariamente a un percentile interpolato basato sull'istogramma bin finale.

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

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

Frazioni

Le frazioni indicano le percentuali di caricamenti pagina che possono essere etichettati 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 form factor (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 pagina è 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

Mappatura dei nomi delle metriche BigQuery

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 verificare se sono stati aggiornati per quel giorno o se restituiscono gli stessi dati del giorno precedente.

Il periodo di raccolta è disponibile anche in PageSpeed Insights:

Inoltre, collectionPeriod mostrerà sempre 28 giorni, anche se i dati non coprono l'intero periodo di 28 giorni (ad esempio, se una pagina è stata lanciata meno di 28 giorni fa). collectionPeriod è il periodo di tempo in cui sono stati aggregati i dati 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 della query come oggetto JSON nel corpo della richiesta 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"]}'

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
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• form_factors (viene segnalato solo se nella richiesta non è specificato formFactor)
• experimental_ad_count (solo per le pagine incluse nelle metriche pubblicitarie)
• experimental_ad_density (riportato solo per le pagine incluse nelle metriche degli annunci)
• experimental_ad_cpu (riportato solo per le pagine incluse nelle metriche degli annunci)
• experimental_ad_kilobytes (solo per le pagine incluse nelle metriche pubblicitarie)

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

Per altri esempi di query, consulta Utilizzo dell'API Chrome UX Report.

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.

Media mobile

I dati del Chrome UX Report sono una media mobile di 28 giorni delle metriche aggregate. Ciò significa che i dati presentati nel Chrome UX Report 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 è previsto un accordo sul livello del servizio per i tempi di aggiornamento, che viene eseguito ogni giorno in base al massimo impegno.

Schema

Esiste un singolo endpoint per l'API CrUX che accetta richieste HTTP POST. L'API restituisce un record che contiene uno o più metrics corrispondenti ai dati sul rendimento relativi all'origine o alla 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.
}

Ad esempio, per richiedere i valori di Largest Contentful Paint per computer della home page della documentazione per lo sviluppo 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.
}

Metriche

Un metric è un insieme di dati aggregati sull'esperienza utente per una singola metrica sul rendimento web, ad esempio First Contentful Paint. Può contenere un istogramma riassuntivo dell'utilizzo di Chrome nel mondo reale come serie di bins, dati percentili specifici (come il p75) oppure frazioni etichettate.

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

o

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

Bin

Un bin è una porzione discreta di dati che va dall'inizio alla fine o, se non è indicata una fine, dall'inizio all'infinito positivo.

I valori iniziale e finale di un bin sono indicati nel tipo di valore della metrica che rappresenta. Ad esempio, First Contentful Paint viene misurato in millisecondi ed esposto come int, pertanto i relativi bin di metrica utilizzeranno int32 per i tipi di inizio e fine. Tuttavia, la variazione del layout cumulativa viene misurata in decimali senza unità ed è esposta come decimale codificato come stringa, pertanto i bin delle metriche utilizzeranno le stringhe per il tipo di valore.

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

Percentili

Percentiles contiene valori sintetici di una metrica a 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
}

Frazioni

Fractions contiene frazioni etichettate che sommate danno ~1. Ogni etichetta descrive un caricamento pagina in qualche modo, quindi 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 particolare valore distinto.

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

Analogamente ai valori di densità nei bin 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 aumentare le probabilità di una ricerca riuscita. Si tratta di modifiche di base e automatiche che vengono apportate quando si sa che la ricerca del url_pattern fornito non andrà a buon fine. Le azioni complesse, come il reindirizzamento, non vengono gestite.

{
  "originalUrl": string,
  "normalizedUrl": string
}

Limiti di frequenza

L'API CrUX è limitata a 150 query al minuto per progetto Google Cloud, offerto senza costi. Questo limite e l'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.