API CrUX

L'API CrUX offre un accès à faible latence à des données agrégées sur l'expérience utilisateur 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 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 provisionnée pour Chrome UX Report API.

Obtenir et utiliser une clé API

Obtenir une clé

Vous pouvez également en créer un 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.

Enregistrement

Informations discrètes relatives à 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 regroupées. Par exemple, supposons que l'origine http://www.example.com comportait des pages telles que décrites 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 d'expérience utilisateur 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 seront renvoyées, regroupées, car il s'agit de toutes les pages sous 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 la page sont renvoyées.

Dimensions

Les dimensions identifient un groupe spécifique de données avec lesquelles un enregistrement est agrégé. Par exemple, un facteur de forme PHONE indique que l'enregistrement contient des informations sur les chargements effectués sur un appareil mobile. Chaque dimension comporte un certain nombre de valeurs. Si vous ne spécifiez pas cette dimension, elle sera implicitement agrégée pour toutes les valeurs. Par exemple, si vous spécifiez "aucun facteur de forme", cela signifie que l'enregistrement contient des informations sur les chargements effectués sur n'importe quel facteur de forme.

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é en PHONE, TABLET et DESKTOP.

Type de connexion effectif

Effective Connection Type (Type de connexion effectif) : estimation de la qualité de connexion de l'appareil lorsqu'il accède à la page. Il s'agit d'une classe générale divisée en offline, slow-2G, 2G, 3G et 4G.

Métrique

Les métriques sont présentées sous forme d'agrégations statistiques sous forme d'histogrammes, de centiles et de fractions.

Les valeurs à virgule flottante sont arrondies à quatre chiffres après la virgule. Notez que les métriques cumulative_layout_shift sont encodées en double sous la forme d'une chaîne. Elles ne sont donc pas considérées comme des nombres à 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 indiquons les pourcentages de chargements de page compris dans des plages spécifiques 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 contenues dans cet histogramme. Dans ce cas, nous allons partir du principe qu'il s'agit de millisecondes.

En outre, 49,91% des chargements de page ont généré une valeur de métrique comprise entre 1 000 ms et 3 000 ms,et que 11, 92% une valeur supérieure à 3 000 ms.

Centiles

Les métriques peuvent également contenir des centiles qui peuvent être utiles pour des analyses supplémentaires. Nous indiquons des valeurs de métriques spécifiques au centile donné pour cette métrique. Ils se basent sur l'ensemble complet des données disponibles et non sur les données binaires finales. Elles ne correspondent donc pas nécessairement à un centile interpolé basé sur le l'histogramme binaire final.

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

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

Fractions

Les fractions indiquent les pourcentages de chargements de page auxquels il est possible d'attribuer un libellé d'une certaine manière. Dans ce cas, les valeurs des métriques sont ces étiquettes.

Par exemple, la métrique form_factors est constituée d'un objet fractions qui liste 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 100 % au total.

Types de valeurs de métriques

Nom de métrique de l'API CrUX	Type de données	Unités métriques	Agrégations statistiques	Documentation
cumulative_layout_shift	Deux décimales à double encodage sous forme de chaîne	sans unité	histogramme avec trois classes, percentiles avec p75	cls
first_contentful_paint	int	millisecondes	histogramme avec trois bins, centiles avec p75	fcp
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_time_to_first_byte	int	millisecondes	histogramme avec trois bins, centiles avec p75	ttfb
form_factors	Double décimale avec 4 chiffres	pourcentage	Mappage d'un facteur de forme à une fraction	facteurs de forme
navigation_types	Double décimale avec 4 chiffres	pourcentage	Mappage entre le type de navigation et la fraction	types de navigation
round_trip_time	int	millisecondes	centiles avec p75	rtt

Mappage des noms des métriques BigQuery

Nom de 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	n/a

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 déjà été mises à jour pour le jour concerné ou si elles renvoient les mêmes données qu'hier.

Notez que l'API CrUX est à environ deux jours de retard sur la date d'aujourd'hui, car elle attend les données complètes pour la journée, et un temps de traitement est nécessaire avant qu'elles ne soient disponibles dans l'API. Le fuseau horaire utilisé est celui de l'heure normale du Pacifique (PST), qui ne change pas 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 envoyée à https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]". Le corps de la requête POST contient les données de requête sous la forme d'un objet JSON:

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

Par exemple, vous pouvez l'appeler depuis curl à l'aide de 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"]}'

Pour accéder aux données au niveau de la page via l'API, transmettez 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
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• navigation_types
• form_factors (indiqué 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.

Pour découvrir d'autres exemples de requêtes, consultez Utiliser l'API Chrome UX Report.

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 d'expérience utilisateur Chrome correspondent à une moyenne glissante des métriques agrégées sur 28 jours. Cela signifie que les données présentées à un moment donné dans le rapport d'expérience utilisateur Chrome correspondent en réalité aux données des 28 derniers jours regroupées.

Cela ressemble à la façon dont l'ensemble de données CRUX dans BigQuery agrège 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 heures de mise à jour. il est exécuté du mieux possible chaque jour.

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 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:

{
  "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 effective est une dimension de requête qui spécifie la classe réseau effective à laquelle les données de l'enregistrement doivent appartenir. Ce champ utilise les valeurs ["offline", "slow-2G", "2G", "3G", "4G"] telles que spécifiées dans la spécification de l'API Network Information. Remarque: Si aucun type de connexion effectif n'est spécifié, un enregistrement spécial contenant des données globales sur tous les types de connexion effectifs est 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 contenant des données globales sur tous les facteurs de forme est renvoyé.
metrics[]	string Métriques à inclure dans la réponse. Si aucune métrique 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"]
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 correspondant à 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 qui correspond à n'importe quelle URL arbitraire. Exemples : "https://example.com/, https://cloud.google.com/why-google-cloud/"

Par exemple, pour demander les plus grandes valeurs Contentful Paint 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 un 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 dans la requête précédente peut ê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 correspond à la classe de l'appareil que tous les utilisateurs ont utilisé pour accéder au site pour cet enregistrement. Si le facteur de forme n'est pas spécifié, les données globales sont renvoyées pour tous les facteurs de forme.
effectiveConnectionType	string Le type de connexion effective correspond à la classe de connexion générale que tous les utilisateurs ont rencontrée pour cet enregistrement. Ce champ utilise les valeurs ["offline", "slow-2G", "2G", "3G", "4G"] comme indiqué dans https://wicg.github.io/netinfo/#effective-connection-types. Si le type de connexion effective n'est pas spécifié, les données globales sont renvoyées pour tous les types de connexions effectives.
Champ d'union url_pattern. Le format d'URL correspond à l'URL à laquelle s'applique l'enregistrement. url_pattern ne peut être qu'un des éléments suivants :
origin	string origin spécifie l'origine à laquelle cet enregistrement est destiné. Remarque: Lorsque vous spécifiez un origin, les données relatives aux chargements sous cette origine sur toutes les pages sont agrégées dans les données sur l'expérience utilisateur au niveau de l'origine.
url	string url spécifie l'URL spécifique à laquelle cet enregistrement est destiné. Remarque: Lorsque vous spécifiez une 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 métrique de performances Web unique, 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 données de centiles bins spécifiques. (p.75, par exemple) ou contenir 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'additionnent pour atteindre ~1.
percentiles	object (Percentiles) Centiles utiles courants de la métrique. Le type de valeur pour les centiles est identique à celui fourni 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

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

Les valeurs de début et de fin d'un bin sont indiquées dans le type de valeur de la métrique qu'il représente. Par exemple, le First Contentful Paint est mesuré en millisecondes et exposé en tant qu'ents. Par conséquent, ses bins de métriques utiliseront des int32s pour ses types de début et de fin. Toutefois, le décalage de mise en page cumulé est mesuré en nombres décimaux sans unité et est exposé sous la forme d'un encodage décimal sous forme de chaîne. Par conséquent, ses bins de métriques utilisent 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) "Fin" correspond à la fin du bin de données. Si la valeur end n'est pas renseignée, alors le bin n'a pas de fin et est valide du début à +inf.
density	number Proportion d'utilisateurs ayant constaté la valeur de cette classe 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 vécue par un pourcentage d'utilisateurs par rapport au nombre total d'utilisateurs.

{
  "P75": value
}

Champs
p75	(integer | string) 75% des chargements de pages ont enregistré une valeur inférieure ou égale à cette valeur pour la métrique donnée.

Fractions

Fractions contient des fractions étiquetées dont la somme est égale à ~1. Chaque étiquette décrit un chargement d'une 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 produit des valeurs distinctes au lieu de valeurs numériques, et les fractions expriment la fréquence de mesure d'une valeur distincte spécifique.

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

Tout comme les valeurs de densité dans les bins d'histogramme, chaque fraction est un nombre. 0.0 <= value <= 1.0.Leur somme est donc égale à ~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 simples modifications automatiques qui sont effectuées lors de la recherche de l'url_pattern fourni comme ayant échoué. 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 à l'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 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 (accès 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.