Publié le 7 février 2023, dernière mise à jour le 11 avril 2025
Ce guide présente le point de terminaison de l'API History du rapport Chrome sur l'expérience utilisateur (CrUX), qui fournit des séries temporelles de données sur les performances Web. Ces données sont actualisées chaque semaine et vous permettent de consulter l'historique sur environ six mois, avec 40 points de données espacés d'une semaine.
Lorsqu'elle est utilisée avec les mises à jour quotidiennes du point de terminaison de l'API CrUX d'origine, vous pouvez désormais voir rapidement les données les plus récentes et ce qui s'est passé auparavant. Il s'agit donc d'un outil puissant pour observer les modifications apportées aux pages Web au fil du temps.
Essayer l'API sur cette page
Interroger l'API CrUX quotidienne
Pour récapituler un article précédent sur l'API CrUX, vous pouvez obtenir un instantané des données de champ pour une origine spécifique de la manière suivante :
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" --header 'Content-Type: application/json' --data '{"origin": "https://web.dev"}'
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [{
"start": 0, "end": 2500, "density": 0.9192
}, {
"start": 2500, "end": 4000, "density": 0.0513
}, {
"start": 4000, "density": 0.0294
}],
"percentiles": {
"p75": 1303
}
}
// ...
},
"collectionPeriod": {
"firstDate": { "year": 2022, "month": 12, "day": 27 },
"lastDate": { "year": 2023, "month": 1, "day": 23 }
}
}
}
Cet instantané inclut les valeurs de densité de l'histogramme et les valeurs de centiles pour une période de collecte de 28 jours spécifique, en l'occurrence du 27 décembre 2022 au 23 janvier 2023.
Interroger l'API CrUX History
Pour appeler le point de terminaison de l'historique, remplacez queryRecord par queryHistoryRecord dans la commande curl de l'URL. Vous pouvez utiliser la même clé API CrUX que pour l'appel précédent.
collectionPeriodCount spécifie le nombre d'entrées de série temporelle à renvoyer (40 maximum). Si aucune valeur n'est spécifiée, la valeur par défaut est 25.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"origin": "https://web.dev", "collectionPeriodCount": 40}'
La forme générale d'une réponse est similaire, mais elle contient beaucoup plus de données. Au lieu d'un seul point de données, il existe désormais des séries temporelles pour les champs contenant les valeurs du 75e centile (p75) et de la densité de l'histogramme.
{
"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 }
}
]
}
}
Dans cet exemple, la série temporelle densities pour le bucket de 0 à 2 500 ms de la métrique Largest Contentful Paint (LCP) est [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].. Chacune de ces densités a été observée lors de l'entrée collectionPeriods correspondante. Par exemple, la cinquième densité (0,9183) correspondait à la cinquième période de collecte, qui s'est terminée le 3 septembre 2022, et 0,9187 correspondait à la densité de la période se terminant la semaine suivante.
En d'autres termes, en interprétant les dernières entrées de série temporelle de l'exemple pour https://web.dev, il a été constaté que, du 14 août 2022 au 10 septembre 2022, 91,87 % des chargements de page avaient des valeurs LCP inférieures à 2 500 ms, 5,27 % avaient des valeurs comprises entre 2 500 ms et 4 000 ms, et 2,85 % avaient des valeurs supérieures à 4 000 ms.
De même, il existe une série temporelle pour les valeurs p75 : la valeur LCP p75 du 14 août 2022 au 10 septembre 2022 était de 1377. Cela signifie que, pour cette période de collecte, 75 % des expériences utilisateur ont enregistré un LCP inférieur à 1 377 ms, et 25 % des expériences utilisateur ont enregistré un LCP supérieur à 1 377 ms.
Bien que l'exemple ne liste que six entrées de séries temporelles et périodes de collecte, les réponses de l'API fournissent 25 entrées de séries temporelles par défaut et 40 au maximum lorsque "collectionPeriodCount": 40 est spécifié dans la requête. Comme les dates de fin de chacune de ces périodes de collecte sont des samedis espacés de sept jours, "collectionPeriodCount": 40 couvre 10 mois.
Dans une réponse donnée, la longueur de la série temporelle pour les densités des bins de l'histogramme et pour les valeurs p75 sera exactement la même que la longueur du tableau dans le champ collectionPeriods : il existe une correspondance un-à-un basée sur l'index dans ces tableaux.
Interroger les données au niveau de la page
En plus des données au niveau de l'origine, l'API CrUX History permet d'accéder aux données historiques au niveau de la page. Alors que les données au niveau de l'origine étaient auparavant disponibles à l'aide de l'ensemble de données CrUX sur BigQuery, les données historiques au niveau de la page n'étaient disponibles que si les sites les collectaient et les stockaient eux-mêmes. La nouvelle API permet désormais d'accéder à ces données historiques au niveau des pages.
Les données au niveau de la page peuvent être interrogées de la même manière, mais en utilisant url au lieu de origin dans la charge utile :
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/blog/"}'
Les données historiques au niveau de la page (et de l'origine) sont soumises aux mêmes critères d'éligibilité que le reste de CrUX. Il est donc possible que les pages, en particulier, ne disposent pas d'un historique complet. Dans ce cas, les données "manquantes" seront représentées par "NaN" pour les densités histogramTimeseries et par null pour les percentilesTimeseries. Cette différence s'explique par le fait que les densités d'histogramme sont toujours des nombres, tandis que les centiles peuvent être des nombres ou des chaînes (la CLS utilise des chaînes, même si elles ressemblent à des nombres).
Visualiser les données
Le moyen le plus simple de visualiser les données est d'utiliser CrUX Vis, un outil spécialement conçu pour démontrer la puissance de l'API CrUX History. Pour en savoir plus, consultez la documentation CrUX Vis.
Pour générer vous-même des graphiques similaires, nous avons créé un Colab à titre d'exemple. Colab (ou "Colaboratory") vous permet d'écrire et d'exécuter du code Python dans votre navigateur. Le notebook Colab de l'API CrUX History (source) utilise Python pour effectuer des appels à l'API et représenter les données sous forme de graphique.
Ce Colab vous permet de créer des graphiques p75 et tri-bin, d'obtenir des données sous forme de tableau et de voir la paire requête/réponse pour l'API CrUX en remplissant un bref formulaire. Vous n'avez pas besoin d'être programmeur pour utiliser cet outil, mais vous pouvez bien sûr consulter le code Python et le modifier pour créer quelque chose d'extraordinaire. N'hésitez pas à nous faire part de vos commentaires sur ce que vous trouvez !
Bien sûr, vous n'êtes pas limité à Colab ou à Python. Il s'agit simplement d'un exemple d'utilisation de cette nouvelle API. Comme il s'agit d'un point de terminaison HTTP basé sur JSON, l'API peut être interrogée à partir de n'importe quelle technologie.
Conclusion
Avant l'introduction du point de terminaison de l'API CrUX History, les propriétaires de sites étaient limités dans les informations historiques qu'ils pouvaient obtenir de CrUX. Des données mensuelles au niveau de l'origine étaient disponibles dans BigQuery, mais pas les données hebdomadaires ni les données historiques au niveau de la page. Les propriétaires de sites pouvaient enregistrer eux-mêmes ces données à l'aide de l'API quotidienne, mais souvent, ce besoin n'était découvert qu'après une régression des métriques.
L'objectif de cette API CrUX History est de permettre aux propriétaires de sites de mieux comprendre l'évolution des métriques de leur site et de l'utiliser comme outil de diagnostic en cas de problème. Si vous utilisez la nouvelle API, n'hésitez pas à nous faire part de vos commentaires dans le groupe Google Chrome UX Report (Discussions).
Remerciements
Image principale de Dave Herring sur Unsplash