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: "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"] 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.