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 Nutzerfreundlichkeitsmesswerte für einen bestimmten URI abgefragt werden, z. B. „Get metrics for the https://example.com origin.“ (Messwerte für den Ursprung abrufen).

CrUX-API-Schlüssel

Für die 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

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

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

Ursprung

Wenn es sich bei der Kennung um einen Ursprung handelt, 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 http://www.example.com-Ursprungs-Sitemap 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 geben eine bestimmte Datengruppe an, für die ein Datensatz aggregiert wird. Der Formfaktor PHONE gibt beispielsweise an, dass der Datensatz Informationen zu Ladevorgängen auf einem Mobilgerät enthält. Jede Dimension hat eine bestimmte Anzahl von Werten. Wenn Sie eine Dimension nicht angeben, werden die Daten implizit über alle Werte dieser Dimension hinweg aggregiert. 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, die der Endnutzer verwendet hat, um zur Seite zu gelangen. 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 4 Dezimalstellen gerundet. Die cumulative_layout_shift-Messwerte sind als String codierte Doubles und werden daher mit 2 Dezimalstellen im String angegeben.

Histogramm

Wenn Messwerte in einem Histogramm dargestellt werden, zeigen wir die Prozentsätze der Seitenaufrufe, die in bestimmte Bereiche für diesen Messwert 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 Seitenaufrufe zwischen 0 ms und 1.000 ms gemessen wurde. Die Einheiten des Messwerts sind nicht in diesem Histogramm enthalten. In diesem Fall gehen wir von Millisekunden aus.

Außerdem lag der Messwert bei 49,91% der Seitenaufbauten zwischen 1.000 ms und 3.000 ms und bei 11,92 % über 3.000 ms.

Perzentile

Messwerte können auch Perzentile enthalten, die für zusätzliche Analysen nützlich sein können. Wir melden bestimmte Messwerte für das angegebene 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 Seitenaufrufe mit dem Messwert <= 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 Messwertwerte diese Labels.

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

"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

Zuordnung von BigQuery-Messwertnamen

Erfassungszeitraum

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 können Sie die Daten besser verstehen und feststellen, 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"
  ]
}

Dies kann beispielsweise mit der folgenden Befehlszeile aus curl aufgerufen werden (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_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 keine formFactor angegeben ist)
• experimental_ad_count (wird nur für Seiten mit Anzeigenmesswerten gemeldet)
• experimental_ad_density (nur für Seiten, die in Anzeigenmesswerten enthalten sind)
• experimental_ad_cpu (wird nur für Seiten mit Anzeigenmesswerten gemeldet)
• experimental_ad_kilobytes (wird nur für Seiten mit Anzeigenmesswerten gemeldet)

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

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

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 zusammengefassten 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. Für die Aktualisierungszeiten gibt es kein Service Level Agreement. Die Aktualisierung erfolgt täglich auf Best-Effort-Basis.

Schema

Es gibt einen einzelnen 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 rufen Sie beispielsweise die Desktop-Werte für „Largest Contentful Paint“ für die Startseite der Chrome-Entwicklerdokumentation ab:

{
  "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 Datensatz 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 Web-Leistungsmesswert, z. B. „First Contentful Paint“. Es kann ein zusammenfassendes Histogramm der tatsächlichen Chrome-Nutzung als Reihe von bins, spezifische Perzentildaten (z. B. das 75. Perzentil) oder beschriftete Anteile enthalten.

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

oder

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

Klasse

Ein bin ist ein diskreter Datenabschnitt, der vom Start bis zum Ende reicht. Wenn kein Ende angegeben ist, reicht er vom Start bis ins Unendliche.

Die Start- und Endwerte eines Bereichs 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 erreicht wird.

{
  "P75": value
}

Brüche

Fractions enthält mit Labels versehene Brüche, die sich auf etwa 1 summieren. Jedes Label beschreibt einen Seitenaufbau auf eine bestimmte Weise. Messwerte, die auf diese Weise dargestellt werden, können also als eindeutige Werte anstelle von numerischen Werten betrachtet werden. Die Brüche geben an, wie oft ein bestimmter eindeutiger 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 zum Normalisieren einer URL ausgeführt wurden, um die Wahrscheinlichkeit einer erfolgreichen Suche zu erhöhen. Dies sind grundlegende, automatisierte Änderungen, die vorgenommen werden, wenn die Suche nach der 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 begrenzt. Sie 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. Es ist nicht möglich, für ein höheres Kontingent zu bezahlen.