L'API CrUX History offre un accès avec une 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 sur l'expérience utilisateur pour un URI spécifique, par exemple "Obtenir les tendances de l'expérience utilisateur historiques pour l'origine https://example.com".
L'API History suit la même structure que l'API CrUX quotidienne, sauf que les valeurs sont fournies dans un tableau et que les clés portent 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 qu'il puisse être utilisé 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 des 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.
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.
Provenance
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 lequel 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.
L'API CrUX History n'est disponible que pour les données agrégées par facteur de forme. Il s'agit d'une classe générale d'appareils divisé en PHONE, TABLET et DESKTOP.
Métrique
Les métriques sont présentées sous forme de séries temporelles d'agrégations statistiques, qui sont 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 a accédé à un intervalle, proportionnellement à l'ensemble des chargements de page. 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.
Pour un exemple de métrique, un histogramme simple à trois bins 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 page ont subi une valeur de métrique 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%... Les unités de la métrique ne sont pas contenues dans cet histogramme. Dans ce cas, nous partons du principe que les millisecondes sont utilisées.
En outre, 5,21% des chargements de page ont enregistré une valeur de métrique 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 des analyses supplémentaires.
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 indiquer des valeurs de métriques spécifiques pour un centile donné. Elles sont basées sur l'ensemble complet de données disponibles et non sur les données binaires finales. Par conséquent, elles 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 page ont été effectués sur des ordinateurs de bureau et 82,88% 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
D'après les critères d'éligibilité, une origine ou une URL ne peut être é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 percentilesTimeseries pour les périodes de collecte pour lesquelles aucune donnée n'est é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 (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 résultat sera 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 ou qui ne le sont plus 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. 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 (selon le délai standard de deux jours). Elle contient les données des 25 semaines précédentes, soit une période de collecte par semaine.
É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 par semaine, les périodes de collecte se chevauchent. Elles sont semblables à 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 à l'aide d'une requête POST envoyée à https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]". Le corps de la requête POST comporte les données de requête sous la forme d'un objet JSON.
Notez l'utilisation de queryHistoryRecord pour remplacer le 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 à 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"]}'
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_shiftfirst_contentful_paintfirst_input_delayinteraction_to_next_paintlargest_contentful_paintexperimental_time_to_first_bytenavigation_typesround_trip_timeform_factors(indiqué 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.
Pour découvrir d'autres exemples de requêtes, consultez le guide Utiliser l'API CrUX History.
Pipeline de données
L'ensemble de données CrUX est traité par un pipeline afin de consolider, d'agréger et de 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 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.
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 par semaine, les périodes de collecte se chevauchent. Elles sont semblables à 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 collectées jusqu'au samedi précédent (selon le délai standard de deux jours). Elle contient les données des 25 semaines précédentes (environ 6 mois), soit une période de collecte par semaine.
Il n'existe pas de contrat de niveau de service pour les heures de mise à jour. L'opération s'effectue de la manière 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 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: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, à l'exception de la prise en charge du champ de requête effectiveConnectionType.
Par exemple, pour demander les valeurs Largest Contentful Paint pour la page d'accueil web.dev sur ordinateur:
{
"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 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": {
"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 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. |
Champ d'union url_. Le format d'URL correspond à l'URL à laquelle s'applique l'enregistrement. url_ ne peut être qu'un des éléments suivants : |
|
origin |
L'origine indique l'origine à laquelle est destiné cet enregistrement. Remarque: Lorsque vous spécifiez une origine, 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 |
Remarque: Lorsque vous spécifiez une |
Métriques
Un metric est un ensemble de données sur l'expérience utilisateur correspondant à 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 de bins.
{
"histogramTimeseries": [
{
object (Bin)
}
],
"percentilesTimeseries": {
object (Percentiles)
}
}
ou
"fractionTimeseries": {
object (Fractions)
}
| Champs | |
|---|---|
histogramTimeseries[] |
Histogramme de séries temporelles 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'additionnent pour atteindre environ 1. Les valeurs manquantes pour cette période de collecte particulière seront marquées comme |
percentilesTimeseries |
Centiles utiles courants de la métrique. Le type de valeur pour les centiles est identique à celui fourni pour les bins d'histogramme. Les valeurs manquantes pour cette période de collecte particulière seront marquées comme |
fractionTimeseries |
Cet objet contient des séries temporelles de fractions étiquetées, qui s'ajoutent à ~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
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 décimales 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,
"densities": [number, number, number...etc.]
}
| Champs | |
|---|---|
start |
"Start" correspond au début du bin de données. |
end |
"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. |
densities |
Une série temporelle représentant la proportion d'utilisateurs ayant constaté la valeur de ce bin 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 | |
|---|---|
p75s |
Séries temporelles des valeurs pour lesquelles 75% des chargements de page ont connu une valeur égale ou inférieure à cette valeur pour la métrique donnée. |
Fractions
Fractions contient des séries temporelles de fractions étiquetées dont la somme est égale à ~1 par entrée.
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 plutôt que des valeurs numériques, et les fractions indiquent la fréquence à laquelle une valeur distincte spécifique 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 bins d'histogramme, chaque fraction est un nombre 0.0 <= value <= 1.0, dont la somme est égale à ~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 connu une valeur égale ou inférieure à cette valeur pour la métrique donnée. |
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 |
URL demandée à l'origine avant toute action de normalisation |
normalizedUrl |
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 History partage la même limite que l'API CrUX, à raison de 150 requêtes par minute et par projet Google Cloud pour les deux API, ce qui est sans frais 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.