Interfejs CrUX History API

Interfejs CrUX History API zapewnia z małym opóźnieniem dostęp do historycznych danych o wrażeniach użytkowników z 6 miesięcy na poziomie szczegółowości strony i źródła.

Typowe zastosowanie

Interfejs CrUX History API umożliwia wysyłanie zapytań o historyczne dane o wrażeniach użytkowników związanych z określonym identyfikatorem URI, np. „Pobierz historyczne trendy UX dla źródła https://example.com”.

Interfejs History API ma taką samą strukturę jak codzienny interfejs API CrUX, z wyjątkiem wartości podanych w tablicy, a klucze mają nazwy w liczbie mnogiej (na przykład histogramTimeseries zamiast histogram lub p75s zamiast p75).

Klucz interfejsu API CrUX

Podobnie jak w przypadku codziennego interfejsu API, używanie interfejsu CrUX History API wymaga klucza interfejsu Google Cloud API. Tego samego klucza można używać w interfejsach API Daily i History.

Możesz je utworzyć na stronie Dane logowania i udostępnić je na potrzeby Chrome UX Report API.

Gdy uzyskasz klucz interfejsu API, Twoja aplikacja może dołączać parametr zapytania key=[YOUR_API_KEY] do wszystkich adresów URL żądań. Zobacz Przykładowe zapytania.

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

Model danych

Ta sekcja zawiera szczegółowe informacje o strukturze danych w żądaniach i odpowiedziach.

Rekord

Wyjątkowa informacja o stronie lub witrynie. Rekord może zawierać dane specyficzne dla identyfikatora i konkretnej kombinacji wymiarów. Rekord może zawierać informacje dotyczące jednego lub wielu wskaźników.

Identyfikatory

Identyfikatory określają, jakie rekordy należy przeszukać. W CrUX identyfikatory te to strony internetowe i witryny.

Punkt początkowy

Jeśli identyfikatorem jest pochodzenie, wszystkie dane dotyczące wszystkich stron w tym źródle są łączone razem. Załóżmy na przykład, że w źródle http://www.example.com znajdowały się strony wymienione w tej mapie witryny:

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

Oznacza to, że podczas wysyłania zapytania do Raportu na temat użytkowania Chrome, którego źródło jest ustawione na http://www.example.com, zwracane będą dane zagregowane w celach http://www.example.com/, http://www.example.com/foo.html i http://www.example.com/bar.html, ponieważ wszystkie te strony należą do tego źródła.

Adresy URL

Jeśli identyfikatorem jest adres URL, zwracane są tylko dane dotyczące tego konkretnego adresu URL. Jeszcze raz przeanalizujemy mapę witryny http://www.example.com:

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

Jeśli identyfikator jest ustawiony na URL z wartością http://www.example.com/foo.html, zwracane będą tylko dane dotyczące tej strony.

Wymiary

Wymiary identyfikują konkretną grupę danych, na podstawie których agregujemy rekord. Na przykład format PHONE oznacza, że rekord zawiera informacje o załadowaniach, które miały miejsce na urządzeniu mobilnym.

Interfejs CrUX History API jest dostępny tylko agregowany według wymiaru formatu. To jest ogólna klasa urządzeń podzielona na PHONE, TABLET i DESKTOP.

Wskaźnik

Udostępniamy dane w ciągach czasowych agregacji statystycznych, którymi są histogramy, percentyle i ułamki.

Histogramy

Jeśli wskaźniki są wyrażone w tablicy histogramu, każdy wpis ciągu czasowego reprezentuje procent wczytań strony, w przypadku których dane znalazły się w przedziale, proporcjonalnie do wszystkich. Punkty danych są wyświetlane w kolejności dat z okresu zbierania również zwróconych przez interfejs API. Pierwszy punkt to okres najwcześniejszy, a końcowy – ostatni.

Prosty histogram binarny przykładowych danych wygląda tak:

{
  "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 pierwszym okresie gromadzenia danych w historii w 91,90% przypadków wczytania strony wystąpiła przykładowa wartość z zakresu od 0 ms do 2500 ms, a potem kolejne 92,03%, 91,94%... Jednostki metryczne nie są ujęte na tym histogramie, w tym przypadku przyjmujemy milisekundy.

Dodatkowo w pierwszym okresie gromadzenia danych w przypadku 5,21% przypadków wczytania stron przykładowa wartość danych wynosi od 2500 ms do 4000 ms, a w pierwszym okresie gromadzenia danych w przypadku 2,88% przypadków wczytania stron ta wartość była większa niż 4000 ms.

Centyle

Wskaźniki mogą też zawierać ciągi czasowe centylów, które mogą być przydatne na potrzeby dodatkowej analizy.

Punkty danych są wyświetlane w kolejności dat z okresu zbierania również zwróconych przez interfejs API. Pierwszy punkt to okres najwcześniejszy, a końcowy – ostatni.

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

Te percentyle mogą pokazywać określone wartości danych przy danym percentylu dla tych danych. Opierają się one na pełnym zbiorze dostępnych danych, a nie na ostatecznych zakresach danych, więc niekoniecznie muszą odpowiadać interpolowanemu percentylu opartemu na końcowym histogramie binarnym.

Ułamki

Dane mogą być wyrażone jako ciągi czasowe oznaczonych ułamkami. Każda etykieta opisuje wczytywanie strony w określony sposób. Punkty danych są wyświetlane w kolejności dat z okresu zbierania również zwróconych przez interfejs API. Pierwszy punkt to okres najwcześniejszy, a końcowy – ostatni.

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ń stron pochodzi z komputerów, 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 codziennej dokumentacji typów wartości danych interfejsu CrUX API.

Dostępność danych

W zależności od kryteriów kwalifikacji źródło 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 null w przypadku percentilesTimeseries dla okresów zbierania danych, dla których nie ma odpowiednich danych. Przyczyną różnic jest to, że histogram ma zawsze wartości liczbowe, natomiast percentyle mogą mieć postać liczb lub ciągów (CLS używa ciągów tekstowych, nawet jeśli wyglądają jak liczby).

Jeśli na przykład w drugim okresie nie ma żadnych odpowiednich danych, będzie to 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 stają się niedostępne lub stają się niedostępne, możesz zauważyć, że brakuje wielu pozycji.

Okresy zbierania danych

Interfejs CrUX History API zawiera obiekt collectionPeriods z tablicą pól firstDate i endDate, które reprezentują 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ą w kolejności rosnącej i reprezentują zakres dat każdego z punktów danych w pozostałych sekcjach odpowiedzi.

Interfejs History API jest aktualizowany w każdy poniedziałek i zawiera dane do poprzedniej soboty (zgodnie ze standardowym 2-dniowym opóźnieniem). Obejmuje dane z ostatnich 25 tygodni – jeden okres gromadzenia danych tygodniowo.

Każdy okres zbierania danych obejmuje dane zbiorcze z poprzednich 28 dni, a okresy gromadzenia danych są podzielone na tygodnie, co oznacza, że okresy ich zbierania będą się pokrywać. Są one podobne do średniej kroczącej danych: w każdym kolejnym okresie uwzględniane są dane z 3 tygodni, a jeden tydzień jest inny.

Przykładowe zapytania

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

Uwaga: funkcja queryHistoryRecord zastępuje queryRecord codziennego interfejsu API CrUX.

Przykładowy tekst:

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

Na przykład można ją wywołać ze strony curl za pomocą następującego wiersza poleceń (zastępując API_KEY 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 dzięki przekazaniu w zapytaniu właściwości 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 skonfigurowana, zwracane będą wszystkie dostępne dane:

  • cumulative_layout_shift
  • first_contentful_paint
  • first_input_delay
  • interaction_to_next_paint
  • largest_contentful_paint
  • experimental_time_to_first_byte
  • navigation_types
  • form_factors (raportowany tylko wtedy, gdy w żądaniu nie określono żadnego formFactor)

Jeśli nie podasz żadnej wartości formFactor, wartości zostaną zebrane ze wszystkich formatów.

Więcej przykładowych zapytań znajdziesz w przewodniku po interfejsie CrUX History API.

Potok danych

Zbiór danych raportu CrUX jest przetwarzany za pomocą potoku w celu konsolidacji, agregacji i filtrowania danych przed udostępnieniem ich przez interfejs API.

Średnia krocząca

Dane w Raporcie na temat użytkowania Chrome to średnia krocząca danych zbiorczych z 28 dni. Oznacza to, że dane przedstawione w danym momencie w Raporcie na temat użytkowania Chrome to tak naprawdę dane z ostatnich 28 dni zebrane.

Interfejs History API zawiera kilka okresów gromadzenia danych obejmujących te 28 dni. Każdy okres zbierania danych obejmuje dane zbiorcze z poprzednich 28 dni, a okresy gromadzenia danych są podzielone na tygodnie, co oznacza, że okresy ich zbierania będą się pokrywać. Są one podobne do średniej kroczącej danych: w każdym kolejnym okresie uwzględniane są dane z 3 tygodni, a jeden tydzień jest inny.

Cotygodniowe aktualizacje

Interfejs History API jest aktualizowany w każdy poniedziałek około 04:00 czasu UTC i zawiera dane aż do poprzedniej soboty (zgodnie ze standardowym 2-dniowym opóźnieniem). Zawiera dane z poprzednich 25 tygodni (około 6 miesięcy) – jeden okres gromadzenia danych tygodniowo.

Nie ma gwarancji jakości usług dla godzin aktualizacji. Jest ona uruchamiana codziennie w miarę naszych możliwości.

Schemat

Interfejs CrUX History API ma jeden punkt końcowy, który akceptuje żądania HTTP POST. Interfejs API zwraca element record, który zawiera co najmniej 1 element metrics odpowiadający danym o wydajności żą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 tych samych treści żądań co codzienny interfejs CrUX API z wyjątkiem obsługi pola żądania effectiveConnectionType.

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

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

Treść odpowiedzi

Udane żądania zwracają odpowiedzi z obiektem record i urlNormalizationDetails w następującej strukturze:

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

Na przykład odpowiedź w poprzednim żądaniu może wyglądać 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 określa wszystkie wymiary, które identyfikują ten rekord jako 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.
}
Pola
formFactor

enum (FormFactor)

Format to klasa urządzenia, z której wszyscy użytkownicy uzyskali dostęp do witryny na potrzeby tego rekordu.

Jeśli format jest nieokreślony, zwracane są dane zbiorcze dotyczące wszystkich formatów.

Pole sumy url_pattern. Wzorzec adresu URL to adres URL, którego dotyczy rekord. url_pattern może być tylko jedną z tych wartości:
origin

string

Źródło określa źródło, dla którego znajduje się ten rekord.

Uwaga: podczas określania źródła dane dotyczące wczytywania w ramach tego źródła na wszystkich stronach są agregowane w dane o wrażeniach użytkownika na poziomie źródła.

url

string

url określa konkretny adres URL, którego dotyczy ten rekord.

Uwaga: jeśli określisz właściwość url, dane tylko dla tego konkretnego adresu URL będą agregowane.

Wskaźniki

metric to zbiór danych o wrażeniach użytkownika związanych z pojedynczym rodzajem danych o wydajności witryny, np. pierwsze wyrenderowanie treści. Zawiera histogram podsumowujący rzeczywiste użytkowanie Chrome w postaci serii bins.

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

lub

"fractionTimeseries": {
  object (Fractions)
}
Pola
histogramTimeseries[]

object (Bin)

Histogram ciągu czasowego przedstawiający wrażenia użytkowników związane z danym rodzajem danych. Histogram ciągu czasowego będzie miał co najmniej 1 przedział, a gęstości wszystkich z nich będą wynosić ~1.

Brakujące wartości dla tego okresu zbierania danych zostaną oznaczone jako "NaN".

percentilesTimeseries

object (Percentiles)

Typowe przydatne centyle wskaźnika. Typ wartości centyli będzie taki sam jak typ wartości podany dla przedziału histogramu.

Brakujące wartości dla tego okresu zbierania danych zostaną oznaczone jako null.

fractionTimeseries

object (Fractions)

Ten obiekt zawiera ciąg czasowy ułamków oznaczonych etykietami, które dają razem około 1 na wpis.

Ułamki są zaokrąglane do 4 miejsc po przecinku.

Brakujące wpisy są wyrażone jako „NaN” we wszystkich ułamkach.

Przedział

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

Wartości początkowe i końcowe przedziału są określone w typie wartości reprezentowanych przez niego wartości. Na przykład pierwsze wyrenderowanie treści jest mierzone w milisekundach i wyświetlane jako liczba int, dlatego przedziały metryczne używają int32 jako typu początkowego i końcowego. Jednak skumulowane przesunięcie układu jest mierzone w ułamkach dziesiętnych bez jednostek i wyświetlane jako liczba dziesiętna zakodowana jako ciąg znaków, dlatego typy wartości w jego przedziałach danych będą używać ciągów znaków.

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

(integer | string)

Argument początek to początek koszyka danych.

end

(integer | string)

Argument koniec to koniec koszyka danych. Jeśli koniec nie jest podany, przedział ten nie ma końca i jest prawidłowy od początku do +inf.

densities

array[number]

Ciąg czasowy dotyczący odsetka użytkowników, którzy napotkali wartość tego przedziału w przypadku danego rodzaju danych.

Gęstości są zaokrąglane do 4 miejsc po przecinku.

Centyle

Percentiles zawiera syntetyczne wartości danych w danym percentylu statystycznym. Służą do oszacowania wartości danych na podstawie odsetka użytkowników w stosunku do łącznej liczby użytkowników.

{
  "P75": value
}
Pola
p75s

array[(integer | string)]

Ciągi czasowe wartości, których dotyczy 75% wczytań stron, wykazały, że dana wartość nie przekroczyła tej wartości.

Ułamki

Fractions zawiera ciąg czasowy oznaczonych ułamkami, które dają razem około 1 na wpis. Każda etykieta opisuje w jakiś sposób wczytanie strony, więc przedstawiane w ten sposób wskaźniki można traktować jako tworzące osobne wartości zamiast wartości liczbowych, a ułamki wskazują, jak często mierzona jest określona odrębna wartość.

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

Podobnie jak wartości gęstości w pojemnikach histogramu, każdy element fraction jest liczbą 0.0 <= value <= 1.0, której suma równa się ok.1,0. Jeśli dla danego okresu zbierania danych wskaźnik jest niedostępny, odpowiadający mu wpis będzie miał postać „NaN” we wszystkich tablicach ułamków.

Pola
p75s

array[(integer | string)]

Ciągi czasowe wartości, których dotyczy 75% wczytań stron, wykazały, że dana wartość nie przekroczyła tej wartości lub była niższa.

UrlNormalization

Obiekt reprezentujący działania normalizacji podejmowane w celu znormalizowania adresu URL, tak aby zwiększyć szansę na udane wyszukiwanie. Oto proste zmiany automatyczne wprowadzane podczas wyszukiwania podanych elementów url_pattern. Złożone działania, takie jak śledzenie przekierowań, nie są obsługiwane.

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

string

Pierwotny adres URL, którego dotyczyło żądanie, przed wykonaniem jakichkolwiek czynności związanych z normalizacją.

normalizedUrl

string

Adres URL po wykonaniu działań normalizacji. Jest to prawidłowy adres URL wrażeń użytkownika, który można wyszukać.

Ograniczenia liczby żądań

Interfejs CrUX History API ma ten sam limit co CrUX API dla 150 zapytań na minutę na projekt Google Cloud w przypadku każdego z interfejsów API (dostępnych bez opłat). Ten limit oraz aktualne wykorzystanie możesz sprawdzić w Google Cloud Console. Taki duży limit powinien wystarczyć do większości zastosowań, a jego zwiększenie nie jest możliwe.