Opublikowano: 7 lutego 2023 r., ostatnia aktualizacja: 11 kwietnia 2025 r.
W tym przewodniku przedstawiamy punkt końcowy CrUX History API, który udostępnia szeregi czasowe danych o wydajności stron internetowych. Dane te są aktualizowane co tydzień i pozwalają wyświetlać historię z ostatnich 6 miesięcy z 40 punktami danych rozłożonymi w odstępach tygodniowych.
W połączeniu z codziennymi aktualizacjami z oryginalnego punktu końcowego CrUX API możesz teraz szybko zobaczyć zarówno najnowsze dane, jak i to, co wydarzyło się wcześniej. Dzięki temu jest to potężne narzędzie do śledzenia zmian na stronach internetowych w czasie.
Wypróbuj interfejs API na tej stronie
Wysyłanie zapytań do codziennego interfejsu CrUX API
Jak wspomnieliśmy w poprzednim artykule o CrUX API, możesz w ten sposób uzyskać migawkę danych z pola dla konkretnej domeny:
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 }
}
}
}
Ta migawka zawiera wartości gęstości histogramu i wartości percentyli dla konkretnego 28-dniowego okresu zbierania danych, w tym przypadku od 27 grudnia 2022 r. do 23 stycznia 2023 r.
Wysyłanie zapytań do CrUX History API
Aby wywołać punkt końcowy historii, zmień queryRecord w adresie URL na queryHistoryRecord w poleceniu curl. Możesz użyć tego samego
klucza CrUX API co w poprzednim wywołaniu.
collectionPeriodCount określa liczbę wpisów szeregów czasowych do zwrócenia. Maksymalna wartość to 40. Jeśli nie podasz żadnej wartości, domyślnie zostanie użyta wartość 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}'
Ogólny kształt odpowiedzi jest podobny, ale zawiera ona znacznie więcej danych. Zamiast pojedynczego punktu danych są teraz szeregi czasowe dla pól zawierających 75 percentyl (p75) i wartości gęstości histogramu.
{
"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 }
}
]
}
}
W tym przykładzie szereg czasowy densities dla przedziału od 0 do 2500 ms wskaźnika
największego wyrenderowania treści (LCP) to
[0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. Każda z tych gęstości została
zaobserwowana w odpowiednim wpisie collectionPeriods. Na przykład piąta gęstość, 0, 9183, była gęstością w piątym okresie zbierania danych, który zakończył się 3 września 2022 r., a 0, 9187 była gęstością w okresie kończącym się tydzień później.
Innymi słowy, interpretując ostatnie wpisy szeregów czasowych w przykładzie dla web.dev, stwierdzono, że od 14 sierpnia 2022 r. do 10 września 2022 r. 91,87% wczytań stron miało wartości LCP mniejsze niż 2500 ms, 5,27% miało wartości między 2500 ms a 4000 ms, a 2,85% miało wartości większe niż 4000 ms.
Podobnie istnieje szereg czasowy dla wartości p75: LCP p75 od 14 sierpnia 2022 r. do 10 września 2022 r. wynosił 1377. Oznacza to, że w tym okresie zbierania danych 75% doświadczeń użytkowników miało LCP mniejsze niż 1377 ms, a 25% doświadczeń użytkowników miało LCP większe niż 1377 ms.
Chociaż przykład zawiera tylko 6 wpisów szeregów czasowych i okresów zbierania danych,
odpowiedzi z interfejsu API domyślnie zawierają 25 wpisów szeregów czasowych, a maksymalnie
40 – gdy w żądaniu określono "collectionPeriodCount": 40. Ponieważ daty zakończenia każdego z tych okresów zbierania danych to soboty, które są oddalone od siebie o 7 dni, przy "collectionPeriodCount": 40 obejmuje to 10 miesięcy.
W każdej odpowiedzi długość szeregów czasowych dla gęstości przedziałów histogramu i dla wartości p75 będzie dokładnie taka sama jak długość tablicy w polu collectionPeriods: istnieje korespondencja jeden do jednego na podstawie indeksu w tych tablicach.
Wysyłanie zapytań o dane na poziomie strony
Oprócz danych na poziomie domeny CrUX History API umożliwia dostęp do danych historycznych na poziomie strony. Dane na poziomie domeny były wcześniej dostępne w zbiorze danych CrUX w BigQuery, ale dane historyczne na poziomie strony były dostępne tylko wtedy, gdy witryny samodzielnie zbierały i przechowywały te dane. Nowy interfejs API odblokowuje teraz te dane historyczne na poziomie strony.
Dane na poziomie strony można wysyłać w ten sam sposób, ale w ładunku użyj url zamiast origin:
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/"}'
Dane historyczne na poziomie strony (i domeny) podlegają
tym samym wymaganiom kwalifikacyjnym co pozostałe
dane CrUX, dlatego strony mogą nie mieć pełnej historii. W takich przypadkach „brakujące” dane będą reprezentowane przez "NaN" w przypadku
histogramTimeseries gęstości i null w przypadku percentilesTimeseries. Powodem tej różnicy jest to, że gęstości histogramu są zawsze liczbami, a percentyle mogą być liczbami lub ciągami znaków (CLS używa ciągów znaków, nawet jeśli wyglądają jak liczby).
Wizualizuj dane
Najłatwiejszym sposobem wizualizacji danych jest CrUX Vis – narzędzie stworzone specjalnie w celu zademonstrowania możliwości CrUX History API. Więcej informacji znajdziesz w dokumentacji CrUX Vis.
Aby samodzielnie wygenerować podobne wykresy, utworzyliśmy przykładowy Colab. Colab, czyli „Colaboratory”, umożliwia pisanie i wykonywanie kodu w języku Python bezpośrednio w przeglądarce. Colab CrUX History API (źródło) używa Pythona do wywoływania interfejsu API i tworzenia wykresów danych.
Ten Colab umożliwia tworzenie wykresów p75, wykresów trójprzedziałowych, pobieranie danych w postaci tabelarycznej oraz wyświetlanie pary żądanie-odpowiedź dla CrUX API przez wypełnienie krótkiego formularza. Nie musisz być programistą, aby z niego korzystać, ale możesz przejrzeć kod w Pythonie i zmodyfikować go w coś niesamowitego.
To tylko jeden przykład użycia tego nowego interfejsu API. Jako punkt końcowy HTTP oparty na JSON interfejs API może być wysyłany z dowolnej technologii.
Podsumowanie
Przed wprowadzeniem punktu końcowego CrUX History API właściciele witryn mieli ograniczone możliwości uzyskiwania informacji historycznych z CrUX. Dane miesięczne na poziomie domeny były dostępne w BigQuery, ale dane tygodniowe i dane historyczne na poziomie strony nie były dostępne. Właściciele witryn mogli samodzielnie rejestrować te dane za pomocą codziennego interfejsu API, ale często potrzeba tego była odkrywana dopiero po regresji wskaźników.
Mamy nadzieję, że wprowadzenie tego CrUX History API pozwoli właścicielom witryn lepiej zrozumieć zmieniające się wskaźniki witryny i będzie służyć jako narzędzie diagnostyczne w przypadku wystąpienia problemów. Jeśli używasz nowego interfejsu API, możesz przesłać opinię w grupie dyskusyjnej Raport na temat użytkowania Chrome (Discussions).