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'utilisation de 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 les exemples de requêtes ci-dessous.

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

Informations discrètes relatives à une page ou à un site. Un enregistrement peut contenir des données spécifiques à un identifiant et à une combinaison de dimensions spécifique. 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 dans cette origine sont regroupées. Par exemple, supposons que l'origine http://www.example.com comportait des pages comme indiqué par ce sitemap:

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

Autrement dit, lorsque vous interrogez le rapport d'expérience utilisateur Chrome avec l'origine 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 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 sur toutes les valeurs. Par exemple, si vous ne spécifiez pas de 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ée en PHONE, TABLET et DESKTOP.

Type de connexion effectif

Le type de connexion effectif correspond à l'estimation de la qualité de la connexion de l'appareil lorsque l'utilisateur 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

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.

Histogramme

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

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

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.38179
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.49905
    },
    {
      "start": 3000,
      "density": 0.11916
    }
  ]
}

Ces données indiquent que pour 38, 179% 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 des millisecondes.

De plus, 49,905% des chargements de page ont constaté une valeur de métrique comprise entre 1 000 ms et 3 000 ms, et 11,916 % ont constaté 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 générons des rapports sur 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 de binning finales. Ils ne correspondent donc pas nécessairement à un centile interpolé basé sur l'histogramme de binning 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 le pourcentage 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. Exemple :

"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 la métrique de l'API CrUX Type de données Unités métriques Agrégations statistiques Documentation web.dev
cumulative_layout_shift double encodage en tant que chaîne sans unité Histogramme à trois classes, centiles avec p75 cls
first_contentful_paint int milliseconde Histogramme à trois classes, centiles avec p75 PFC
first_input_delay int milliseconde Histogramme à trois classes, centiles avec p75 fid
interaction_to_next_paint int milliseconde Histogramme à trois classes, centiles avec p75 INP
largest_contentful_paint int milliseconde Histogramme à trois classes, centiles avec p75 LPC
experimental_time_to_first_byte int milliseconde Histogramme à trois classes, centiles avec p75 ttfb

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
form_factors 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. Voici un 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 ce jour-là 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, et leur disponibilité dans l'API nécessite un certain temps de traitement. 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 via une requête POST adressée à https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" avec les données de requête sous la forme d'un objet JSON dans le corps POST, par exemple,

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

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

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
  • interaction_to_next_paint
  • largest_contentful_paint
  • experimental_time_to_first_byte
  • form_factors (rapport 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, d'agréger et de filtrer les données avant d'être disponible via l'API.

La moyenne glissante

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

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

Infos 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 s'exécutent de la façon 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 contenant 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 effective 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 indiqué 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 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 est renvoyé avec des données globales sur tous les facteurs de forme.

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. Le format d'URL est le principal identifiant pour une recherche d'enregistrements. Il peut s'agir de l'un des différents types de valeurs. url_pattern ne peut être qu'un des éléments suivants :
origin

string

Le format d'URL "origine" désigne un format d'URL qui est l'origine d'un site Web.

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

url

string

Le format d'URL "url" fait référence à 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 importantes 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 dans la requête ci-dessus pourrait être:

{
  "record": {
    "key": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.98148451581189577
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.010814353596591841
          },
          {
            "start": 4000,
            "density": 0.0077011305915124116
          }
        ],
        "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 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 correspond à la classe de connexion générale rencontrée par tous les utilisateurs pour cet enregistrement. Ce champ utilise les valeurs ["offline", "slow-2G", "2G", "3G", "4G"] comme spécifié à l'adresse: https://wicg.github.io/netinfo/#effective-connection-types

Si le type de connexion effectif n'est pas spécifié, les données agrégées de 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" indique l'origine à laquelle l'enregistrement est destiné.

Remarque: Lorsque vous spécifiez une origine, les données des chargements sous cette origine sur toutes les pages sont agrégées en 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 associées à cette URL sont regroupé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 ~1.

percentiles

object (Percentiles)

Centiles utiles courants de la métrique. Le type de valeur des centiles sera le même que les types de valeurs indiqués pour les classes d'histogrammes.

fractions

object (Fractions)

Cet objet contient des fractions étiquetées, dont la somme est égale à ~1.

Bin

Une bin est une partie discrète des données qui s'étendent 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 "int". Par conséquent, ses classes de métriques utilisent des entiers 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'un nombre décimal encodé sous forme de chaîne. 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

value (Value format)

Le début est le début du bin de données.

end

value (Value format)

La fin est la fin de la classe de données. Si le champ "end" n'est pas renseigné, la classe n'a pas de fin et est valide du début à la valeur +inf.

density

number

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

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 ressentie par un pourcentage d'utilisateurs par rapport au nombre total d'utilisateurs.

{
  "P75": value
}
Champs
p75

value (Value format)

75% des utilisateurs ont constaté que la métrique donnée était égale ou inférieure à cette valeur.

Fractions

Fractions contient des fractions étiquetées qui s'additionnent pour faire ~1. Chaque libellé 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 produisant des valeurs distinctes plutôt que des valeurs numériques, et les fractions expriment la fréquence à laquelle une valeur distincte 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, qui se cumule jusqu'à ~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 automatisées qui sont apportées lors de la recherche du url_pattern fourni et qui échoueraient. 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 suffire pour la grande majorité des cas d'utilisation. À l'heure actuelle, il n'est pas possible de payer pour augmenter ce quota.