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�: "/proxy/https://example.com", "/proxy/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�: "/proxy/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.