CrUX API

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

Testen!

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

Zur Verwendung der CrUX API ist ein Google Cloud API-Schlüssel erforderlich, der für die Chrome UX Report API-Nutzung bereitgestellt wird.

API-Schlüssel erhalten und nutzen

Schl�ssel anfordern

Alternativ k�nnen Sie auf der Seite "Anmeldedaten" einen Schl�ssel erstellen.

Nachdem Sie einen API-Schl�ssel haben, kann Ihre Anwendung den Abfrageparameter key=yourAPIKey an alle Anfrage-URLs anh�ngen.

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

Weitere Informationen finden Sie unter Beispielabfragen.

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 dargestellt werden:

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 aufgeteilt 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 offline, slow-2G, 2G, 3G und 4G unterteilt ist.

Messwert

Messwerte werden als statistische Aggregationen, als Histogramme, Perzentile und Br�che gemeldet.

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 dargestellt werden, sehen Sie die Prozents�tze der Seitenaufrufe, die bestimmte Bereiche f�r diesen Messwert.

Ein Histogramm mit drei Klassen 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 bei 38,18% der Seitenladevorg�nge der Beispielmesswert gemessen wurde. zwischen 0 ms und 1.000 ms. Die Einheiten des Messwerts sind in diesem Histogramm nicht enthalten, In diesem Fall gehen wir von Millisekunden aus.

Au�erdem ergab sich bei 49,91% der Seitenaufrufe ein Messwert zwischen 1.000 ms und 3.000 ms und 11,92 %. einen Wert �ber 3.000 ms sahen.

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 allen verf�gbaren Daten und nicht auf den endg�ltigen gruppierten Daten, sodass sie nicht unbedingt mit einem interpolierten Perzentil �bereinstimmen, das auf dem das endg�ltige gruppierte Histogramm.

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

In diesem Beispiel wurden mindestens 75�% der Seitenladezeiten 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 Messwertwerte 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 Bins, Perzentile mit p75	fcp
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	Doppelt mit 4�Dezimalstellen	Prozent	Zuordnung vom Formfaktor zum Bruch	Formfaktoren
navigation_types	Doppelte Stellen mit 4 Dezimalstellen	Prozent	Zuordnung von Navigationstyp zu Bruchteil	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	–

Erhebungszeitraum

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

So k�nnen Sie die Daten besser nachvollziehen und erkennen, ob sie f�r den jeweiligen Tag bereits aktualisiert wurden oder ob dieselben Daten wie gestern zur�ckgegeben werden.

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. Die Sommerzeit wird nicht ge�ndert.

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

Der CrUX-Datensatz wird in einer Pipeline verarbeitet, um die Daten zu konsolidieren, zu aggregieren und zu filtern, bevor sie �ber die API verf�gbar gemacht 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 die Daten, die im Chrome UX Report zu einem bestimmten Zeitpunkt angezeigt werden, in Wirklichkeit Daten der letzten 28�Tage sind, die zusammengefasst wurden.

�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. jeden Tag auf Best-Effort-Basis 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 ist, 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. In diesem Feld werden 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. Die url_pattern ist die Hauptkennzeichnung für die Datensatzsuche. Folgende Werte sind zulässig:
origin	string Der „Ursprung“ url_pattern bezieht sich auf ein URL-Muster, das den Ursprung einer Website darstellt. Beispiele: "/proxy/https://example.com", "/proxy/https://cloud.google.com"
url	string Das url_pattern-url verweist auf ein URL-Muster mit einer beliebigen URL. Beispiele: "/proxy/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"] wie in https://wicg.github.io/netinfo/#effective-connection-types angegeben. 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 eine 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 von bins-spezifischen Perzentildaten enthalten. (z. B. p75) oder Brüche mit Labels 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 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 beschriftete Fraktionen, die zusammen etwa�1 ergeben. Jedes Label beschreibt ein Seitenaufbau vor. Daher sind die so dargestellten Messwerte wobei unterschiedliche Werte anstelle von numerischen Werten erzeugt werden, und die Br�che ausdr�cken wie oft ein bestimmter bestimmter Wert gemessen wurde.

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

�hnlich wie bei den Dichtewerten in Histogrammklassen ist jeder fraction eine Zahl. 0.0 <= value <= 1.0, und sie ergeben in der Summe 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 Nutzerfreundlichkeit, die vern�nftigerweise aufgerufen werden k�nnte.

Ratenlimits

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.