API CrUX

L'API CrUX permet d'accéder à faible latence à des données agrégées sur l'expérience utilisateur réelle, avec une précision au niveau de la page et de l'origine.

Essayer

Cas d'utilisation courant

L'API CrUX permet d'interroger les métriques d'expérience utilisateur pour un URI spécifique, par exemple "Obtenir les métriques pour l'origine https://example.com".

Clé API CrUX

L'utilisation de l'API CrUX nécessite une clé API Google Cloud provisionnée pour l'utilisation de Chrome UX Report API.

Obtenir et utiliser une clé API

Obtenir une clé

Vous pouvez aussi en créer une sur la page Identifiants.

Une fois la clé API obtenue, votre application peut ajouter le paramètre de requête key=yourAPIKey à toutes les URL de requête.

La clé API peut s'intégrer aux URL en toute sécurité et ne nécessite pas d'encodage.

Consultez les exemples de requêtes.

Modèle de données

Cette section détaille la structure des données dans les requêtes et les réponses.

Enregistrer

Information distincte sur une page ou un site. Un enregistrement peut contenir des données spécifiques à un identifiant et à une combinaison spécifique de dimensions. Un enregistrement peut contenir des données pour une ou plusieurs métriques.

Identifiants

Les identifiants spécifient les enregistrements à rechercher. Dans CrUX, ces identifiants sont des pages Web et des sites Web.

Origine

Lorsque l'identifiant est une origine, toutes les données présentes pour toutes les pages de cette origine sont agrégées. Par exemple, supposons que l'origine http://www.example.com comporte des pages disposées comme suit dans ce sitemap :

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Cela signifie que lorsque vous interrogez le rapport UX Chrome avec l'origine définie sur http://www.example.com, les données pour http://www.example.com/, http://www.example.com/foo.html et http://www.example.com/bar.html sont renvoyées, agrégées, car il s'agit de toutes les pages de cette origine.

URL

Lorsque l'identifiant est une URL, seules les données de cette URL spécifique sont renvoyées. Revenons au sitemap d'origine http://www.example.com :

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Si l'identifiant est défini sur "URL" avec la valeur http://www.example.com/foo.html, seules les données de cette page seront renvoyées.

Dimensions

Les dimensions identifient un groupe de données spécifique par rapport auquel un enregistrement est agrégé. Par exemple, un facteur de forme de PHONE indique que l'enregistrement contient des informations sur les chargements qui ont eu lieu sur un appareil mobile. Chaque dimension aura un certain nombre de valeurs. Si vous ne spécifiez pas une dimension, cela signifie qu'elle est agrégée sur toutes les valeurs. Par exemple, si vous ne spécifiez aucun facteur de forme, cela signifie que l'enregistrement contient des informations sur les chargements qui ont eu lieu sur n'importe quel facteur de forme.

Facteur de forme

Classe de l'appareil utilisé par l'utilisateur final pour accéder à la page. Il s'agit d'une classe générale d'appareils divisée en PHONE, TABLET et DESKTOP.

Métrique

Nous présentons les métriques sous forme d'agrégations statistiques, dans des histogrammes, des centiles et des fractions.

Les valeurs à virgule flottante sont arrondies à quatre décimales (notez que les métriques cumulative_layout_shift sont des doubles encodés sous forme de chaîne. Elles ne sont donc pas considérées comme des nombres à virgule flottante et sont indiquées avec deux décimales dans la chaîne).

Histogramme

Lorsque les métriques sont exprimées dans un histogramme, nous affichons les pourcentages de chargements de page correspondant à des plages particulières pour cette métrique.

Un histogramme à trois bins pour un exemple de métrique se présente comme suit :

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

Ces données indiquent que pour 38, 18% des chargements de page,l'exemple de métrique a été mesuré entre 0 ms et 1 000 ms. Les unités de la métrique ne sont pas incluses dans cet histogramme. Dans ce cas, nous allons supposer qu'il s'agit de millisecondes.

De plus, 49,91% des chargements de page ont enregistré une valeur de métrique comprise entre 1 000 ms et 3 000 ms, et 11,92 % ont enregistré une valeur supérieure à 3 000 ms.

Centiles

Les métriques peuvent également contenir des centiles qui peuvent être utiles pour une analyse supplémentaire. Nous indiquons des valeurs de métriques spécifiques au centile donné pour cette métrique. Ils sont basés sur l'ensemble des données disponibles et non sur les données finales regroupées. Ils ne correspondent donc pas nécessairement à un centile interpolé basé sur l'histogramme final regroupé.

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

Dans cet exemple, au moins 75% des chargements de page ont été mesurés avec une valeur de métrique <= 2063.

Fractions

Les fractions indiquent les pourcentages de chargements de page pouvant être étiquetés d'une manière particulière. Dans ce cas, les valeurs de la métrique sont ces libellés.

Par exemple, la métrique form_factors se compose d'un objet fractions listant la répartition des facteurs de forme (ou appareils) couverts par la requête donnée :

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

Dans ce cas, 3,77% des chargements de page ont été mesurés sur un ordinateur, 2,88% sur une tablette et 93,35% sur un téléphone, soit un total de 100 %.

Types de valeurs de métrique

Nom de la métrique de l'API CrUX Type de données Unités métriques Agrégations statistiques Documentation
cumulative_layout_shift Double encodé sous forme de chaîne avec deux décimales sans unité histogramme avec trois bins, centiles avec p75 CLS
interaction_to_next_paint int millisecondes histogramme avec trois bins, centiles avec p75 INP
largest_contentful_paint int millisecondes histogramme avec trois bins, centiles avec p75 LCP
experimental_cumulative_layout_shift_with_softnavs Double encodé sous forme de chaîne avec deux décimales sans unité Histogramme avec trois bins, centiles avec p75 Blog
experimental_interaction_to_next_paint_with_softnavs int millisecondes Histogramme avec trois bins, centiles avec p75 Blog
experimental_largest_contentful_paint_with_softnavs int millisecondes histogramme avec trois bins, centiles avec p75 Blog
first_contentful_paint int millisecondes Histogramme avec trois bins, centiles avec p75 FCP
experimental_time_to_first_byte int millisecondes histogramme avec trois bins, centiles avec p75 TTFB
form_factors Double à quatre décimales pourcentage Mappage du facteur de forme à la fraction Facteurs de forme
navigation_types Double à quatre décimales pourcentage mappage du type de navigation à la fraction Types de navigation
round_trip_time int millisecondes Histogramme avec trois bins, centiles avec p75 Métrique RTT
largest_contentful_paint_resource_type Double à quatre décimales pourcentage Mappage du type de navigation à la fraction Types de ressources LCP
largest_contentful_paint_image_time_to_first_byte int millisecondes centiles avec p75 Sous-parties LCP
largest_contentful_paint_image_resource_load_delay int millisecondes centiles avec P75 Sous-parties du LCP
largest_contentful_paint_image_resource_load_duration int millisecondes centiles avec P75 Sous-parties LCP
largest_contentful_paint_image_element_render_delay int millisecondes centiles avec P75 Sous-parties du LCP
experimental_ad_count Double à deux décimales sans unité P75 uniquement Nombre d'annonces
experimental_ad_density Double à deux décimales sans unité p75 uniquement Densité des annonces
experimental_ad_cpu int millisecondes p75 uniquement Pondération de l'annonce : CPU
experimental_ad_kilobytes int Ko P75 uniquement Pondération de l'annonce : réseau

Mappage des noms de métriques BigQuery

Nom de la métrique de l'API CrUX Nom de la métrique 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 round_trip_time
largest_contentful_paint_resource_type n/a
largest_contentful_paint_image_time_to_first_byte n/a
largest_contentful_paint_image_resource_load_delay n/a
largest_contentful_paint_image_resource_load_duration n/a
largest_contentful_paint_image_element_render_delay n/a
experimental_ad_count n/a
experimental_ad_density n/a
experimental_ad_cpu n/a
experimental_ad_kilobytes n/a

Période de collecte

Depuis octobre 2022, l'API CrUX contient un objet collectionPeriod avec les champs firstDate et endDate représentant les dates de début et de fin de la période d'agrégation. Exemple :

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

Cela permet de mieux comprendre les données et de savoir si elles ont déjà été mises à jour pour la journée ou si elles renvoient les mêmes données que la veille.

La période de collecte est également disponible dans PageSpeed Insights :

PageSpeed Insights affiche les dates de la période de collecte dans une info-bulle.
Dates de la période de collecte dans PageSpeed Insights.

De plus, la collectionPeriod affichera toujours 28 jours, même si les données ne couvrent pas l'intégralité de cette période (par exemple, si une page a été lancée il y a moins de 28 jours). La collectionPeriod correspond à la période pendant laquelle les données CrUX ont été agrégées, et non à la période que représentent les données.

Exemples de requêtes

Les requêtes sont envoyées sous forme d'objets JSON à l'aide d'une requête POST à https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]", avec les données de requête sous forme d'objet JSON dans le corps de la requête POST :

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Par exemple, vous pouvez l'appeler depuis curl avec la ligne de commande suivante (en remplaçant API_KEY par votre clé) :

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"]}'

Les données au niveau de la page sont disponibles via l'API en transmettant une propriété url dans la requête, au lieu de origin :

{
  "url": "https://example.com/page",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Si la propriété metrics n'est pas définie, toutes les métriques disponibles sont renvoyées :

Si aucune valeur formFactor n'est fournie, les valeurs seront agrégées pour tous les facteurs de forme.

Pour obtenir d'autres exemples de requêtes, consultez Utiliser l'API rapport UX Chrome.

Pipeline de données

L'ensemble de données CrUX est traité via un pipeline pour consolider, agréger et filtrer les données avant qu'elles ne soient disponibles via l'API.

La moyenne glissante

Les données du rapport UX Chrome sont une moyenne glissante sur 28 jours de métriques agrégées. Cela signifie que les données présentées dans le rapport UX Chrome à un moment donné sont en fait des données agrégées des 28 derniers jours.

Cette méthode est semblable à celle utilisée par l'ensemble de données CrUX sur BigQuery pour agréger les rapports mensuels.

Mises à jour quotidiennes

Les données sont mises à jour quotidiennement vers 4h00 UTC. Il n'existe pas de contrat de niveau de service pour les délais de mise à jour. Les mises à jour sont effectuées quotidiennement, dans la mesure du possible.

Schéma

L'API CrUX ne comporte qu'un seul point de terminaison qui accepte les requêtes HTTP POST. L'API renvoie un record contenant un ou plusieurs metrics correspondant aux données sur les performances concernant l'origine ou la page demandée.

Requête HTTP

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

L'URL utilise la syntaxe de transcodage gRPC.

Corps de la requête

Le corps de la requête doit contenir des données présentant la structure suivante :

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

enum (FormFactor)

Le facteur de forme est une dimension de requête qui spécifie la classe d'appareil à laquelle les données de l'enregistrement doivent appartenir.

Ce champ utilise les valeurs DESKTOP, PHONE ou TABLET.

Remarque : Si aucun facteur de forme n'est spécifié, un enregistrement spécial contenant des données globales pour tous les facteurs de forme sera renvoyé.
metrics[]

string

Métriques à inclure dans la réponse. Si aucune n'est spécifiée, toutes les métriques trouvées sont renvoyées.

Valeurs autorisées : ["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", "experimental_ad_count", "experimental_ad_density", "experimental_ad_cpu", "experimental_ad_kilobytes"].
Champ d'union url_pattern. url_pattern est l'identifiant principal d'une recherche d'enregistrement. Il ne peut s'agir que de l'un des éléments suivants :
origin

string

L'"origine" url_pattern fait référence à un format d'URL qui est l'origine d'un site Web.

Exemples : "https://example.com", "https://cloud.google.com"
url

string

url_pattern url fait référence à un format d'URL qui est une URL arbitraire.

Exemples : "https://example.com/, https://cloud.google.com/why-google-cloud/"

Par exemple, pour demander les valeurs Largest Contentful Paint pour ordinateur de la page d'accueil de la documentation pour les développeurs Chrome :

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

Corps de la réponse

Les requêtes réussies renvoient des réponses avec un objet record et urlNormalizationDetails dans la structure suivante :

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

Par exemple, la réponse au corps de la requête précédente pourrait être :

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

Clé

Key définit toutes les dimensions qui identifient cet enregistrement comme unique.

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

enum (FormFactor)

Le facteur de forme correspond à la classe d'appareil utilisée par tous les utilisateurs pour accéder au site pour cet enregistrement.

Si le facteur de forme n'est pas spécifié, des données globales pour tous les facteurs de forme seront renvoyées.
Champ d'union url_pattern. Le format d'URL est l'URL à laquelle l'enregistrement s'applique. url_pattern ne peut être qu'un des éléments suivants :
origin

string

origin spécifie l'origine à laquelle cet enregistrement se rapporte.

Remarque : Lorsque vous spécifiez une origin, les données de chargement de cette origine sur toutes les pages sont agrégées dans les données d'expérience utilisateur au niveau de l'origine.
url

string

url spécifie une URL spécifique à laquelle cet enregistrement est destiné.

Remarque : Lorsque vous spécifiez un url, seules les données de cette URL spécifique sont agrégées.

Métriques

Un metric est un ensemble de données agrégées sur l'expérience utilisateur pour une seule métrique de performances Web, comme le premier contenu affiché. Il peut contenir un histogramme récapitulatif de l'utilisation réelle de Chrome sous la forme d'une série de bins, de données de centile spécifiques (comme le p75) ou de fractions étiquetées.

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

ou

{
  "fractions": {
    object (Fractions)
  }
}
Champs
histogram[]

object (Bin)

Histogramme des expériences utilisateur pour une métrique. L'histogramme comporte au moins un bin, et la somme des densités de tous les bins est d'environ 1.
percentiles

object (Percentiles)

Centiles utiles courants de la métrique. Le type de valeur des centiles sera le même que celui indiqué pour les classes de l'histogramme.
fractions

object (Fractions)

Cet objet contient des fractions libellées, dont la somme est d'environ 1.

Les fractions sont arrondies à quatre décimales.

Bin

Un bin est une partie discrète de données s'étendant du début à la fin, ou de l'infini positif si aucune fin n'est indiquée.

Les valeurs de début et de fin d'un bin sont exprimées dans le type de valeur de la métrique qu'il représente. Par exemple, le premier rendu de contenu est mesuré en millisecondes et exposé sous forme d'entiers. Par conséquent, ses classes de métriques utiliseront des entiers int32 pour ses types de début et de fin. Toutefois, le Cumulative Layout Shift est mesuré en décimales sans unité et est exposé sous la forme d'une décimale encodée en tant que chaîne. Par conséquent, ses segments de métriques utiliseront des chaînes pour son type de valeur.

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

(integer | string)

"Start" correspond au début du bin de données.
end

(integer | string)

"End" correspond à la fin du bin de données. Si le champ "end" n'est pas renseigné, le bin n'a pas de fin et est valide de "start" à +inf.
density

number

Proportion d'utilisateurs ayant rencontré la valeur de ce bin pour la métrique donnée.

Les densités sont arrondies à quatre décimales.

Centiles

Percentiles contient les valeurs synthétiques d'une métrique à un centile statistique donné. Ils permettent d'estimer la valeur d'une métrique telle qu'elle est perçue par un pourcentage d'utilisateurs par rapport au nombre total d'utilisateurs.

{
  "P75": value
}
Champs
p75

(integer | string)

75% des chargements de page ont enregistré la métrique donnée à cette valeur ou moins.

Fractions

Fractions contient des fractions étiquetées dont la somme est d'environ 1. Chaque étiquette décrit un chargement de page d'une manière ou d'une autre. Les métriques représentées de cette manière peuvent donc être considérées comme produisant des valeurs distinctes plutôt que des valeurs numériques, et les fractions expriment la fréquence à laquelle une valeur distincte particulière a été mesurée.

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

Tout comme les valeurs de densité dans les classes d'histogramme, chaque fraction est un nombre 0.0 <= value <= 1.0, et leur somme est d'environ 1,0.

UrlNormalization

Objet représentant les actions de normalisation effectuées pour normaliser une URL afin d'augmenter les chances de réussite de la recherche. Il s'agit de modifications de base automatisées qui sont effectuées lorsqu'il est certain que la recherche de l'url_pattern fourni échouera. Les actions complexes telles que le suivi des redirections ne sont pas gérées.

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

string

URL demandée d'origine avant toute action de normalisation.
normalizedUrl

string

URL après toute action de normalisation. Il s'agit d'une URL d'expérience utilisateur valide qui peut raisonnablement être recherchée.

Limites de débit

L'API CrUX est limitée à 150 requêtes par minute et par projet Google Cloud, et est proposée sans frais. Vous pouvez consulter cette limite et votre utilisation actuelle dans la console Google Cloud. Ce quota généreux devrait suffire pour la grande majorité des cas d'utilisation. Il n'est pas possible de payer pour augmenter le quota.