API CrUX History

Publié le 7 février 2023, dernière mise à jour le 11 avril 2025

L'API CrUX History permet d'accéder à un historique de six mois de données sur l'expérience utilisateur réelle avec une granularité au niveau de la page et de l'origine, avec une faible latence.

Essayer

Cas d'utilisation courant

L'API CrUX History permet d'interroger l'historique des métriques d'expérience utilisateur pour un URI spécifique, par exemple "Obtenir les tendances historiques de l'expérience utilisateur pour l'origine https://example.com".

L'API History suit la même structure que l'API CRUX quotidienne, à l'exception des valeurs qui sont indiquées dans un tableau et des clés qui sont associées à des noms au pluriel (par exemple, histogramTimeseries au lieu de histogram ou p75s au lieu de p75).

Clé API CrUX

Comme pour l'API quotidienne, l'utilisation de l'API History CrUX nécessite une clé API Google Cloud provisionnée pour l'utilisation de Chrome UX Report API. Vous pouvez utiliser la même clé pour les API "daily" et "history".

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 par rapport auquel 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.

Facteur de forme

L'API CrUX History n'est disponible qu'agrégée par la dimension "facteur de forme". Il s'agit d'une classe d'appareils générale divisée en PHONE, TABLET et DESKTOP.

Métrique

Nous rapportons les métriques sous forme de séries temporelles d'agrégations statistiques, qui sont des histogrammes, des percentiles et des fractions.

des histogrammes ;

Lorsque les métriques sont exprimées dans un tableau d'histogramme, chaque entrée de la série temporelle représente le pourcentage de chargements de page pour lesquels la métrique est comprise dans un intervalle, proportionnellement à l'ensemble. Les points de données sont présentés dans l'ordre des dates de la période de collecte également renvoyées par l'API. Le premier point correspond à la période la plus ancienne, et le dernier à la période de collecte la plus récente.

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

{
  "histogramTimeseries": [
    {
      "start": 0,
      "end": 2500,
      "densities": [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]
    },
    {
      "start": 2500,
      "end": 4000,
      "densities": [0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527]
    },
    {
      "start": 4000,
      "densities": [0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285]
    }
  ],
}

Ces données indiquent que 91,90% des chargements de pages ont enregistré une valeur de métrique d'exemple comprise entre 0 ms et 2 500 ms pour la première période de collecte de l'historique, suivie de 92,03%, 91,94 %, etc. 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, 5,21% des chargements de pages ont enregistré une valeur de métrique d'exemple comprise entre 2 500 ms et 4 000 ms au cours de la première période de collecte de l'historique, et 2,88% des chargements de pages ont enregistré une valeur supérieure à 4 000 ms au cours de la première période de collecte de l'historique.

Centiles

Les métriques peuvent également contenir des séries temporelles de percentiles qui peuvent être utiles pour une analyse supplémentaire.

Les points de données sont présentés dans l'ordre des dates de la période de collecte également renvoyées par l'API. Le premier point correspond à la période la plus ancienne, et le dernier à la période de collecte la plus récente.

{
  "percentilesTimeseries": {
    "p75s": [1362, 1352, 1344, 1356, 1366, 1377]
  },
}

Ces centiles peuvent afficher 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.

Fractions

Les métriques peuvent être exprimées sous forme de séries temporelles de fractions libellées. Chaque libellé décrit une charge de page d'une manière particulière. Les points de données sont présentés dans l'ordre des dates de la période de collecte également renvoyées par l'API. Le premier point correspond à la période la plus ancienne, et le dernier à la période de collecte la plus récente.

Exemple :

{    
  "fractionTimeseries": {
    "desktop": {"fractions": [0.3195, 0.2115, 0.1421]},
    "phone": {"fractions": [0.6295, 0.7544, 0.8288]},
    "tablet": {"fractions": [0.051, 0.0341, 0.029]}
  }
}

Dans cet exemple, le point de données le plus récent indique que 14,21% des chargements de pages proviennent d'ordinateurs et 82,88% de téléphones.

Types de valeurs de métrique

Comme l'API CrUX History utilise les mêmes types de valeurs de métrique, vous pouvez consulter la documentation sur les types de valeurs de métrique quotidienne de l'API CrUX pour en savoir plus.

Éligibilité des métriques

En fonction des critères d'éligibilité, une origine ou une URL ne peut être éligible qu'à certaines des périodes de collecte couvertes par l'API CrUX History. Dans ce cas, l'API CrUX History renvoie "NaN" pour les densités histogramTimeseries et null pour les percentilesTimeseries pour les périodes de collecte qui ne comportent aucune donnée éligible. La raison de cette différence est que les densités d'histogramme sont toujours des nombres, tandis que les percentiles peuvent être des nombres ou des chaînes (CLS utilise des chaînes, même si elles ressemblent à des nombres).

Par exemple, si la deuxième période ne contient aucune donnée éligible, le résultat s'affiche comme suit:

{
  "histogramTimeseries": [
    {
      "start": 0,
      "end": 2500,
      "densities": [0.9190, "NaN", 0.9194, 0.9195, 0.9183, 0.9187]
    },
    {
      "start": 2500,
      "end": 4000,
      "densities": [0.0521, "NaN", 0.0518, 0.0518, 0.0526, 0.0527]
    },
    {
      "start": 4000,
      "densities": [0.0288, "NaN", 0.0286, 0.0285, 0.0290, 0.0285]
    }
  ],
  "percentilesTimeseries": {
    "p75s": [1362, null, 1344, 1356, 1366, 1377]
  },
}

Si des URL ou des origines deviennent éligibles ou non au fil du temps, vous remarquerez peut-être de nombreuses entrées manquantes.

Périodes de collecte

L'API CrUX History contient un objet collectionPeriods avec un tableau de champs firstDate et endDate représentant les dates de début et de fin de chaque période d'agrégation. Exemple :

    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }
    ]

Ces périodes de collecte sont triées par ordre croissant et représentent la période de chaque point de données dans les autres sections de la réponse.

L'API History est mise à jour chaque lundi et contient les données jusqu'au samedi précédent (avec un délai standard de deux jours). Il contient les données des 40 dernières semaines (une période de collecte par semaine). Par défaut, 25 périodes de collecte sont renvoyées. Pour modifier ce paramètre, définissez "collectionPeriodCount" dans la requête sur un nombre compris entre 1 et 40.

Étant donné que chaque période de collecte contient les données agrégées des 28 derniers jours et que les périodes de collecte sont hebdomadaires, elles se chevauchent. Elles sont semblables à une moyenne mobile des données, avec trois semaines de données incluses dans chaque période ultérieure et une semaine différente.

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:queryHistoryRecord?key=[YOUR_API_KEY]", avec les données de requête sous forme d'objet JSON dans le corps de la requête POST.

Notez que queryHistoryRecord remplace queryRecord dans l'API CrUX quotidienne.

Voici un exemple de corps:

{
  "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:queryHistoryRecord?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
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• 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 voir d'autres exemples de requêtes, consultez le guide Utiliser l'API History CrUX.

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

L'API History contient un certain nombre de périodes de collecte, chacune couvrant ces 28 jours. Étant donné que chaque période de collecte contient les données agrégées des 28 derniers jours et que les périodes de collecte sont hebdomadaires, elles se chevauchent. Elles sont semblables à une moyenne mobile des données, avec trois semaines de données incluses dans chaque période ultérieure et une semaine différente.

Mises à jour hebdomadaires

L'API History est mise à jour chaque lundi vers 4h UTC et contient les données jusqu'au samedi précédent (selon le décalage standard de deux jours). Il contient les données des 40 dernières semaines (environ 10 mois), une période de collecte par semaine. Notez que par défaut, nous renvoyons 25 entrées par série temporelle. Vous pouvez toutefois remplacer ce nombre en spécifiant le paramètre de requête collectionPeriodCount.

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

L'URL utilise la syntaxe de transcodage gRPC.

Corps de la requête

L'API CrUX History utilise des corps de requête similaires à ceux de l'API CrUX quotidienne, avec un champ "collectionPeriodCount" facultatif supplémentaire:

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

  "collectionPeriodCount": int32 // Optional: Number of periods to collect
}

Par exemple, pour demander les valeurs de Largest Contentful Paint sur ordinateur pour la page d'accueil de web.dev:

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

Cette requête similaire inclut le champ facultatif collectionPeriodCount et génère 40 entrées de séries temporelles fournissant environ 10 mois d'historique des performances Web pour l'origine https://web.dev:

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ],
  "collectionPeriodCount": 40
}

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": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogramTimeseries": [{
            "start": 0, "end": 2500, "densities": [
              0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187, ...
            ]
          }, {
            "start": 2500, "end": 4000, "densities": [
              0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527, ...
            ]
          },  {
            "start": 4000, "densities": [
              0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285, ...
            ]
          }
        ],
        "percentilesTimeseries": {
          "p75s": [
            1362, 1352, 1344, 1356, 1366, 1377, ...
          ]
        }
      }
    },
    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }, {
        ...
      }
    ]
  }
}

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 sur l'expérience utilisateur pour une seule métrique de performances Web, comme la première peinture avec contenu. Il contient un histogramme récapitulatif de l'utilisation réelle de Chrome sous la forme d'une série de bins.

{
  "histogramTimeseries": [
    {
      object (Bin)
    }
  ],
  "percentilesTimeseries": {
    object (Percentiles)
  }
}

ou

"fractionTimeseries": {
  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,
  "densities": [number, number, number...etc.]
}

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 séries temporelles de fractions libellées qui totalisent environ 1 par entrée. Chaque libellé 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": { "fractions": array[fraction]},
  "label_1": { "fractions": array[fraction]},
  ...
  "label_n": { "fractions": array[fraction]}
}

Tout comme les valeurs de densité dans les bacs d'histogramme, chaque fraction est un nombre 0.0 <= value <= 1.0, et leur somme est d'environ 1,0. Lorsque la métrique n'est pas disponible pour une période de collecte donnée, l'entrée correspondante est "NaN" dans tous les tableaux de fractions.

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 de base et automatisées 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 History partage la même limite que l'API CrUX, à savoir 150 requêtes par minute et par projet Google Cloud pour les deux API, qui sont proposées 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.