CrUX API

Über die CrUX API erhalten Sie mit niedriger Latenz Zugriff auf aggregierte Daten zur Nutzerfreundlichkeit auf Seiten- und Ursprungsebene.

Häufiger Anwendungsfall

Mit der CrUX API können Messwerte zur Nutzererfahrung für einen bestimmten URI wie „Messwerte für den Ursprung https://example.com abrufen“ abgefragt werden.

CrUX API-Schlüssel

Für die Verwendung der CrUX API ist ein Google Cloud API-Schlüssel erforderlich. Sie können auf der Seite Anmeldedaten eine Anmeldedaten erstellen und sie für Chrome UX Report API bereitstellen.

Sobald Sie einen API-Schlüssel haben, kann Ihre Anwendung den Suchparameter key=[YOUR_API_KEY] an alle Anfrage-URLs anhängen (siehe Beispielabfragen).

Der API-Schlüssel lässt sich sicher in URLs einbetten. Eine Codierung ist nicht notwendig.

Datenmodell

In diesem Abschnitt wird die Struktur der Daten in Anfragen und Antworten beschrieben.

Eintrag

Eine eigenständige Information über eine Seite oder Website. Ein Datensatz kann Daten enthalten, die für eine Kennung und eine bestimmte Kombination von Dimensionen spezifisch sind. Ein Datensatz kann Daten für einen oder mehrere Messwerte enthalten.

IDs

IDs geben an, nach welchen Datensätzen gesucht werden soll. In CrUX sind diese Kennungen Webseiten und Websites.

Ursprung

Wenn es sich bei der Kennung um einen Ursprung handelt, werden alle für alle Seiten in diesem Ursprung vorhandenen Daten zusammengefasst. Angenommen, der Ursprung http://www.example.com hat die Seiten, die in dieser Sitemap angeordnet sind:

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

Wenn also der UX-Bericht für Chrome abgefragt wird und der Ursprung auf http://www.example.com gesetzt ist, werden Daten für http://www.example.com/, http://www.example.com/foo.html und http://www.example.com/bar.html zurückgegeben, zusammengefasst, da dies alle Seiten unter diesem Ursprung sind.

URLs

Wenn die ID eine URL ist, werden nur Daten für diese spezifische URL zurückgegeben. Gehen Sie noch einmal zur Ursprungs-Sitemap http://www.example.com:

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

Wenn die ID auf URL mit dem Wert http://www.example.com/foo.html festgelegt ist, werden nur Daten für diese Seite zurückgegeben.

Abmessungen

Dimensionen identifizieren eine bestimmte Gruppe von Daten, mit denen ein Datensatz aggregiert wird. So gibt beispielsweise der Formfaktor PHONE an, dass der Datensatz Informationen zu Ladevorgängen auf einem Mobilgerät enthält. Jede Dimension hat eine bestimmte Anzahl von Werten. Wenn diese Dimension nicht angegeben wird, wird sie über alle Werte aggregiert. Wenn Sie zum Beispiel keinen Formfaktor angeben, bedeutet dies, dass der Datensatz Informationen über Ladevorgänge enthält, die auf einem beliebigen Formfaktor stattgefunden haben.

Formfaktor

Die Geräteklasse, mit der der Endnutzer die Seite aufgerufen hat. Dies ist eine allgemeine Geräteklasse, die in die Kategorien PHONE, TABLET und DESKTOP unterteilt ist.

Effektiver Anschlusstyp

Der effektive Verbindungstyp gibt die geschätzte Verbindungsqualität des Geräts beim Aufrufen der Seite an. Dies ist eine allgemeine Klasse, die in die Kategorien offline, slow-2G, 2G, 3G und 4G unterteilt ist.

Messwert

Messwerte werden als statistische Aggregationen, als Histogramme, Perzentile und Brüche erfasst.

Gleitkommawerte werden auf vier Dezimalstellen gerundet. Beachten Sie, dass die cumulative_layout_shift-Messwerte doppelt als String codiert sind. Gleitkommazahlen werden daher nicht berücksichtigt und im String mit zwei Dezimalstellen gemeldet.

Histogramm

Wenn Messwerte in einem Histogramm ausgedrückt werden, sehen Sie die Prozentsätze der Seitenladevorgänge, die in bestimmte Bereiche für diesen Messwert fallen.

Ein einfaches Histogramm mit drei Bins für einen Beispielmesswert sieht so aus:

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

Diese Daten zeigen an, dass der Beispielmesswert bei 38,18% der Seitenladevorgänge zwischen 0 ms und 1.000 ms gemessen wurde. Die Einheiten des Messwerts sind in diesem Histogramm nicht enthalten. In diesem Fall gehen wir von Millisekunden aus.

Außerdem sahen 49,91% der Seitenaufrufe einen Messwert zwischen 1.000 ms und 3.000 ms und 11,92 % einen Wert, der über 3.000 ms lag.

Perzentile

Messwerte können auch Perzentile enthalten, die für weitere Analysen nützlich sein können. Für diesen Messwert werden bestimmte Werte nach dem angegebenen Perzentil erfasst. Sie basieren auf dem vollständigen Satz verfügbarer Daten und nicht auf den endgültigen gruppierten Daten, sodass sie nicht unbedingt mit einem interpolierten Perzentil übereinstimmen, das auf dem endgültigen gruppierten Histogramm basiert.

{
  "percentiles": {
    "p75": 2063
  }
}

In diesem Beispiel wurden mindestens 75% der Seitenaufrufe mit dem Messwert <= 2063 gemessen.

Brüche

Bruchteile geben die Prozentsätze der Seitenladevorgänge an, die mit einem bestimmten Label versehen werden können. In diesem Fall sind die Messwerte diese Labels.

Der Messwert form_factors besteht beispielsweise aus einem fractions-Objekt, das eine Aufschlüsselung der Formfaktoren (oder Geräte) auflistet, die die jeweilige Abfrage abdeckt:

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

In diesem Fall wurden 3,77% der Seitenaufrufe auf einem Computer, 2,88% auf einem Tablet und 93,35% auf einem Smartphone gemessen, was insgesamt 100% entspricht.

Messwerttypen

Name des CrUX API-Messwerts	Datentyp	Metrische Einheiten	Statistische Aggregationen	Dokumentation
cumulative_layout_shift	Zwei Dezimalstellen als String doppelt codiert	ohne Einheit	Histogramm mit drei Klassen, Perzentile mit P75	cls
first_contentful_paint	int	Millisekunden	Histogramm mit drei Klassen, Perzentile mit P75	FCP
first_input_delay (eingestellt)	int	Millisekunden	Histogramm mit drei Klassen, Perzentile mit P75	Fid
interaction_to_next_paint	int	Millisekunden	Histogramm mit drei Klassen, Perzentile mit P75	Inp
largest_contentful_paint	int	Millisekunden	Histogramm mit drei Klassen, Perzentile mit P75	LPP
experimental_time_to_first_byte	int	Millisekunden	Histogramm mit drei Klassen, Perzentile mit P75	TTFB
form_factors	Doppelte Stellen mit 4 Dezimalstellen	Prozentzeichen	Zuordnung vom Formfaktor zum Bruch	Formfaktoren
navigation_types	Doppelte Stellen mit 4 Dezimalstellen	Prozentzeichen	Zuordnung vom Navigationstyp zum Bruch	Navigationstypen
round_trip_time	int	Millisekunden	Perzentile mit P75	rtt

Zuordnung von BigQuery-Messwertnamen

Name des CrUX API-Messwerts	Name des BigQuery-Messwerts
cumulative_layout_shift	layout_instability.cumulative_layout_shift
first_contentful_paint	first_contentful_paint
first_input_delay	first_input.delay
interaction_to_next_paint	interaction_to_next_paint
largest_contentful_paint	largest_contentful_paint
experimental_time_to_first_byte	experimental.time_to_first_byte
navigation_types	navigation_types
form_factors	–
round_trip_time	–

Erfassungszeitraum

Seit Oktober 2022 enthält die CrUX API ein collectionPeriod-Objekt mit den Feldern firstDate und endDate, die das Start- und Enddatum des Aggregationsfensters darstellen. Beispiel:

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

Auf diese Weise können Sie die Daten besser verstehen und feststellen, ob sie für diesen Tag noch aktualisiert wurden oder dieselben Daten wie gestern zurückgeben.

Die CrUX API liegt etwa zwei Tage hinter dem heutigen Datum, da sie auf die abgeschlossenen Daten für den Tag wartet. Außerdem ist eine gewisse Verarbeitungszeit erforderlich, bis die API in der API verfügbar ist. Als Zeitzone wird Pacific Standard Time (PST) verwendet, wobei die Umstellung auf Sommer-/Winterzeit nicht erfolgt.

Beispielabfragen

Abfragen werden als JSON-Objekte mit einer POST-Anfrage an https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" mit Abfragedaten als JSON-Objekt im POST-Text gesendet:

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

Dies kann beispielsweise über curl mit der folgenden Befehlszeile aufgerufen werden (ersetzen Sie dabei API_KEY durch Ihren Schlüssel):

curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryRecord?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"]}'

Daten auf Seitenebene sind über die API verfügbar, indem in der Abfrage eine url-Eigenschaft anstelle von origin übergeben wird:

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

Wenn das Attribut metrics nicht festgelegt ist, werden alle verfügbaren Messwerte zurückgegeben:

• cumulative_layout_shift
• first_contentful_paint
• first_input_delay (eingestellt)
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• navigation_types
• form_factors (wird nur gemeldet, wenn in der Anfrage kein formFactor angegeben wurde)

Wenn kein formFactor-Wert angegeben wird, werden die Werte für alle Formfaktoren aggregiert.

Weitere Beispielabfragen finden Sie unter Chrome UX Report API verwenden.

Datenpipeline

Das CrUX-Dataset wird über eine Pipeline verarbeitet, um die Daten zu konsolidieren, zu aggregieren und zu filtern, bevor sie über die API verfügbar werden.

Gleitender Durchschnitt

Bei den Daten im UX-Bericht für Chrome handelt es sich um einen gleitenden Durchschnitt aggregierter Messwerte über einen Zeitraum von 28 Tagen. Das bedeutet, dass es sich bei den Daten im UX-Bericht für Chrome zu einem bestimmten Zeitpunkt um Daten der letzten 28 Tage handelt.

Ähnlich wie im CrUX-Dataset in BigQuery werden monatliche Berichte zusammengefasst.

Tägliche Updates

Die Daten werden täglich um 4:00 Uhr (UTC) aktualisiert. Es gibt kein Service Level Agreement für Aktualisierungszeiten; es wird täglich nach dem Best-Effort-Prinzip ausgeführt.

Schema

Es gibt einen einzigen Endpunkt für die CrUX API, die POST-HTTP-Anfragen akzeptiert. Die API gibt eine record zurück, die mindestens eine metrics enthält, die den Leistungsdaten zum angeforderten Ursprung oder der angeforderten Seite entspricht.

HTTP-Anfrage

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

Die URL verwendet die Syntax der gRPC-Transcodierung.

Anfragetext

Der Anfragetext sollte Daten mit folgender Struktur enthalten:

{
  "effectiveConnectionType": string,
  "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.
}

Felder
effectiveConnectionType	string Der Typ der effektiven Verbindung ist eine Abfragedimension, die die effektive Netzwerkklasse angibt, zu der die Daten des Eintrags gehören sollen. In diesem Feld werden die Werte ["offline", "slow-2G", "2G", "3G", "4G"] verwendet, wie in der Network Information API-Spezifikation angegeben. Hinweis: Wenn kein effektiver Verbindungstyp angegeben wird, wird ein spezieller Datensatz mit aggregierten Daten über alle effektiven Verbindungstypen zurückgegeben.
formFactor	enum (FormFactor) Der Formfaktor ist eine Abfragedimension, die die Geräteklasse angibt, zu der die Daten des Eintrags gehören sollen. Dieses Feld verwendet die Werte DESKTOP, PHONE oder TABLET. Hinweis: Wenn kein Formfaktor angegeben ist, wird ein spezieller Datensatz mit aggregierten Daten über alle Formfaktoren zurückgegeben.
metrics[]	string Die Messwerte, die in der Antwort enthalten sein sollen. Wenn keine angegeben sind, werden alle gefundenen Messwerte zurückgegeben. Zulässige Werte: ["cumulative_layout_shift", "first_contentful_paint", "first_input_delay", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
Union-Feld url_pattern. url_pattern ist die Hauptkennung für die Suche nach Einträgen. Folgende Werte sind zulässig:
origin	string Der „Ursprung“ (url_pattern) bezieht sich auf ein URL-Muster, das den Ursprung einer Website darstellt. Beispiele: "https://example.com", "https://cloud.google.com"
url	string Das url_pattern-url verweist auf ein URL-Muster mit einer beliebigen URL. Beispiele: "https://example.com/, https://cloud.google.com/why-google-cloud/"

So fordern Sie beispielsweise die größten Contentful Paint-Werte für Computer für die Startseite der Chrome-Entwicklerdokumentation an:

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

Antworttext

Erfolgreiche Anfragen geben Antworten mit einem record-Objekt und einem urlNormalizationDetails in der folgenden Struktur zurück:

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

Die Antwort auf den Anfragetext in der vorherigen Anfrage könnte beispielsweise so aussehen:

{
  "record": {
    "key": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.9815
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.0108
          },
          {
            "start": 4000,
            "density": 0.0077
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

Schlüssel

Key definiert alle Dimensionen, die diesen Datensatz als eindeutig identifizieren.

{
  "effectiveConnectionType": string,
  "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.
}

Felder
formFactor	enum (FormFactor) Der Formfaktor ist die Geräteklasse, über die alle Nutzer für diesen Eintrag auf die Website zugegriffen haben. Wenn der Formfaktor nicht angegeben ist, werden aggregierte Daten für alle Formfaktoren zurückgegeben.
effectiveConnectionType	string Der effektive Verbindungstyp ist die allgemeine Verbindungsklasse, die alle Nutzer für diesen Eintrag hatten. In diesem Feld werden die Werte ["offline", "slow-2G", "2G", "3G", "4G"] verwendet, wie hier angegeben: https://wicg.github.io/netinfo/#effective-connection-types Wenn der effektive Verbindungstyp nicht angegeben ist, werden aggregierte Daten für alle effektiven Verbindungstypen zurückgegeben.
Union-Feld url_pattern. Das URL-Muster ist die URL, für die der Eintrag gilt. Für url_pattern ist nur einer der folgenden Werte zulässig:
origin	string origin gibt den Ursprung an, für den dieser Eintrag gilt. Hinweis: Wenn Sie ein origin angeben, werden Daten für Ladevorgänge dieses Ursprungs auf allen Seiten in Daten zur Nutzererfahrung auf Ursprungsebene zusammengefasst.
url	string url gibt eine bestimmte URL an, für die dieser Eintrag bestimmt ist. Hinweis: Wenn du eine url angibst, werden nur Daten für diese spezifische URL zusammengefasst.

Messwerte

Ein metric besteht aus aggregierten Daten zur Nutzererfahrung für einen einzelnen Webleistungsmesswert, z. B. „First Contentful Paint“. Sie kann ein Histogramm der realen Nutzung von Chrome in Form einer Reihe von bins, bestimmten Perzentildaten (z. B. P75) oder mit Labels versehene Bruchteile enthalten.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

oder

{
  "fractions": {
    object (Fractions)
  }
}

Felder
histogram[]	object (Bin) Das Histogramm der Nutzerfreundlichkeit für einen Messwert. Das Histogramm hat mindestens eine Klasse und die Dichten aller Klassen ergeben zusammen ~1.
percentiles	object (Percentiles) Gemeinsame nützliche Perzentile des Messwerts. Der Werttyp für die Perzentile entspricht den Werttypen, die für die Histogramm-Bins angegeben wurden.
fractions	object (Fractions) Dieses Objekt enthält Brüche mit Labels, die zusammen ~1 ergeben. Brüche werden auf vier Dezimalstellen gerundet.

Klasse

Eine bin ist ein diskreter Teil von Daten, der sich von Anfang bis Ende erstreckt, oder wenn kein Ende von Anfang bis positiv unendlich angegeben wird.

Die Start- und Endwerte einer Klasse werden im Werttyp der entsprechenden Metrik angegeben. First Contentful Paint wird beispielsweise in Millisekunden gemessen und als Ganzzahlen dargestellt. Daher verwenden die Messwert-Bins als Start- und Endtyp den Wert „int32“. Kumulative Layout Shifts werden jedoch in Dezimalzahlen ohne Einheit gemessen und als Dezimalzahl dargestellt und als String codiert. Daher verwenden die Messwert-Klassen Strings als Werttyp.

{
  "start": value,
  "end": value,
  "density": number
}

Felder
start	(integer | string) „Start“ ist der Anfang der Datengruppe.
end	(integer | string) Das Ende ist das Ende der Datengruppe. Wenn für end nichts angegeben ist, hat der Container kein Ende und ist von „start“ bis „+inf“ gültig.
density	number Der Anteil der Nutzer, die den Bin-Wert für den jeweiligen Messwert erlebt haben. Dichten werden auf vier Dezimalstellen gerundet.

Perzentile

Percentiles enthält synthetische Werte eines Messwerts bei einem bestimmten statistischen Perzentil. Sie werden verwendet, um den Wert eines Messwerts zu schätzen, der von einem Prozentsatz der Nutzer bezogen auf die Gesamtzahl der Nutzer erlebt wird.

{
  "P75": value
}

Felder
p75	(integer | string) Bei 75% der Seitenladevorgänge lag der angegebene Messwert bei oder unter diesem Wert.

Brüche

Fractions enthält Brüche mit Labels, die zusammen eine Summe von ~1 ergeben. Jedes Label beschreibt einen Seitenaufbau in irgendeiner Weise. Auf diese Weise dargestellte Messwerte können als Ergebnis der Erzeugung unterschiedlicher Werte anstelle von numerischen Werten betrachtet werden. Die Bruchteile geben an, wie häufig ein bestimmter bestimmter Wert gemessen wurde.

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

Ähnlich wie die Dichtewerte in Histogrammbins ist jedes fraction eine Zahl 0.0 <= value <= 1.0 und sie ergeben zusammen ca.1,0.

UrlNormalization

Objekt, das die Normalisierungsaktionen darstellt, die zum Normalisieren einer URL durchgeführt werden, um eine höhere Wahrscheinlichkeit für einen erfolgreichen Lookup zu erreichen. Dies sind einfache automatisierte Änderungen, die bei der Suche nach der bereitgestellten url_pattern vorgenommen werden. Diese Änderungen würden scheitern. Komplexe Aktionen wie das Folgen von Weiterleitungen werden nicht berücksichtigt.

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

Felder
originalUrl	string Die ursprünglich angeforderte URL vor allen Normalisierungsaktionen.
normalizedUrl	string Die URL nach allen Normalisierungsaktionen. Dies ist eine gültige URL für die Nutzererfahrung, die vernünftigerweise nachgeschlagen werden könnte.

Ratenbegrenzungen

Die CrUX API ist auf 150 Abfragen pro Minute pro Google Cloud-Projekt beschränkt, die kostenlos angeboten werden. Dieses Limit und Ihre aktuelle Nutzung können Sie in der Google Cloud Console einsehen. Dieses großzügige Kontingent sollte für die meisten Anwendungsfälle ausreichen. Ein höheres Kontingent kann nicht finanziell beglichen werden.