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 d'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, si ce n'est que les valeurs sont fournies dans un tableau et que les clés comportent 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 l'API Daily et History.
Vous pouvez en créer un sur la page Identifiants et le provisionner pour l'utiliser avec 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 la section Exemples de requêtes.
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
Information discrète concernant 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 au niveau de cette origine sont regroupées. Par exemple, supposons que l'origine http://www.example.com comportait des pages telles que décrites par ce sitemap:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Ainsi, lorsque vous interrogez le rapport UX 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, 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 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 (histogrammes, centiles et 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 pages pour lesquels la métrique est tombée dans un intervalle, proportionnellement à l'ensemble. Les points de données sont présentés dans l'ordre des dates de 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 simple histogramme à 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 pour 91,90% des chargements de page, la valeur de la métrique d'exemple est comprise entre 0 ms et 2 500 ms pour la première période de collecte de l'historique, suivi de 92,03 % et 91,94%... Les unités de la métrique ne sont pas contenues dans cet histogramme. Dans ce cas, nous prenons en compte les millisecondes.
En outre, pour 5,21% des chargements de page,la valeur de la métrique d'exemple a été comprise entre 2 500 et 4 000 ms lors de la première période de collecte de l'historique, et 2,88% des chargements de page 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 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 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 à binning final.
Fractions
Les métriques peuvent être exprimées sous forme de séries temporelles 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 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.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 ont été effectués sur ordinateur et 82,88% sur téléphone.
Types de valeurs de métriques
Comme 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 quotidiens 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 qui ne comportent aucune donnée éligible. La différence s'explique par le fait 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 aucune donnée éligible n'est disponible pour la deuxième période, le résultat est le suivant:
{
"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 constaterez peut-être qu'il manque de nombreuses entrées.
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. 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 jusqu'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 de collecte sont hebdomadaires, elles se chevauchent. Ils s'apparentent à une moyenne mobile des données : l'équivalent d'une semaine de données est inclus dans chaque période suivante pour chaque période.
Exemples de requêtes
Les requêtes sont envoyées en tant qu'objets JSON à l'aide d'une requête POST pour 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 depuis 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_shiftfirst_contentful_paintfirst_input_delayinteraction_to_next_paintlargest_contentful_paintexperimental_time_to_first_bytenavigation_typesform_factors(uniquement si aucunformFactorn'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 le guide Utiliser l'API CrUX History 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, agréger et filtrer les données avant d'être disponibles via l'API.
La moyenne glissante
Les données du rapport d'expérience utilisateur Chrome correspondent à une moyenne glissante sur 28 jours de métriques agrégées. Cela signifie que les données présentées dans le rapport UX Chrome à un moment donné correspondent en réalité aux données cumulées des 28 derniers jours.
L'API History contient un certain nombre de périodes de collecte, chacune s'étendant sur 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 de collecte sont hebdomadaires, elles se chevauchent. Ils s'apparentent à une moyenne mobile des données : l'équivalent d'une semaine de données est inclus dans chaque période suivante pour chaque période.
Mises à jour hebdomadaires
L'API History est mise à jour tous les lundis aux alentours de 4h UTC et contient les données collectées jusqu'au samedi précédent (conformément au délai standard de deux jours). Il contient les données des 25 dernières semaines (environ 6 mois), soit 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 sont exécutés chaque jour de la façon la plus optimale possible.
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 qui contient 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, sauf qu'elle n'est pas compatible avec 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 de la requête précédente 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 |
Le facteur de forme est 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_. Le format d'URL est l'URL à laquelle l'enregistrement s'applique. url_ ne peut être qu'un des éléments suivants : |
|
origin |
"origin" spécifie l'origine pour laquelle cet 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 sous forme de données d'expérience utilisateur au niveau de l'origine. |
url |
Remarque: Lorsque vous spécifiez une valeur |
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. Elle 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)
}
| Champs | |
|---|---|
histogramTimeseries[] |
Histogramme de série temporelle des expériences utilisateur pour une métrique. L'histogramme de séries temporelles comportera au moins un bin, et les densités de tous les bins s'additionneront pour être d'environ 1. Les valeurs manquantes pour cette période de collecte spécifique seront marquées comme |
percentilesTimeseries |
Centiles utiles communs de la métrique. Le type de valeur des centiles sera le même que les types de valeurs indiqués pour les bins d'histogramme. Les valeurs manquantes pour cette période de collecte spécifique seront marquées comme |
fractionTimeseries |
Cet objet contient des séries temporelles de fractions étiquetées, qui totalisent environ 1 par entrée. Les fractions sont arrondies à quatre décimales. Les entrées manquantes sont exprimées sous la forme"NaN" dans toutes les fractions. |
Bin
Un bin est une partie distincte des données s'étendant 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 "ints". Par conséquent, ses classes de métriques utilisent 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'une chaîne encodée sous forme décimale. 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 |
"début" est le début du bin de données. |
end |
La fin est la fin de la classe de données. Si la valeur de fin n'est pas renseignée, alors le bin n'a pas de fin et est valide de début à +inf. |
densities |
Série temporelle de la proportion d'utilisateurs ayant constaté la valeur de ce bin pour la métrique donnée. La densité est arrondie à quatre décimales. |
Centiles
Percentiles contient les valeurs synthétiques d'une métrique à un centile statistique donné. Elles 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 |
Séries temporelles des valeurs pour lesquelles 75% des chargements de page ont enregistré une métrique donnée égale ou inférieure à cette valeur. |
Fractions
Fractions contient des séries temporelles de fractions étiquetées dont la somme totale est d'environ 1.
Chaque étiquette décrit un chargement de page d'une manière ou d'une autre. Par conséquent, les métriques représentées de cette manière peuvent être considérées comme produisant des valeurs distinctes au lieu de valeurs numériques, et les fractions expriment la fréquence de mesure d'une valeur distincte particulière.
{
"label_1": { "fractions": array[fraction]},
"label_1": { "fractions": array[fraction]},
...
"label_n": { "fractions": array[fraction]}
}
Comme pour les valeurs de densité dans les classes d'histogramme, chaque fraction est un nombre 0.0 <= value <= 1.0, dont la somme est d'environ 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 |
Séries temporelles des valeurs pour lesquelles 75% des chargements de page ont enregistré une métrique donnée égale ou inférieure à cette valeur. |
UrlNormalization
Objet représentant les actions de normalisation entreprises pour normaliser une URL afin d'augmenter les chances de réussite de la recherche. Il s'agit de modifications automatisées simples apportées lors de la recherche du url_pattern fourni. Les actions complexes telles que le suivi de redirections ne sont pas gérées.
{
"originalUrl": string,
"normalizedUrl": string
}
| Champs | |
|---|---|
originalUrl |
URL demandée d'origine avant toute action de normalisation. |
normalizedUrl |
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, à raison de 150 requêtes par minute et par projet Google Cloud pour l'une ou l'autre des API, ce qui est proposé sans frais. Vous pouvez consulter cette limite et votre utilisation actuelle dans la console Google Cloud. Ce quota généreux devrait être suffisant pour la grande majorité des cas d'utilisation et il n'est pas possible de payer un quota supplémentaire.