API CrUX History

L'API CrUX History offre un accès à faible latence à six mois de données historiques sur l'expérience utilisateur réelle, au niveau de la page et de l'origine.

Cas d'utilisation courant

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

L'API History suit la même structure que l'API CrUX quotidienne, à la différence que les valeurs sont fournies dans un tableau et que les clés sont libellées avec 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 CrUX History nécessite une clé API Google Cloud. La même clé peut être utilisée pour les API Daily et History.

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 de PHONE indique que l'enregistrement contient des informations sur les chargements effectués sur un appareil mobile.

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

Métrique

Les métriques sont présentées sous forme de séries temporelles d'agrégations statistiques, c'est-à-dire des histogrammes, des centiles et des fractions.

des histogrammes ;

Lorsque les métriques sont exprimées dans un tableau d'histogramme, chaque entrée de série temporelle représente le pourcentage de chargements de page pour lesquels la métrique est tombée dans un intervalle, proportionnellement à tous. 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 point à la période de collecte la plus récente.

Un histogramme simple à trois bins 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 utilisateurs voient la valeur de la métrique d'exemple 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 contenues dans cet histogramme. Dans ce cas, nous prenons en compte la milliseconde.

En outre, 5,21% des utilisateurs voient la valeur de la métrique de l'exemple entre 2 500 ms et 4 000 ms lors de la première période de collecte de l'historique, et 2,88% des utilisateurs rencontrent une valeur supérieure à 4 000 ms lors de la première période de collecte de l'historique.

Centiles

Les métriques peuvent également contenir des séries temporelles de centiles 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 point à 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é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. Par conséquent, ils ne correspondent pas nécessairement à un centile interpolé basé sur l'histogramme de binning final.

Fractions

Les métriques peuvent être exprimées sous la forme d'une série temporelle de fractions étiquetées. Chaque étiquette décrit un chargement 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 point à la période de collecte la plus récente.

Exemple :

{
  "fractionTimeseries": {
    "desktop": { "fractions": [0.22, 0.22, 0.28, 0.32, 0.35, 0.37] },
    "phone": { "fractions": [0.76, 0.77, 0.60, 0.66, 0.65, 0.63] },
    "table": { "fractions": [0.02, 0.01, 0.02, 0.02, 0.0, 0.0] }
  },
}

Dans cet exemple, le point de données le plus récent indique que 37% des chargements de page provenaient d'un ordinateur et de 63% sur des téléphones.

Types de valeurs de métriques

Étant donné que l'API CrUX History utilise les mêmes types de valeurs de métriques, vous pouvez consulter la documentation sur les types de valeurs de métriques quotidiennes de l'API CrUX pour en savoir plus.

Éligibilité des métriques

Selon les critères d'éligibilité, il est possible qu'une origine ou une URL ne soit éligible que pour certaines 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 ne comportant aucune donnée éligible. La raison de cette différence est que les densités de l'histogramme sont toujours des nombres, tandis que les centiles peuvent être des nombres ou des chaînes (le CLS utilise des chaînes, même si elles ressemblent à des nombres).

Par exemple, si la deuxième période ne comporte aucune donnée éligible, le code 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]
  },
}

Pour les URL ou les origines qui ne sont plus éligibles 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 fenêtre d'agrégation. Voici un 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 dans l'ordre croissant et représentent la période de chacun des points de données dans les autres sections de la réponse.

L'API History est mise à jour tous les lundis et contient les données remontant au samedi précédent (conformément au délai standard de deux jours). Il contient les données des 25 dernières semaines, soit une période de collecte par semaine.

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

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

Notez l'utilisation de queryHistoryRecord à la place de queryRecord de 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 à 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: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
  • 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.

Pour obtenir d'autres exemples de requêtes, consultez Données des performances Web de l'historique via l'API CrUX.

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.

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 globales des 28 derniers jours et que les périodes sont hebdomadaires, elles se chevauchent. Elles sont similaires à une moyenne mobile de données, avec trois semaines de données incluses dans chaque période suivante, et une semaine étant différente.

Mises à jour hebdomadaires

L'API History est mise à jour tous les lundis vers 04h00 (UTC) et contient les données enregistrées jusqu'au samedi précédent (selon le décalage standard de deux jours). Il contient les données des 25 semaines précédentes (environ 6 mois), avec une période de collecte par semaine.

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

L'URL utilise la syntaxe de transcodage gRPC.

Corps de la requête

L'API CrUX History utilise les mêmes corps de requête que l'API CrUX quotidienne, mais ne prend pas en charge le champ de requête effectiveConnectionType.

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

{
  "origin": "https://web.dev/",
  "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": {
      "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.
}
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.

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 sur l'expérience utilisateur pour une seule métrique de performances Web, telle que First Contentful Paint. Il contient un histogramme récapitulatif de l'utilisation réelle de Chrome sous la forme d'une série d'bins.

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

ou

"fractionTimeseries": {
  object (Fractions)
}
Champs
histogramTimeseries[]

object (Bin)

Histogramme de série temporelle des expériences utilisateur pour une métrique. L'histogramme de série temporelle comportera au moins un bin, et les densités de tous les bins s'additionneront pour faire ~1.

Les valeurs manquantes pour cette période de collecte sont marquées comme "NaN".

percentilesTimeseries

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.

Les valeurs manquantes pour cette période de collecte sont marquées comme null.

fractionTimeseries

object (Fractions)

Cet objet contient des séries temporelles de fractions étiquetées, qui totalisent environ 1 par entrée.

Les entrées manquantes sont exprimées sous la forme"NaN" dans toutes les fractions.

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

densities

array[number]

Série temporelle de la 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
p75s

array[value] (Value format)

Séries temporelles des valeurs pour lesquelles 75% des utilisateurs ont constaté que la métrique donnée était égale ou inférieure à cette valeur.

Fractions

Fractions contient des séries temporelles de fractions étiquetées qui totalisent environ 1 par entrée. 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": { "fractions": array[fraction]},
  "label_1": { "fractions": array[fraction]},
  ...
  "label_n": { "fractions": array[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. Lorsque la métrique n'est pas disponible pour une période de collecte particulière, l'entrée correspondante est "NaN" dans tous les tableaux de fractions.

Champs
p75s

array[value] (Value format)

Séries temporelles des valeurs pour lesquelles 75% des utilisateurs ont constaté que la métrique donnée était égale ou inférieure à cette valeur.

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 History partage la même limite que l'API CrUX, à savoir 150 requêtes par minute et par projet Google Cloud, quelle que soit l'API. Cette limite 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 pour la grande majorité des cas d'utilisation. À l'heure actuelle, il n'est pas possible de payer pour augmenter ce quota.