API CrUX

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

Essayer

Cas d'utilisation courant

L'API CrUX permet d'interroger les métriques sur l'expérience utilisateur pour un URI spécifique, par exemple "Obtenir les 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 l'utilisation de Chrome UX Report API.

Obtenir et utiliser une clé API

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 la section Exemples de requêtes.

Modèle de données

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

Enregistrer

Information distincte sur 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 comporte des pages telles que définies par 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 sont renvoyées et agrégé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. Reprenons 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 seront renvoyées.

Dimensions

Les dimensions identifient un groupe spécifique de données avec lequel 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 comporte un certain nombre de valeurs. Si vous ne spécifiez pas de dimension, elle sera implicitement agrégée pour toutes les valeurs. Par exemple, si vous ne spécifiez aucun facteur de forme, l'enregistrement contient des informations sur les charges qui ont eu lieu 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 d'appareils générale divisée en PHONE, TABLET et DESKTOP.

Métrique

Nous présentons les métriques sous forme d'agrégations statistiques, sous forme d'histogrammes, de percentiles et de fractions.

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

Un histogramme à trois classes 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,la métrique de l'exemple a été mesurée entre 0 ms et 1 000 ms. Les unités de la métrique ne sont pas incluses dans cet histogramme. Dans ce cas, nous allons supposer qu'il s'agit de millisecondes.

De plus, 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 percentiles qui peuvent être utiles pour une analyse supplémentaire. Nous rapportons des valeurs de métrique 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. Ils ne correspondent donc pas nécessairement à un percentile interpolé basé sur l'histogramme binaire 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.

Fractions

Les fractions indiquent les pourcentages de chargements de pages qui peuvent être libellés d'une manière particulière. Dans ce cas, les valeurs de la métrique correspondent à ces libellés.

Par exemple, la métrique form_factors se compose 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étrique

Mappage des noms de métriques BigQuery

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 ce jour ou si elles renvoient les mêmes données qu'hier.

La période de collecte est également disponible dans PageSpeed Insights:

De plus, collectionPeriod affiche toujours 28 jours, même si les données ne couvrent pas la totalité de cette période (par exemple, si une page a été lancée il y a moins de 28 jours). collectionPeriod correspond à la période sur laquelle les données CrUX ont été agrégées, et non nécessairement à la période qu'elles représentent.

Exemples de requêtes

Les requêtes sont envoyées sous forme d'objets JSON à l'aide d'une requête POST à https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]", avec les données de requête sous forme d'objet JSON dans le corps de la requête POST:

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

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

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
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• navigation_types
• form_factors (signalé 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 obtenir 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.

Moyenne glissante

Les données du rapport d'expérience utilisateur Chrome sont une moyenne glissante sur 28 jours des métriques agrégées. Cela signifie que les données présentées dans le rapport UX Chrome à un moment donné correspondent en fait aux données des 28 derniers jours cumulées.

Cela ressemble à la façon dont l'ensemble de données CRUX dans BigQuery agrège les rapports mensuels.

Infos quotidiennes

Les données sont mises à jour quotidiennement vers 4h00 UTC. Aucun contrat de niveau de service n'est appliqué aux heures de mise à jour. Elles sont exécutées tous les jours dans la mesure du possible.

Schéma

L'API CrUX ne comporte qu'un seul point de terminaison, qui accepte les requêtes HTTP POST. L'API renvoie un record contenant un ou plusieurs metrics correspondant aux données de performances de l'origine ou de 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:

{
  "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.
}

Par exemple, pour demander les valeurs de Largest Contentful Paint sur ordinateur pour la page d'accueil de la documentation destinée aux 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 précédente peut être la suivante:

{
  "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.

{
  "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.
}

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, comme la première peinture avec contenu. 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 percentile spécifiques (telles que le p75) ou de fractions libellées.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

ou

{
  "fractions": {
    object (Fractions)
  }
}

Bin

Un bin est une partie distincte de données allant du début à la fin, ou, si aucune fin n'est indiquée, du début à l'infini positif.

Les valeurs de début et de fin d'une tranche sont indiquées dans le type de valeur de la métrique qu'elle représente. Par exemple, le premier rendu de contenu est mesuré en millisecondes et exposé sous forme d'entiers. Par conséquent, ses intervalles de métriques utiliseront des entiers 32 bits pour ses types de début et de fin. Toutefois, le décalage de mise en page cumulé est mesuré en décimaux sans unité et est exposé sous la forme d'un décimal encodé en tant que chaîne. Par conséquent, ses intervalles de métriques utiliseront des chaînes pour leur type de valeur.

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

Centiles

Percentiles contient les valeurs synthétiques d'une métrique à un percentile statistique donné. Elles permettent d'estimer la valeur d'une métrique pour un pourcentage d'utilisateurs par rapport au nombre total d'utilisateurs.

{
  "P75": value
}

Fractions

Fractions contient des fractions libellées qui totalisent environ 1. Chaque étiquette décrit une page chargée d'une certaine manière. 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 particulière a été mesurée.

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

Tout comme les valeurs de densité dans les buckets d'histogramme, chaque fraction est un nombre 0.0 <= value <= 1.0, et leur somme est d'environ 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 modifications automatiques simples qui sont effectuées lorsque la recherche de l'url_pattern fournie est connue pour échouer. Les actions complexes, comme le suivi des redirections, ne sont pas gérées.

{
  "originalUrl": string,
  "normalizedUrl": string
}

Limites de débit

L'API CrUX est limitée à 150 requêtes par minute et par projet Google Cloud, et est proposée sans frais. Vous pouvez consulter cette limite et votre utilisation actuelle dans la console Google Cloud. Ce quota généreux devrait suffire à la grande majorité des cas d'utilisation. Il n'est pas possible de payer pour augmenter le quota.