CrUX API

Die CrUX API bietet Zugriff mit niedriger Latenz auf aggregierte Daten zur Nutzerfreundlichkeit auf Seite und Ursprung.

Gängiger Anwendungsfall

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

CrUX API-Schlüssel

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

Sobald Sie einen API-Schlüssel haben, kann Ihre Anwendung den Suchparameter key=[YOUR_API_KEY] an alle Anfrage-URLs anhängen. 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.

Datensatz

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

IDs

IDs geben an, welche Datensätze abgerufen werden sollen. In CrUX sind diese Kennungen Webseiten und Websites.

Ursprung

Wenn die Kennung ein Ursprung ist, werden alle Daten für alle Seiten dieses Ursprungs zusammengefasst. Angenommen, der Ursprung http://www.example.com hatte Seiten gemäß dieser Sitemap:

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, für den 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 in aggregierter Form zurückgegeben, da es sich um alle Seiten dieses Ursprungs handelt.

URLs

Wenn es sich bei der Kennung um eine URL handelt, werden nur Daten für diese spezifische URL zurückgegeben. Noch einmal auf die ursprüngliche Sitemap von http://www.example.com:

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

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

Abmessungen

Dimensionen geben eine bestimmte Gruppe von Daten an, mit denen ein Datensatz aggregiert wird. Beispielsweise gibt der Formfaktor PHONE an, dass der Datensatz Informationen zu Ladevorgängen enthält, die auf einem Mobilgerät stattgefunden haben. Jede Dimension hat eine bestimmte Anzahl von Werten. Wenn diese Dimension nicht angegeben wird, bedeutet das, dass sie für alle Werte zusammengefasst wird. Wird kein Formfaktor angegeben, bedeutet dies beispielsweise, dass der Datensatz Informationen zu Ladevorgängen 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 PHONE, TABLET und DESKTOP unterteilt ist.

Effektiver Verbindungstyp

Effektiver Verbindungstyp ist die geschätzte Verbindungsqualität des Geräts beim Aufrufen der Seite. Dies ist eine allgemeine Klasse, die in offline, slow-2G, 2G, 3G und 4G aufgeteilt ist.

Messwert

Messwerte werden als statistische Aggregationen, in Histogrammen, Perzentilen und Brüchen angegeben.

Gleitkommawerte werden auf vier Dezimalstellen gerundet. Beachten Sie, dass die cumulative_layout_shift-Messwerte doppelt als String codiert sind. Sie werden nicht als Gleitkommazahlen berücksichtigt und werden innerhalb des Strings auf zwei Dezimalstellen ausgegeben.

Histogramm

Wenn Messwerte in einem Histogramm dargestellt werden, werden die Prozentsätze der Seitenladevorgänge angezeigt, 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, dass der Beispielmesswert bei 38,18% der Seitenaufrufe 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 über 3.000 ms.

Perzentile

Messwerte können auch Perzentile enthalten, die für zusätzliche Analysen nützlich sein können. Es werden spezifische Messwerte auf Basis des jeweiligen Perzentils für diesen Messwert angegeben. Sie basieren auf dem vollständigen Satz verfügbarer Daten und nicht auf den endgültigen gruppierten Daten. Daher stimmen sie nicht unbedingt mit einem interpolierten Perzentil überein, das auf dem endgültigen gruppierten Histogramm basiert.

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

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

Hinweis:Die Werte für jedes Perzentil sind synthetisch abgeleitet. Das bedeutet nicht, dass der angegebene Wert tatsächlich für einen Nutzer erfasst wurde. Es gab nur bei einem Teil des Seitenaufbaus einen Messwert, der unter dem angegebenen Wert liegt.

Brüche

Bruchteile geben die Prozentsätze des Seitenaufbaus an, die unterschiedlich beschriftet 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 in der angegebenen Abfrage enthalten sind:

"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% ergibt.

Messwerttypen

CrUX API-Messwertname	Datentyp	Metrische Einheiten	Statistische Zusammenfassungen	Dokumentation
cumulative_layout_shift	Zwei Dezimalstellen doppelt als String 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	lcp
experimental_time_to_first_byte	int	Millisekunden	Histogramm mit drei Klassen, Perzentile mit p75	TTFB
form_factors	Doppelte Stelle mit 4 Dezimalstellen	Prozent	Zuordnung von Formfaktor zu Bruch	Formfaktoren
navigation_types	Doppelte Stelle mit 4 Dezimalstellen	Prozent	Zuordnung vom Navigationstyp zum Bruch	Navigationstypen

Zuordnung von BigQuery-Messwertnamen

CrUX API-Messwertname	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	–

Hinweis:In CrUX BigQuery ergeben die Histogrammdichten bezogen auf alle Formfaktoren 100% pro Ursprung. Daher wird der form_factors-Messwert, den wir in der API unterstützen, stattdessen als Histogrammdichte für first_contentful_paint ausgedrückt.

Erhebungszeitraum

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

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

So können Sie die Daten besser verstehen und feststellen, ob sie für diesen Tag noch aktualisiert wurden oder die gleichen Daten wie gestern zurückgegeben werden.

Beachten Sie, dass die CrUX API etwa zwei Tage hinter dem heutigen Datum liegt, da sie auf abgeschlossene Daten für den Tag wartet und einige Verarbeitungszeit erforderlich ist, bevor sie in der API verfügbar ist. Die verwendete Zeitzone ist Pacific Standard Time (PST) ohne Umstellung auf Sommer-/Winterzeit.

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-Textkörper gesendet:

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

Sie kann beispielsweise über curl mit der folgenden Befehlszeile aufgerufen werden. Dabei wird API_KEY durch Ihren Schlüssel ersetzt:

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

Hinweis:Das vorherige Beispiel gilt für macOS- oder Linux-basierte Systeme, einschließlich der Git BASH-Shell für Windows. Bei anderen Systemen sind möglicherweise geringfügige Änderungen erforderlich. In der cmd.exe-Befehlszeile sind beispielsweise weder einfache Anführungszeichen für Parameter noch Zeilenfortsetzungen (\) zulässig. Daher müssen doppelte Anführungszeichen (entsprechende Escapezeichen innerer Anführungszeichen für \") und eine einzelne Zeile verwendet werden.

Daten auf Seitenebene sind über die API verfügbar, wenn statt origin das Attribut url in der Abfrage ü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 (nur gemeldet, wenn in der Anfrage kein formFactor angegeben ist)

Wenn kein formFactor-Wert angegeben ist, 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 sind.

Der gleitende Durchschnitt

Bei den Daten im UX-Bericht für Chrome handelt es sich um einen gleitenden Durchschnitt über 28 Tage von aggregierten Messwerten. Das bedeutet, dass es sich bei den Daten, die jeweils im Bericht zur Nutzererfahrung von Chrome angezeigt werden, um Daten der letzten 28 Tage handelt.

Dies ähnelt der Zusammenfassung monatlicher Berichte im CrUX-Dataset in BigQuery.

Tägliche Updates

Die Daten werden täglich um 04:00 Uhr (UTC) aktualisiert. Es gibt kein Service Level Agreement (SLA) für Aktualisierungszeiten. Die Updates werden jeden Tag auf Best-Effort-Basis durchgeführt.

Achtung:Die Daten unterscheiden sich nach der Aktualisierung um 04:00 Uhr (UTC) innerhalb eines Tages nicht. Wiederholte Aufrufe führen zum gleichen Ergebnis.

Schema

Für die CrUX API gibt es einen einzelnen Endpunkt, der POST-HTTP-Anfragen akzeptiert. Die API gibt ein record zurück, das eine oder mehrere metrics enthält, die den Leistungsdaten zum angeforderten Ursprung oder zur angeforderten Seite entsprechen.

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 effektive Verbindungstyp 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 ist, wird ein spezieller Datensatz mit aggregierten Daten für 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. In diesem Feld werden die Werte DESKTOP, PHONE oder TABLET verwendet. Hinweis: Wenn kein Formfaktor angegeben ist, wird ein spezieller Datensatz mit aggregierten Daten für 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 eine Datensatzsuche. Folgende Optionen sind zulässig:
origin	string „origin“ (url_pattern) bezieht sich auf ein URL-Muster, das der Ursprung einer Website ist. Beispiele: "https://example.com", "https://cloud.google.com"
url	string url_pattern url bezieht sich auf ein URL-Muster, das eine beliebige URL ist. 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

Bei erfolgreichen Anfragen werden Antworten mit einem record-Objekt und urlNormalizationDetails in der folgenden Struktur zurückgegeben:

{
  "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, mit denen dieser Datensatz als eindeutig identifiziert wird.

{
  "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, die alle Nutzer verwendet haben, um für diesen Eintrag auf die Website zuzugreifen. Wenn der Formfaktor nicht angegeben ist, werden aggregierte Daten zu allen Formfaktoren zurückgegeben.
effectiveConnectionType	string Der effektive Verbindungstyp ist die allgemeine Verbindungsklasse, die alle Nutzer für diesen Eintrag festgestellt haben. In diesem Feld werden die Werte ["offline", "slow-2G", "2G", "3G", "4G"] verwendet, wie unter https://wicg.github.io/netinfo/#effective-connection-types angegeben. Wenn der effektive Verbindungstyp nicht angegeben ist, werden aggregierte Daten über 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 dieses Eintrags an. Hinweis: Wenn Sie ein origin angeben, werden Daten für Ladevorgänge unter diesem Ursprung auf allen Seiten zu Nutzererfahrungsdaten auf Ursprungsebene zusammengefasst.
url	string url gibt eine bestimmte URL an, für die dieser Eintrag bestimmt ist. Hinweis: Bei Angabe von url werden nur Daten für diese spezifische URL aggregiert.

Messwerte

Ein metric ist ein Satz aggregierter Daten zur Nutzererfahrung für einen einzelnen Web-Leistungsmesswert, z. B. First Contentful Paint. Es kann ein zusammenfassendes Histogramm der realen Chrome-Nutzung in Form einer Reihe von bins, spezifischen 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 Nutzererfahrung für einen Messwert. Das Histogramm enthält mindestens einen Container und die Dichten aller Klassen ergeben zusammengenommen ungefähr 1.
percentiles	object (Percentiles) Allgemeine nützliche Perzentile des Messwerts. Der Werttyp für die Perzentile entspricht den Werttypen für die Histogrammgruppen.
fractions	object (Fractions) Dieses Objekt enthält beschriftete Brüche, die zusammengenommen ~1 ergeben. Brüche werden auf vier Dezimalstellen gerundet.

Klasse

Ein bin ist ein diskreter Teil von Daten, der von Anfang bis Ende umfasst oder wenn kein Ende vom Anfang bis positiv unendlich angegeben wird.

Die Start- und Endwerte einer Klasse sind im Werttyp des dargestellten Messwerts angegeben. Beispielsweise wird First Contentful Paint in Millisekunden gemessen und als Ganzzahl dargestellt. Daher verwenden seine Messwertbins int32s für die Start- und Endtypen. Die kumulative Layoutverschiebung wird jedoch in Dezimalzahlen ohne Einheit gemessen und als Dezimalzahl codiert, die als String codiert ist. Daher verwenden die Messwertbinden Strings als Werttyp.

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

Felder
start	(integer | string) „Start“ ist der Anfang des Datencontainers.
end	(integer | string) Ende ist das Ende der Datengruppe. Wenn das Feld end nicht ausgefüllt ist, hat der Container kein Ende und ist von Anfang bis +inf gültig.
density	number Anteil der Nutzer, bei denen der Wert dieses Containers für den angegebenen Messwert erfasst wurde. Die Dichten werden auf 4 Dezimalstellen gerundet.

Perzentile

Percentiles enthält synthetische Werte eines Messwerts bei einem bestimmten statistischen Perzentil. Sie werden verwendet, um den Wert eines Messwerts so zu schätzen, wie er für einen Prozentsatz der Nutzer im Vergleich zur Gesamtzahl der Nutzer zu sehen ist.

{
  "P75": value
}

Felder
p75	(integer | string) Bei 75% der Seitenaufbauvorgänge war der angegebene Messwert unter diesem Wert.

Brüche

Fractions enthält mit Labels versehene Brüche, die zusammengenommen ~1 ergeben. Jedes Label beschreibt einen Seitenaufbau auf irgendeine Art und Weise. Die so dargestellten Messwerte erzeugen unterschiedliche Werte anstelle von numerischen Werten. 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 Histogrammklassen ist jeder fraction eine Zahl 0.0 <= value <= 1.0, deren Summe ungefähr 1, 0 ergibt.

UrlNormalization

Objekt, das die Normalisierungsaktionen darstellt, die zur Normalisierung einer URL erforderlich sind, um eine höhere Wahrscheinlichkeit einer erfolgreichen Suche zu erzielen. Dies sind einfache automatisierte Änderungen, die bei der Suche nach der bereitgestellten url_pattern vorgenommen werden und scheitern. Komplexe Aktionen wie 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, die Nutzer nachschlagen könnte.

Ratenbegrenzungen

Die CrUX API ist auf 150 Abfragen pro Minute pro Google Cloud-Projekt beschränkt und wird kostenlos angeboten. 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 und es ist nicht möglich, für ein erhöhtes Kontingent zu bezahlen.