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.

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 qu'il puisse être utilisé 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 des 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.

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.

Provenance

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 sera associée à un certain nombre de valeurs et, implicitement, si vous ne la spécifiez pas, elle sera cumulée avec 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 correspondant à des plages spécifiques pour ces métriques.

Pour un exemple de métrique, un histogramme simple à trois bins 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 partons du principe que les millisecondes sont utilisées.

En outre, 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 des analyses supplémentaires. Nous indiquons des valeurs de métriques spécifiques au centile donné pour cette métrique. Ils sont basés sur l'ensemble complet de données disponibles et non sur les données binaires finales. Par conséquent, elles ne correspondent pas nécessairement à un centile interpolé basé sur le dernier histogramme binning.

{
  "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 un total de 100 %.

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 bins, centiles avec p75	cls
first_contentful_paint	int	millisecondes	histogramme avec trois bins, centiles avec p75	FCP
first_input_delay (obsolète)	int	millisecondes	histogramme avec trois bins, centiles avec p75	fid
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	pour cent	Mappage d'un facteur de forme à une fraction	facteurs de forme
navigation_types	Double décimale avec 4 chiffres	pour cent	Mise en correspondance du type de navigation avec 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
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
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 a environ deux jours de retard par rapport à la date d'aujourd'hui, car elle attend les données complètes pour la journée et un certain 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 utilise 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
• first_input_delay (obsolète)
• 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é par un pipeline afin de consolider, d'agréger et de 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 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.

Cette approche est semblable à celle utilisée pour regrouper les rapports mensuels dans l'ensemble de données CrUX sur BigQuery.

Mises à jour quotidiennes

Les données sont mises à jour quotidiennement vers 04h00 UTC. Il n'existe pas de contrat de niveau de service pour les heures de mise à jour. L'opération s'effectue de la manière la plus optimale 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", "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 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"], telles que spécifiées 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 bins, de données de centile spécifiques (telles que 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 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 décimales 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 de page d'une manière ou d'une autre. Par conséquent, les métriques représentées de cette manière peuvent être considérées comme produisant des valeurs distinctes plutôt que des valeurs numériques, et les fractions indiquent la fréquence à laquelle une valeur distincte spécifique a été mesurée.

{
  "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, dont la somme est é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.