API CrUX

L'API CrUX offre un accès à faible latence aux données agrégées sur l'expérience utilisateur réelle, au niveau de la page et de l'origine.

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 des métriques pour l'origine https://example.com".

Clé API CrUX

L'utilisation de l'API CrUX nécessite une clé API Google Cloud. Vous pouvez en créer un sur la page Identifiants et le provisionner pour l'utiliser avec Chrome UX Report API.

Une fois que vous disposez d'une clé API, votre application peut ajouter le paramètre de requête key=[YOUR_API_KEY] à toutes les URL de requête. Consultez la section Exemples de requêtes.

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

Modèle de données

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

Enregistrer

Information discrète concernant 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 au niveau de cette origine sont regroupées. Par exemple, supposons que l'origine http://www.example.com comportait des pages telles que décrites par ce sitemap:

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

Ainsi, 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, regroupées, car il s'agit de toutes les pages associées à cette origine.

URL

Lorsque l'identifiant est une URL, seules les données de cette URL spécifique sont renvoyées. Revenons sur le 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 sont renvoyées.

Dimensions

Les dimensions identifient un groupe spécifique de données 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 effectués sur un appareil mobile. Chaque dimension aura un certain nombre de valeurs. Par conséquent, si vous ne le spécifiez pas, elle sera cumulée avec 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 effectués sur l'un ou l'autre facteur.

Facteur de forme

Classe d'appareil utilisée 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.

Type de connexion effectif

Le type de connexion effectif correspond à la qualité de connexion estimée de l'appareil lorsque vous accédez à cette page. Il s'agit d'une classe générale divisée en trois : offline, slow-2G, 2G, 3G et 4G.

Métrique

Nous générons des rapports sur les métriques sous la forme d'agrégations statistiques, sous la forme d'histogrammes, de centiles et de fractions.

Les valeurs à virgule flottante sont arrondies à quatre décimales (notez que les métriques cumulative_layout_shift sont encodées deux fois sous forme de chaîne). Elles ne sont donc pas considérées comme des valeurs à virgule flottante et sont signalées à 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 dans des plages particulières pour cette métrique.

Un simple 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 contenues dans cet histogramme. Dans ce cas, nous prenons en compte les millisecondes.

De plus, 49,91% des chargements de page ont vu une valeur de métrique comprise entre 1 000 ms et 3 000 ms, et 11,92 % ont vu 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 présentons des valeurs de métriques spécifiques au centile donné pour cette métrique. Ils sont basés sur l'ensemble complet des données disponibles et non sur les données binaires finales. Par conséquent, ils ne correspondent pas nécessairement à un centile interpolé basé sur l'histogramme à binning final.

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

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

Remarque:Les valeurs de chaque centile sont dérivées de façon synthétique. Cela ne signifie pas qu'un utilisateur a réellement vu la valeur indiquée, mais seulement qu'un certain pourcentage de chargements de page a enregistré une valeur de métrique inférieure à la valeur indiquée.

Fractions

Les fractions indiquent le pourcentage de chargements de page pouvant être étiquetés d'une manière particulière. Dans le cas présent, les valeurs de la métrique sont ces étiquettes.

Par exemple, la métrique form_factors consiste en 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 pages ont été mesurés sur un ordinateur, 2,88% sur une tablette et 93,35% sur un téléphone, soit 100% au total.

Types de valeurs de métriques

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 encodage en tant que chaîne avec deux décimales	sans unité	Histogramme à trois classes, centiles avec p75	cls
first_contentful_paint	int	millisecondes	Histogramme à trois classes, centiles avec p75	FPS
first_input_delay (obsolète)	int	millisecondes	Histogramme à trois classes, centiles avec p75	FID
interaction_to_next_paint	int	millisecondes	Histogramme à trois classes, centiles avec p75	inp
largest_contentful_paint	int	millisecondes	Histogramme à trois classes, centiles avec p75	LPC
experimental_time_to_first_byte	int	millisecondes	Histogramme à trois classes, centiles avec p75	À confirmer
form_factors	Double à 4 chiffres après la virgule	pourcentage	mappage du facteur de forme à la fraction	facteurs de forme
navigation_types	Double à 4 chiffres après la virgule	pourcentage	mappage du type de navigation à la fraction	types de navigation

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
first_input_delay	first_input.delay
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

Remarque:Dans BigQuery CrUX, la somme des densités d'histogramme peut atteindre 100% par origine pour tous les facteurs de forme. Par conséquent, la métrique form_factors compatible avec l'API est exprimée sous la forme de densités d'histogramme pour first_contentful_paint.

Période de collecte

Depuis octobre 2022, l'API CrUX contient un objet collectionPeriod avec des 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 été mises à jour pour le jour en question ou si elles renvoient les mêmes données qu'hier.

Notez que l'API CrUX a environ deux jours de retard par rapport à la date d'aujourd'hui, car elle attend que les données soient complètes pour la journée. Par conséquent, un certain temps de traitement est nécessaire avant qu'elles ne soient disponibles dans l'API. Le fuseau horaire utilisé est l'heure normale du Pacifique (PST), sans changement pour l'heure d'été.

Exemples de requêtes

Les requêtes sont envoyées en tant qu'objets JSON à l'aide d'une requête POST pour https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" avec les données de requête en tant qu'objet JSON dans le corps 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"]}'

Remarque:L'exemple précédent concerne les systèmes basés sur macOS ou Linux, y compris le shell Git BASH pour Windows. D'autres systèmes peuvent nécessiter de légères modifications. Par exemple, la ligne de commande cmd.exe n'accepte pas les guillemets simples pour les paramètres, ni les continuations de ligne (\). Elle nécessite donc d'utiliser des guillemets doubles (en échappant les guillemets internes si nécessaire avec \") et une seule ligne.

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:

• cumulative_layout_shift
• first_contentful_paint
• first_input_delay (obsolète)
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• navigation_types
• form_factors (uniquement si aucun formFactor n'est spécifié dans la requête)

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

Consultez Utiliser l'API Chrome UX Report pour obtenir d'autres exemples de requêtes.

Pipeline de données

L'ensemble de données CrUX est traité via un pipeline afin de consolider, agréger et filtrer les données avant d'être disponibles à l'aide de l'API.

La moyenne glissante

Les données du rapport d'expérience utilisateur Chrome correspondent à 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é correspondent en réalité aux données cumulées des 28 derniers jours.

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

Mises à jour quotidiennes

Les données sont mises à jour quotidiennement vers 04h00 UTC. Il n'existe pas de contrat de niveau de service concernant les délais de mise à jour. Ces délais sont exécutés chaque jour de la façon la plus optimale possible.

Attention : Les données ne diffèrent pas le même jour après leur mise à jour vers 4h UTC. Les appels répétés produisent les mêmes résultats.

Schéma

Il existe un seul point de terminaison pour l'API CrUX qui accepte les requêtes HTTP POST. L'API renvoie un record qui contient un ou plusieurs metrics correspondant aux données de performances sur le point de départ ou la page demandés.

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:

{
  "effectiveConnectionType": string,
  "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
effectiveConnectionType	string Le type de connexion effectif est une dimension de requête qui spécifie la classe de réseau effective à laquelle les données de l'enregistrement doivent appartenir. Ce champ utilise les valeurs ["offline", "slow-2G", "2G", "3G", "4G"] comme spécifié dans la spécification de l'API Network Information Remarque: Si aucun type de connexion effectif n'est spécifié, un enregistrement spécial avec des données globales sur tous les types de connexion effectifs sera renvoyé.
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 avec des données agrégées sur tous les facteurs de forme est renvoyé.
metrics[]	string Métriques à inclure dans la réponse. Si aucune valeur n'est spécifiée, toutes les métriques trouvées sont renvoyées. Valeurs autorisées: ["cumulative_layout_shift", "first_contentful_paint", "first_input_delay", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
Champ d'union url_pattern. url_pattern est l'identifiant principal pour une recherche d'enregistrements. 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 Le url url_pattern fait référence à un format d'URL correspondant à n'importe quelle URL arbitraire. Exemples : "https://example.com/, https://cloud.google.com/why-google-cloud/"

Par exemple, pour demander les valeurs Contentful Paint les plus élevées pour ordinateur pour 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 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.

{
  "effectiveConnectionType": string,
  "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 est 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é, les données agrégées sur tous les facteurs de forme sont renvoyées.
effectiveConnectionType	string Le type de connexion effectif est la classe de connexion générale que tous les utilisateurs ont rencontrés pour cet enregistrement. Ce champ utilise les valeurs ["offline", "slow-2G", "2G", "3G", "4G"] comme spécifié dans: https://wicg.github.io/netinfo/#effective-connection-types Si le type de connexion effectif n'est pas spécifié, des données agrégées sur tous les types de connexion effectifs sont 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 pour laquelle cet enregistrement est destiné. Remarque: Lorsque vous spécifiez un origin, les données des chargements sous cette origine sur toutes les pages sont agrégées en données d'expérience utilisateur au niveau de l'origine.
url	string url spécifie une URL spécifique pour laquelle cet enregistrement est destiné. Remarque: Lorsque vous spécifiez une valeur 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, telle que First Contentful Paint. Il peut contenir un histogramme récapitulatif de l'utilisation réelle de Chrome sous la forme d'une série de bins, des données de centile spécifiques (telles que p75), ou des 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 comportera au moins un bin, et les densités de tous les bins s'additionneront pour être d'environ 1.
percentiles	object (Percentiles) Centiles utiles communs de la métrique. Le type de valeur des centiles sera le même que les types de valeurs indiqués pour les bins d'histogramme.
fractions	object (Fractions) Cet objet contient des fractions étiquetées, dont la somme est égale à ~1. Les fractions sont arrondies à quatre décimales.

Bin

Un bin est une partie distincte des données s'étendant du début à la fin, ou lorsqu'aucune fin n'est fournie du début à l'infini positif.

Les valeurs de début et de fin d'un bin sont fournies dans le type de valeur de la métrique qu'il représente. Par exemple, la métrique "First Contentful Paint" est mesurée en millisecondes et exposée en tant que "ints". Par conséquent, ses classes de métriques utilisent int32 pour ses types de début et de fin. Toutefois, le décalage de mise en page cumulatif est mesuré en décimales sans unité et est exposé sous la forme d'une chaîne encodée sous forme décimale. Par conséquent, ses classes de métriques utiliseront des chaînes pour son type de valeur.

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

Champs
start	(integer | string) "début" est le début du bin de données.
end	(integer | string) La fin est la fin de la classe de données. Si la valeur de fin n'est pas renseignée, alors le bin n'a pas de fin et est valide de début à +inf.
density	number Proportion d'utilisateurs ayant constaté la valeur de ce bin pour la métrique donnée. La densité est arrondie à quatre décimales.

Centiles

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

{
  "P75": value
}

Champs
p75	(integer | string) Pour 75% des chargements de page, la métrique donnée est égale ou inférieure à cette valeur.

Fractions

Fractions contient des fractions étiquetées dont la somme totale est ~1. Chaque étiquette décrit un chargement de page. Par conséquent, les métriques représentées de cette manière peuvent être considérées comme des valeurs distinctes plutôt que numériques, et les fractions expriment la fréquence de mesure d'une valeur distincte particulière.

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

Comme pour les valeurs de densité dans les classes d'histogramme, chaque fraction est un nombre 0.0 <= value <= 1.0, dont la somme est d'environ 1,0.

UrlNormalization

Objet représentant les actions de normalisation entreprises pour normaliser une URL afin d'augmenter les chances de réussite de la recherche. Il s'agit de modifications automatisées simples apportées lors de la recherche du url_pattern fourni. Les actions complexes telles que le suivi de 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 les actions de normalisation. Il s'agit d'une URL d'expérience utilisateur valide qui pourrait raisonnablement être recherchée.

Limites de débit

L'API CrUX est limitée à 150 requêtes par minute et par projet Google Cloud, ce qui est sans frais. Vous pouvez consulter cette limite et votre utilisation actuelle dans la console Google Cloud. Ce quota généreux devrait être suffisant pour la grande majorité des cas d'utilisation et il n'est pas possible de payer un quota supplémentaire.