CrUX API

Die CrUX API bietet Zugriff mit geringer Latenz auf aggregierte Daten zur Nutzererfahrung auf Seiten- und Ursprungsebene.

Testen!

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, der für die Verwendung von Chrome UX Report API bereitgestellt wurde.

API-Schlüssel erhalten und nutzen

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.

Beispielabfragen

Datenmodell

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

Aufnehmen

Eine einzelne Information zu einer Seite oder Website. Ein Eintrag 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

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

Ursprung

Wenn die Kennung ein Ursprung ist, werden alle Daten für alle Seiten in diesem Ursprung zusammengefasst. Angenommen, der Ursprung http://www.example.com hat Seiten, die in dieser Sitemap aufgeführt sind:

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

Wenn Sie den Chrome UX Report mit dem Ursprung http://www.example.com abfragen, werden die Daten für http://www.example.com/, http://www.example.com/foo.html und http://www.example.com/bar.html zusammengefasst zurückgegeben, da es sich bei allen um Seiten unter diesem Ursprung handelt.

URLs

Wenn die Kennung eine URL ist, werden nur Daten für diese bestimmte URL zurückgegeben. Sehen wir uns noch einmal die Sitemap für den Ursprung http://www.example.com an:

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

Wenn die Kennung 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. Ein Formfaktor von PHONE gibt beispielsweise 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 eine Dimension nicht angegeben wird, bedeutet das implizit, dass sie über alle Werte aggregiert wird. Wenn Sie beispielsweise keinen Formfaktor angeben, enthält der Datensatz Informationen zu Ladevorgängen, 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.

Messwert

Wir stellen Messwerte als statistische Aggregationen in Histogrammen, Perzentilen und Brüchen dar.

Gleitkommawerte werden auf vier Dezimalstellen gerundet. Hinweis: Die cumulative_layout_shift-Messwerte sind als String codierte Double-Werte. Sie werden daher nicht als Gleitkommazahlen betrachtet und im String mit zwei Dezimalstellen angegeben.

Histogramm

Wenn Messwerte in einem Histogramm dargestellt werden, zeigen wir die Prozentsätze der Seitenaufbauten an, die für diesen Messwert in bestimmte Bereiche fallen.

Ein Histogramm mit drei Buckets 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 Seitenaufbauten zwischen 0 ms und 1.000 ms lag. Die Einheiten des Messwerts sind in diesem Histogramm nicht enthalten. In diesem Fall gehen wir von Millisekunden aus.

Außerdem wurde bei 49,91 % der Seitenaufbauten ein Messwert zwischen 1.000 ms und 3.000 ms und bei 11,92 % ein Wert von mehr als 3.000 ms gemessen.

Perzentile

Messwerte können auch Perzentile enthalten, die für zusätzliche Analysen nützlich sein können. Wir melden bestimmte Messwerte am angegebenen Perzentil für diesen Messwert. Sie basieren auf dem vollständigen Satz verfügbarer Daten und nicht auf den endgültigen klassifizierten Daten. Daher stimmen sie nicht unbedingt mit einem interpolierten Perzentil überein, das auf dem endgültigen klassifizierten Histogramm basiert.

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

In diesem Beispiel wurden mindestens 75 % der Seitenaufbauten mit einem Messwert von <= 2063 gemessen.

Brüche

Die Brüche geben den Prozentsatz der Seitenaufbauten an, die auf eine bestimmte Weise gekennzeichnet werden können. In diesem Fall sind die Messwerte diese Labels.

Der Messwert form_factors besteht beispielsweise aus einem fractions-Objekt, das die Aufschlüsselung der Formfaktoren (oder Geräte) enthält, die von der jeweiligen Abfrage abgedeckt werden:

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

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

Messwerttypen

Zuordnung von BigQuery-Messwertnamen

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 darstellen. Beispiel:

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

So lassen sich die Daten besser nachvollziehen und Sie können sehen, ob sie für den jeweiligen Tag bereits aktualisiert wurden oder ob dieselben Daten wie am Vortag zurückgegeben werden.

Der Erfassungszeitraum ist auch in PageSpeed Insights verfügbar:

Außerdem werden in der collectionPeriod immer 28 Tage angezeigt, auch wenn die Daten nicht für die gesamten 28 Tage gelten (z. B. wenn eine Seite vor weniger als 28 Tagen veröffentlicht wurde). Der collectionPeriod ist der Zeitraum, über den die CrUX-Daten aggregiert wurden, nicht unbedingt der Zeitraum, den die Daten darstellen.

Beispielabfragen

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

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

Sie können beispielsweise curl mit der folgenden Befehlszeile aufrufen (ersetzen Sie 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, wenn ihr in der Abfrage die Property url anstelle von origin übergebt:

{
  "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
• interaction_to_next_paint
• largest_contentful_paint
• experimental_cumulative_layout_shift_with_softnavs
• experimental_first_contentful_paint_with_softnavs
• experimental_interaction_to_next_paint_with_softnavs
• experimental_largest_contentful_paint_with_softnavs
• experimental_navigation_types_with_softnavs
• experimental_time_to_first_byte
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• form_factors (wird nur gemeldet, wenn in der Anfrage kein formFactor angegeben ist)
• experimental_ad_count (nur für Seiten, die in Anzeigenmesswerten enthalten sind)
• experimental_ad_density (nur für Seiten, die in Anzeigenmesswerten enthalten sind)
• experimental_ad_cpu (nur für Seiten, die in Anzeigenmesswerten enthalten sind)
• experimental_ad_kilobytes (nur für Seiten, die in Anzeigenmesswerten enthalten sind)

Wenn kein formFactor-Wert angegeben ist, werden die Werte über alle Formfaktoren hinweg aggregiert.

Weitere Beispielabfragen finden Sie unter Chrome UX Report API verwenden.

Datenpipeline

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

Der gleitende Durchschnitt

Die Daten im Chrome UX Report sind ein gleitender 28-Tage-Durchschnitt der aggregierten Messwerte. Das bedeutet, dass die im Chrome UX Report angezeigten Daten immer die aggregierten Daten der letzten 28 Tage sind.

Das ist ähnlich wie beim CrUX-Dataset in BigQuery, in dem monatliche Berichte zusammengefasst werden.

Tägliche Updates

Die Daten werden täglich gegen 04:00 Uhr UTC aktualisiert. Es gibt kein Service Level Agreement für Aktualisierungszeiten. Die Aktualisierung erfolgt täglich im Rahmen der Möglichkeiten.

Schema

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

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:

{
  "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.
}

So fordern Sie beispielsweise die Largest Contentful Paint-Werte für die Desktop-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, die diesen Eintrag als eindeutig identifizieren.

{
  "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.
}

Messwerte

Ein metric ist ein Satz aggregierter Daten zur Nutzererfahrung für einen einzelnen Leistungsmesswert, z. B. „First Contentful Paint“. Sie kann ein zusammenfassendes Histogramm der realen Chrome-Nutzung als eine Reihe von bins, spezifische Perzentildaten (z. B. p75) oder beschriftete Brüche enthalten.

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

oder

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

Klasse

Ein bin ist ein diskreter Datenabschnitt, der sich vom Anfang bis zum Ende erstreckt, oder, wenn kein Ende angegeben ist, vom Anfang bis zur positiven Unendlichkeit.

Die Start- und Endwerte eines Behälters werden im Werttyp des Messwerts angegeben, den er darstellt. Beispielsweise wird „First Contentful Paint“ in Millisekunden gemessen und als Ganzzahl dargestellt. Daher werden für die Start- und Endtypen der Messwert-Bins int32-Werte verwendet. Die kumulative Layoutverschiebung wird jedoch in einheitenlosen Dezimalzahlen gemessen und als Dezimalzahl dargestellt, die als String codiert ist. Daher werden für die Messwert-Bins Strings als Werttyp verwendet.

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

Perzentile

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

{
  "P75": value
}

Brüche

Fractions enthält mit Labels versehene Bruchwerte, die zusammengenommen etwa 1 ergeben. Jedes Label beschreibt einen Seitenaufbau auf eine bestimmte Weise. Messwerte, die so dargestellt werden, können also als Erzeugung unterschiedlicher Werte anstelle von numerischen Werten betrachtet werden. Die Brüche geben an, wie oft ein bestimmter Wert gemessen wurde.

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

Ähnlich wie die Dichtewerte in Histogramm-Bins ist jeder fraction eine Zahl 0.0 <= value <= 1.0 und die Summe beträgt etwa 1,0.

UrlNormalization

Objekt, das die Normalisierungsaktionen darstellt, die zur Normalisierung einer URL durchgeführt wurden, um die Wahrscheinlichkeit einer erfolgreichen Suche zu erhöhen. Dies sind grundlegende, automatisierte Änderungen, die vorgenommen werden, wenn die Suche nach dem angegebenen url_pattern fehlschlagen würde. Komplexe Aktionen wie das Folgen von Weiterleitungen werden nicht verarbeitet.

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

Ratenlimits

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