Interfejs CrUX History API

Data publikacji: 7 lutego 2023 r., ostatnia aktualizacja: 11 kwietnia 2025 r.

Interfejs CrUX History API zapewnia dostęp do historycznych danych o użytkownikach na poziomie strony i źródła z niskim opóźnieniem.

Wypróbuj

Typowy przypadek użycia

Interfejs CrUX History API umożliwia wysyłanie zapytań o historyczne dane o wygodzie użytkownika dotyczące konkretnego identyfikatora URI, np. „Uzyskaj historyczne trendy dotyczące wygody użytkownika dla źródła https://example.com”.

Interfejs History API ma tę samą strukturę co dzienny interfejs CrUX API, z tym wyjątkiem, że wartości są podawane w tablicy, a klucze mają nazwy w liczbie mnogiej (np. histogramTimeseries zamiast histogram lub p75s zamiast p75).

Klucz interfejsu API CrUX

Podobnie jak w przypadku interfejsu daily API, korzystanie z interfejsu CrUX History API wymaga klucza interfejsu Google Cloud API przeznaczonego do użytku w ramach Chrome UX Report API. Ten sam klucz można używać do interfejsu dziennego i historycznego.

Uzyskiwanie i używanie klucza interfejsu API

Możesz też utworzyć je na stronie Dane logowania.

Gdy uzyskasz klucz interfejsu API, Twoja aplikacja będzie mogła dołączać parametry zapytania key=yourAPIKey do adresów URL wszystkich żądań.

Klucz interfejsu API można bezpiecznie umieszczać w adresach URL, więc nie trzeba go kodować.

Zobacz przykładowe zapytania.

Model danych

Ta sekcja zawiera szczegółowe informacje o strukturze danych w prośbach i odpowiedziach.

Nagraj

Pojedyncza informacja o stronie lub witrynie. Rekord może zawierać dane dotyczące konkretnego identyfikatora i konkretnej kombinacji wymiarów. Rekord może zawierać dane dotyczące co najmniej 1 rodzaju danych.

Identyfikatory

Identyfikatory określają, jakie rekordy mają być wyszukiwane. W przypadku CrUX są to strony internetowe i witryny.

Punkt początkowy

Jeśli identyfikator to źródło, wszystkie dane na wszystkich stronach w tym źródle są agregowane. Załóżmy na przykład, że domen http://www.example.com dotyczyły strony o takim układzie w tej mapie witryny:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Oznacza to, że po przesłaniu zapytania do raportu na temat użytkowania Chrome z ustawionym źródłem http://www.example.com zwrócone zostaną dane o witrynach http://www.example.com/, http://www.example.com/foo.html i http://www.example.com/bar.html, które zostaną zgrupowane, ponieważ wszystkie te strony należą do tego źródła.

Adresy URL

Jeśli identyfikator to adres URL, zwrócone zostaną tylko dane dotyczące tego konkretnego adresu. Ponownie patrz na mapę witryny http://www.example.com źródłową:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Jeśli identyfikator ma wartość http://www.example.com/foo.html, zwracane są tylko dane o tej stronie.

Wymiary

Wymiary identyfikują konkretną grupę danych, na podstawie której rekord jest agregowany. Na przykład format PHONE wskazuje, że rekord zawiera informacje o wczytywaniu na urządzeniu mobilnym.

Format

Interfejs History API w ramach CrUX jest dostępny tylko w postaci zbiorczej według wymiaru Form Factor. Ogólna klasa urządzeń podzielona na PHONE, TABLET i DESKTOP.

Dane

Dane raportujemy w seryjnych zbiorach danych statystycznych, które są histogramami, percentylami i ułamkami.

Histogramy

Gdy dane są wyrażone w tablicy histogramu, każdy wpis w seryjnych danych czasowych reprezentuje odsetek załadowań strony, dla których dane mieszczą się w danym przedziale, proporcjonalnie do wszystkich. Punkty danych są prezentowane w kolejności odpowiadającej dacie okresu gromadzenia, która jest również zwracana przez interfejs API. Pierwszy punkt odpowiada najstarszemu okresowi, a ostatni – najmłodszemu okresowi gromadzenia.

Wygląd histogramu z 3 przedziałami dla przykładowych danych:

{
  "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]
    }
  ],
}

Te dane wskazują, że w przypadku 91,90% wczytań strony w pierwszym okresie zbierania danych w historii wartość przykładowych danych wahała się między 0 ms a 2500 ms, a potem 92,03%, 91,94%... Jednostki danych nie są zawarte w tym histogramie, więc w tym przypadku przyjmiemy milisekundy.

Dodatkowo w pierwszym okresie zbierania danych w historii w przypadku 5,21% wczytań strony wystąpiła wartość przykładowego wskaźnika w zakresie od 2500 ms do 4000 ms, a w tym samym okresie w przypadku 2,88% wczytań strony wystąpiła wartość większa niż 4000 ms.

Percentyle

Dane mogą też zawierać linie czasowe z wartościami percentylowymi, które mogą być przydatne do dodatkowych analiz.

Punkty danych są prezentowane w kolejności odpowiadającej dacie okresu gromadzenia, która jest również zwracana przez interfejs API. Pierwszy punkt odpowiada najstarszemu okresowi, a ostatni – najmłodszemu okresowi gromadzenia.

{
  "percentilesTimeseries": {
    "p75s": [1362, 1352, 1344, 1356, 1366, 1377]
  },
}

Te wartości mogą wskazywać konkretne wartości danych w danym percentylu. Są one oparte na pełnym zestawie dostępnych danych, a nie na ostatecznych danych zgrupowanych, więc niekoniecznie odpowiadają interpolowanemu percentylowi na podstawie ostatecznego histogramu zgrupowanego.

Ułamki

Dane mogą być wyrażane jako szeregi czasowe z oznaczonymi ułamkami. Każda etykieta opisuje wczytanie strony w określony sposób. Punkty danych są prezentowane w kolejności odpowiadającej dacie okresu gromadzenia, która jest również zwracana przez interfejs API. Pierwszy punkt odpowiada najstarszemu okresowi, a ostatni – najmłodszemu okresowi gromadzenia.

Przykład:

{    
  "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]}
  }
}

W tym przykładzie najnowszy punkt danych wskazuje, że 14,21% wczytań strony pochodziło z komputera, a 82,88% z telefonów.

Typy wartości danych

Interfejs CrUX History API używa tych samych typów wartości danych, więc więcej informacji znajdziesz w dokumentacji dotyczącej typów wartości danych w interfejsie CrUX API.

Kwalifikowanie się danych

Na podstawie kryteriów kwalifikacji pochodzenie lub adres URL mogą kwalifikować się tylko do niektórych okresów zbierania danych objętych interfejsem CrUX History API. W takich przypadkach interfejs CrUX History API zwróci wartość "NaN" dla gęstości histogramTimeseries i wartość null dla percentilesTimeseries w przypadku okresów zbierania danych, w których nie ma kwalifikujących się danych. Różnica polega na tym, że gęstości histogramu są zawsze liczbami, a procentyle mogą być liczbami lub ciągami znaków (CLS używa ciągów znaków, nawet jeśli wyglądają jak liczby).

Jeśli na przykład drugi okres nie zawierał żadnych odpowiednich danych, będzie wyglądać tak:

{
  "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]
  },
}

W przypadku adresów URL lub źródeł, które z czasem kwalifikują się do wyświetlania reklam, a potem tracą tę możliwość, możesz zauważyć wiele brakujących pozycji.

Okresy zbierania danych

Interfejs CrUX History API zawiera obiekt collectionPeriods z tablicą pól firstDate i endDate, który reprezentuje daty rozpoczęcia i zakończenia każdego okna agregacji. Na przykład:

    "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 }
      }
    ]

Okresy zbierania danych są uporządkowane rosnąco i reprezentują zakres dat każdego punktu danych w innych sekcjach odpowiedzi.

Interfejs History API jest aktualizowany co poniedziałek i zawiera dane do poprzedniej soboty (z standardowym opóźnieniem 2 dni). Zawiera on dane z poprzednich 40 tygodni – po jednym okresie zbierania danych na tydzień. Domyślnie zwracane są 25 okresów zbierania danych. Możesz to zmienić, ustawiając w prośbie parametr "collectionPeriodCount" na liczbę z zakresu od 1 do 40.

Każdy okres zbierania danych zawiera dane zagregowane z poprzednich 28 dni, a okresy zbierania danych są tygodniowe, co oznacza, że okresy zbierania danych będą się na siebie nakładać. Są one podobne do średniej ruchomej, ponieważ każdy kolejny okres zawiera dane z 3 tygodni, a jeden tydzień jest inny.

Przykładowe zapytania

Zapytania są przesyłane jako obiekty JSON za pomocą żądania POST do adresu https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]", a dane zapytania są przesyłane jako obiekt JSON w treści żądania POST.

Zwróć uwagę, że w tym przykładzie queryHistoryRecord zastępuje queryRecord w interfejsie dziennego interfejsu CrUX API.

Przykładowa treść:

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Można go na przykład wywołać z poziomu curl za pomocą tego wiersza poleceń (zastąp API_KEY swoim kluczem):

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"]}'

Dane na poziomie strony są dostępne przez interfejs API, jeśli w zapytaniu podasz usługę url zamiast origin:

{
  "url": "https://example.com/page",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Jeśli właściwość metrics nie jest ustawiona, zwracane są wszystkie dostępne dane:

• cumulative_layout_shift
• first_contentful_paint
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• form_factors (zwracane tylko wtedy, gdy w żądaniu nie określono parametru formFactor)

Jeśli nie podasz wartości formFactor, wartości zostaną zsumowane dla wszystkich formatów.

Więcej przykładowych zapytań znajdziesz w przewodniku Korzystanie z interfejsu History API w pliku CrUX.

Potok danych

Zbiór danych CrUX jest przetwarzany w ramach potoku, aby skonsolidować, zagregować i odfiltrować dane, zanim staną się dostępne przez interfejs API.

Średnia krocząca

Dane w raporcie na temat użytkowania Chrome to średnia krocząca z 28 dni obejmująca zagregowane dane. Oznacza to, że dane prezentowane w raporcie na temat użytkowania Chrome w danym momencie to w istocie dane z ostatnich 28 dni zebrane w jedną całość.

History API zawiera kilka okresów zbierania danych, z których każdy obejmuje 28 dni. Każdy okres zbierania danych zawiera dane zagregowane z poprzednich 28 dni, a okresy zbierania danych są tygodniowe, co oznacza, że okresy zbierania danych będą się na siebie nakładać. Są one podobne do średniej ruchomej, ponieważ każdy kolejny okres zawiera dane z 3 tygodni, a jeden tydzień jest inny.

Aktualizacje co tydzień

History API jest aktualizowane co poniedziałek około godziny 4:00 UTC i zawiera dane do poprzedniej soboty (z standardowym 2-dniowym opóźnieniem). Zawiera dane z 40 poprzednich tygodni (ok. 10 miesięcy), po jednym okresie zbierania danych na tydzień. Pamiętaj, że domyślnie zwracamy 25 rekordów na serię czasową, ale możesz zmienić tę wartość, podając parametr collectionPeriodCount.

Czas aktualizacji nie jest objęty gwarancją jakości usług. Aktualizacja jest wykonywana codziennie w miarę możliwości.

Schemat

Interfejs CrUX History API ma 1 punkt końcowy, który akceptuje POST żądania HTTP. Interfejs API zwraca record, który zawiera co najmniej 1 element metrics odpowiadający danym o skuteczności dotyczącym żądanego źródła lub strony.

Żądanie HTTP

POST https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord

Adres URL używa składni transkodowania gRPC.

Treść żądania

Interfejs CrUX History API używa podobnych treści żądania co interfejs CrUX API, ale z 1 dodatkowym opcjonalnym polem "collectionPeriodCount":

{
  "formFactor": enum (FormFactor),
  "metrics": [
    string
  ],

  // 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.

  "collectionPeriodCount": int32 // Optional: Number of periods to collect
}

Aby na przykład uzyskać wartości największego wyrenderowania treści na komputerze dla strony głównej web.dev:

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

To podobne żądanie zawiera opcjonalne pole collectionPeriodCount i zawiera 40 rekordów serii czasowych, które dostarczają około 10 miesięcy historii wydajności witryny dla domeny https://web.dev:

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ],
  "collectionPeriodCount": 40
}

Treść odpowiedzi

Pomyślne żądania zwracają odpowiedzi z obiektem record i urlNormalizationDetails o tej strukturze:

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

Odpowiedź na treść poprzedniego zapytania może wyglądać na przykład tak:

{
  "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 }
      }, {
        ...
      }
    ]
  }
}

Klucz

Key definiuje wszystkie wymiary, które wskazują, że rekord jest unikalny.

{
  "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.
}

Dane

metric to zestaw danych o wygodzie korzystania z pojedynczego wskaźnika wydajności strony internetowej, np. pierwszego wyrenderowania treści. Zawiera on podsumowanie w postaci histogramu rzeczywistego użytkowania Chrome jako serii bins.

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

lub

"fractionTimeseries": {
  object (Fractions)
}

Przedział

bin to dyskretna część danych obejmująca zakres od początku do końca lub, jeśli nie podano końca, od początku do dodatniej nieskończoności.

Wartości początkowa i końcowa przedziału są podawane w typie wartości danych, które reprezentują. Na przykład pierwsze wyrenderowanie treści jest mierzone w milisekundach i wyświetlane jako liczba całkowita, dlatego jego zakresy danych będą używać typu int32 dla typów początku i końca. Jednak skumulowane przesunięcie układu jest mierzone w bezwymiarowych liczbach dziesiętnych i wyświetlane jako liczba dziesiętna zakodowana jako ciąg znaków, dlatego jego zakresy danych będą używać ciągów znaków jako typu wartości.

{
  "start": value,
  "end": value,
  "densities": [number, number, number...etc.]
}

Percentyle

Percentiles zawiera wartości syntetyczne danych przy danym percentylu statystycznym. Są one używane do oszacowania wartości danych jako odsetek łącznej liczby użytkowników.

{
  "P75": value
}

Ułamki

Fractions zawiera szeregi czasowe z oznaczonymi ułamkami, których suma na każdy wpis wynosi około 1. Każda etykieta w jakiś sposób opisuje wczytanie strony, więc dane reprezentowane w ten sposób można traktować jako wartości jednoznaczne zamiast liczbowe, a ułamki wskazują, jak często była mierzona dana wartość jednoznaczna.

{
  "label_1": { "fractions": array[fraction]},
  "label_1": { "fractions": array[fraction]},
  ...
  "label_n": { "fractions": array[fraction]}
}

Podobnie jak wartości gęstości w przedziałach histogramu, każda wartość fraction jest liczbą 0.0 <= value <= 1.0, a ich suma wynosi około 1,0. Jeśli dane są niedostępne w przypadku konkretnego okresu zbierania danych, odpowiedni wpis będzie miał wartość „NaN” we wszystkich tablicach ułamków.

UrlNormalization

Obiekt reprezentujący działania normalizacyjne podjęte w celu ujednoliwienia adresu URL, aby zwiększyć szansę na znalezienie go. Są to podstawowe, automatyczne zmiany, które są wprowadzane, gdy wiadomo, że wyszukiwanie podanych danych url_pattern zakończy się niepowodzeniem. Złożone działania, takie jak śledzenie przekierowań, nie są obsługiwane.

{
  "originalUrl": string,
  "normalizedUrl": string
}

Ograniczenia liczby żądań

Interfejs CrUX History API ma ten sam limit co interfejs Crux API, czyli 150 zapytań na minutę na projekt Google Cloud. Oba interfejsy są dostępne bezpłatnie. Ten limit i obecne wykorzystanie możesz sprawdzić w konsoli Google Cloud. Ten obszerny limit powinien wystarczyć w większości przypadków. Nie można płacić za zwiększenie limitu.