CrUX API

De CrUX API biedt toegang met lage vertraging tot verzamelde gegevens over de gebruikerservaring van echte gebruikers op pagina- en oorsprongsniveau.

Probeer het eens.

Veelvoorkomende toepassing

Met de CrUX API kun je statistieken over de gebruikerservaring opvragen voor een specifieke URI, zoals 'Statistieken ophalen voor de oorsprong https://example.com'.

CrUX API-sleutel

Voor het gebruik van de CrUX API is een Google Cloud API-sleutel vereist die is ingesteld voor Chrome UX Report API-gebruik.

Een API-sleutel verkrijgen en gebruiken

Een sleutel krijgen

Je kunt er ook een maken op de pagina Inloggegevens.

Nadat je een API-sleutel hebt, kan je app de queryparameter key=yourAPIKey toevoegen aan alle verzoek-URL's.

De API-sleutel is veilig om in te sluiten in URL's. Je hoeft deze niet te coderen.

Ga naar Voorbeeldquery's.

Gegevensmodel

In dit gedeelte wordt de structuur van gegevens in verzoeken en reacties beschreven.

Opnemen

Een afzonderlijk stukje informatie over een pagina of site. Een record kan gegevens bevatten die specifiek zijn voor een ID en voor een specifieke combinatie van dimensies. Een record kan gegevens voor een of meer statistieken bevatten.

ID's

ID's geven aan welke records moeten worden opgezocht. In CrUX zijn deze ID's webpagina's en websites.

Origin

Als de ID een oorsprong is, worden alle gegevens die aanwezig zijn voor alle pagina's in die oorsprong, samengevoegd. Stel dat de oorsprong http://www.example.com pagina's heeft die zijn ingedeeld volgens deze sitemap:

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

Dit betekent dat als je een query uitvoert op het Chrome UX Report met de oorsprong ingesteld op http://www.example.com, gegevens voor http://www.example.com/, http://www.example.com/foo.html en http://www.example.com/bar.html worden geretourneerd, samengevoegd, omdat dit allemaal pagina's onder die oorsprong zijn.

URL's

Als de ID een URL is, worden alleen gegevens voor die specifieke URL geretourneerd. We kijken opnieuw naar de sitemap van de oorsprong http://www.example.com:

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

Als de ID is ingesteld op URL met de waarde http://www.example.com/foo.html, worden alleen gegevens voor die pagina geretourneerd.

Afmetingen

Dimensies geven een specifieke groep gegevens aan waarvoor een record wordt verzameld. Een vormfactor van PHONE geeft bijvoorbeeld aan dat de record informatie bevat over laden die hebben plaatsgevonden op een mobiel apparaat. Elke dimensie heeft een bepaald aantal waarden. Als u die dimensie niet opgeeft, betekent dit impliciet dat de dimensie wordt samengevoegd voor alle waarden. Als je bijvoorbeeld geen vormfactor opgeeft, geeft dit aan dat de record informatie bevat over laadacties die op een vormfactor hebben plaatsgevonden.

Vormfactor

De apparaatklasse die de eindgebruiker heeft gebruikt om naar de pagina te navigeren. Dit is een algemene apparaatklasse die is onderverdeeld in PHONE, TABLET en DESKTOP.

Statistiek

We rapporteren statistieken als statistische aggregaties, in histogrammen, percentielen en fracties.

Kommagetallen worden afgerond op 4 decimalen (de cumulative_layout_shift-statistieken zijn doubles die zijn gecodeerd als een tekenreeks, dus worden niet beschouwd als kommagetallen en worden gerapporteerd met 2 decimalen in de tekenreeks).

Histogram

Als statistieken worden uitgedrukt in een histogram, tonen we de percentages van pagina's die worden geladen binnen bepaalde bereiken voor die statistiek.

Een histogram met 3 groepen voor een voorbeeldstatistiek ziet er zo uit:

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

Deze gegevens geven aan dat voor 38,18% van de paginaladingen de voorbeeldstatistiek is gemeten tussen 0 ms en 1000 ms. De eenheden van de statistiek zijn niet opgenomen in dit histogram. In dit geval gaan we uit van milliseconden.

Daarnaast had 49,91% van de pagina's die werden geladen een statistiekwaarde tussen 1000 ms en 3000 ms en had 11,92% een waarde van meer dan 3000 ms.

Percentielen

Statistieken kunnen ook percentielen bevatten die nuttig kunnen zijn voor aanvullende analyse. We rapporteren specifieke statistiekwaarden op het aangegeven percentiel voor die statistiek. Ze zijn gebaseerd op de volledige set beschikbare gegevens en niet op de uiteindelijke gebinde gegevens. Ze komen dus niet noodzakelijkerwijs overeen met een geïnterpoleerd percentiel dat is gebaseerd op het uiteindelijke gebinde histogram.

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

In dit voorbeeld is minstens 75% van de pagina's geladen met een statistiekwaarde van <= 2063.

Breuken

Breuken geven de percentages van paginaweergaven aan die op een bepaalde manier kunnen worden gelabeld. In dit geval zijn de statistiekwaarden deze labels.

De statistiek form_factors bestaat bijvoorbeeld uit een fractions-object met de uitsplitsing van vormfactoren (of apparaten) die de betreffende query dekt:

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

In dit geval is 3,77% van de pagina's geladen op een desktop, 2,88% op een tablet en 93,35% op een telefoon, wat in totaal 100% is.

Typen statistiekwaarden

Naam van CrUX API-statistiek Gegevenstype Metrische eenheden Statistische aggregaties Documentatie
cumulative_layout_shift Double met 2 decimalen gecodeerd als tekenreeks zonder eenheid histogram met 3 klassen, percentielen met p75 CLS
interaction_to_next_paint int milliseconden histogram met 3 klassen, percentielen met p75 INP
largest_contentful_paint int milliseconden histogram met 3 klassen, percentielen met p75 LCP
experimental_cumulative_layout_shift_with_softnavs Double met 2 decimalen gecodeerd als tekenreeks zonder eenheid histogram met 3 klassen, percentielen met p75 Blog
experimental_interaction_to_next_paint_with_softnavs int milliseconden histogram met 3 klassen, percentielen met p75 Blog
experimental_largest_contentful_paint_with_softnavs int milliseconden histogram met 3 klassen, percentielen met p75 Blog
first_contentful_paint int milliseconden histogram met 3 klassen, percentielen met p75 FCP
experimental_first_contentful_paint_with_softnavs int milliseconden histogram met 3 klassen, percentielen met p75 Blog
experimental_time_to_first_byte int milliseconden histogram met 3 klassen, percentielen met p75 TTFB
form_factors Dubbel item met 4 decimalen procent toewijzing van vormfactor aan fractie Vormfactoren
navigation_types Dubbel item met 4 decimalen procent toewijzing van navigatietype aan fractie Navigatietypen
experimental_navigation_types_with_softnavs Dubbel item met 4 decimalen procent toewijzing van navigatietype aan fractie Blog
round_trip_time int milliseconden histogram met 3 klassen, percentielen met p75 RTT-statistiek
largest_contentful_paint_resource_type Dubbel item met 4 decimalen procent toewijzing van navigatietype aan fractie LCP-brontypen
largest_contentful_paint_image_time_to_first_byte int milliseconden percentielen met p75 LCP-subonderdelen
largest_contentful_paint_image_resource_load_delay int milliseconden percentielen met p75 LCP-subonderdelen
largest_contentful_paint_image_resource_load_duration int milliseconden percentielen met p75 LCP-subonderdelen
largest_contentful_paint_image_element_render_delay int milliseconden percentielen met p75 LCP-subonderdelen
experimental_ad_count Dubbel item met 2 decimalen zonder eenheid alleen p75 Aantal advertenties
experimental_ad_density Double met 2 decimalen zonder eenheid alleen p75 Advertentiedichtheid
experimental_ad_cpu int milliseconden alleen p75 Advertentiegewicht: CPU
experimental_ad_kilobytes int KB alleen p75 Advertentiegewicht: netwerk

Toewijzing van BigQuery-statistieknamen

Naam van CrUX API-statistiek Naam van BigQuery-statistiek
cumulative_layout_shift layout_instability.cumulative_layout_shift
first_contentful_paint first_contentful_paint
interaction_to_next_paint interaction_to_next_paint
largest_contentful_paint largest_contentful_paint
experimental_time_to_first_byte experimental.time_to_first_byte
experimental_cumulative_layout_shift_with_softnavs experimental.cumulative_layout_shift_with_softnavs
experimental_first_contentful_paint_with_softnavs n/a
experimental_interaction_to_next_paint_with_softnavs experimental.interaction_to_next_paint_with_softnavs
experimental_largest_contentful_paint_with_softnavs experimental.largest_contentful_paint_with_softnavs
navigation_types navigation_types
experimental_navigation_types_with_softnavs n/a
form_factors N.v.t.
round_trip_time round_trip_time
largest_contentful_paint_resource_type N.v.t.
largest_contentful_paint_image_time_to_first_byte N.v.t.
largest_contentful_paint_image_resource_load_delay N.v.t.
largest_contentful_paint_image_resource_load_duration N.v.t.
largest_contentful_paint_image_element_render_delay N.v.t.
experimental_ad_count n/a
experimental_ad_density n/a
experimental_ad_cpu n/a
experimental_ad_kilobytes n/a

Verzamelperiode

Sinds oktober 2022 bevat de CrUX API een collectionPeriod-object met de velden firstDate en endDate die de begin- en einddatum van de verzamelperiode vertegenwoordigen. Voorbeeld:

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

Zo krijg je meer inzicht in de gegevens en of deze al zijn geüpdatet voor die dag of dat dezelfde gegevens als gisteren worden geretourneerd.

De verzamelperiode is ook beschikbaar in PageSpeed Insights:

PageSpeed Insights toont de datums van de verzamelperiode in een tooltip.
Datums van de verzamelperiode in PageSpeed Insights.

Daarnaast toont de collectionPeriod altijd 28 dagen, zelfs als de gegevens niet voor de volledige 28 dagen zijn (bijvoorbeeld als een pagina minder dan 28 dagen geleden is gelanceerd). De collectionPeriod is de periode waarin de CrUX-gegevens zijn verzameld, niet per se de periode die de gegevens vertegenwoordigen.

Voorbeelden van zoekopdrachten

Query's worden ingediend als json-objecten via een POST-verzoek aan https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" met querygegevens als json-object in de POST-hoofdtekst:

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

Dit kan bijvoorbeeld worden aangeroepen vanuit curl met de volgende opdrachtregel (vervang API_KEY door je sleutel):

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

Gegevens op paginaniveau zijn beschikbaar via de API door een url-property door te geven in de query in plaats van origin:

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

Als de property metrics niet is ingesteld, worden alle beschikbare statistieken geretourneerd:

  • 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 (wordt alleen gerapporteerd als er geen formFactor is opgegeven in het verzoek)
  • experimental_ad_count (alleen gerapporteerd voor pagina's die zijn opgenomen in advertentiestatistieken)
  • experimental_ad_density (alleen gerapporteerd voor pagina's die zijn opgenomen in advertentiestatistieken)
  • experimental_ad_cpu (alleen gerapporteerd voor pagina's die zijn opgenomen in advertentiestatistieken)
  • experimental_ad_kilobytes (alleen gerapporteerd voor pagina's die zijn opgenomen in advertentiestatistieken)

Als er geen formFactor-waarde wordt ingevoerd, worden de waarden verzameld voor alle vormfactoren.

Ga naar De Chrome UX Report API gebruiken voor meer voorbeeldquery's.

Data pipeline

De CrUX-dataset wordt verwerkt via een pipeline om de gegevens te consolideren, te verzamelen en te filteren voordat ze beschikbaar komen via de API.

Het voortschrijdend gemiddelde

De gegevens in het Chrome UX Report zijn een voortschrijdend gemiddelde van 28 dagen van verzamelde statistieken. Dit betekent dat de gegevens die op een bepaald moment in het Chrome UX Report worden getoond, eigenlijk gegevens zijn voor de afgelopen 28 dagen, samengevoegd.

Dit is vergelijkbaar met de manier waarop de CrUX-dataset op BigQuery maandelijkse rapporten verzamelt.

Dagelijkse updates

De gegevens worden dagelijks rond 04:00 uur UTC geüpdatet. Er is geen serviceovereenkomst voor updatetijden. De update wordt elke dag op basis van de beste inspanning uitgevoerd.

Schema

Er is één eindpunt voor de CrUX API dat POST HTTP-verzoeken accepteert. De API retourneert een record met een of meer metrics die overeenkomen met prestatiegegevens over de aangevraagde oorsprong of pagina.

HTTP-verzoek

POST https://chromeuxreport.googleapis.com/v1/records:queryRecord

De URL gebruikt de syntaxis van gRPC-transcodering.

Hoofdtekst van verzoek

De verzoektekst moet gegevens bevatten met de volgende structuur:

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

enum (FormFactor)

De vormfactor is een querydimensie die de apparaatklasse aangeeft waartoe de gegevens van de record moeten behoren.

Dit veld gebruikt de waarden DESKTOP, PHONE of TABLET.

Opmerking: Als er geen vormfactor is opgegeven, wordt er een speciale record met verzamelde gegevens voor alle vormfactoren geretourneerd.

metrics[]

string

De statistieken die in de reactie moeten worden opgenomen. Als er geen worden opgegeven, worden alle gevonden statistieken geretourneerd.

Toegestane waarden: ["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_time_to_first_byte", "experimental_navigation_types_with_softnavs", "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", "experimental_ad_count", "experimental_ad_density", "experimental_ad_cpu", "experimental_ad_kilobytes"]

Unieveld url_pattern. De url_pattern is de belangrijkste ID voor een recordzoekopdracht. Dit kan maar een van de volgende zijn:
origin

string

De url_pattern 'origin' verwijst naar een URL-patroon dat de oorsprong van een website is.

Voorbeelden: "https://example.com", "https://cloud.google.com"

url

string

De url_pattern url verwijst naar een URL-patroon dat een willekeurige URL is.

Voorbeelden: "https://example.com/, https://cloud.google.com/why-google-cloud/"

Zo vraag je bijvoorbeeld de Largest Contentful Paint-waarden voor desktop aan voor de homepage van de documentatie voor Chrome-ontwikkelaars:

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

Tekstgedeelte van reactie

Succesvolle verzoeken retourneren reacties met een record-object en urlNormalizationDetails in de volgende structuur:

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

De reactie op de verzoektekst in het vorige verzoek kan bijvoorbeeld zijn:

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

Sleutel

Key definieert alle dimensies die deze record als uniek identificeren.

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

enum (FormFactor)

De vormfactor is de apparaatklasse die alle gebruikers hebben gebruikt om de site voor deze record te openen.

Als de vormfactor niet is opgegeven, worden verzamelde gegevens voor alle vormfactoren geretourneerd.

Unieveld url_pattern. Het URL-patroon is de URL waarop de record van toepassing is. url_pattern kan maar een van de volgende zijn:
origin

string

origin geeft de oorsprong aan waarvoor deze record is bedoeld.

Opmerking: Als je een origin invoert, worden gegevens voor laadacties onder deze oorsprong voor alle pagina's verzameld in gegevens over de gebruikerservaring op oorsprongsniveau.

url

string

url geeft een specifieke URL aan waarvoor deze record is bedoeld.

Opmerking: Als je een url invoert, worden alleen gegevens voor die specifieke URL verzameld.

Statistieken

Een metric is een set verzamelde gegevens over de gebruikerservaring voor één statistiek voor webprestaties, zoals First Contentful Paint. Het kan een overzichtshistogram van het echte Chrome-gebruik bevatten als een reeks bins, specifieke percentielgegevens (zoals de p75) of gelabelde fracties.

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

of

{
  "fractions": {
    object (Fractions)
  }
}
Velden
histogram[]

object (Bin)

Het histogram van gebruikerservaringen voor een statistiek. Het histogram heeft minstens één bin en de dichtheden van alle bins tellen op tot ~1.

percentiles

object (Percentiles)

Veelgebruikte nuttige percentielen van de statistiek. Het waardetype voor de percentielen is hetzelfde als de waardetypen die zijn opgegeven voor de histogramklassen.

fractions

object (Fractions)

Dit object bevat gelabelde fracties die samen ongeveer 1 vormen.

Breuken worden afgerond op 4 decimalen.

Ruimte

Een bin is een afzonderlijk deel van de gegevens dat van begin tot eind loopt, of als er geen einde is opgegeven, van begin tot positief oneindig.

De begin- en eindwaarden van een bin worden gegeven in het waardetype van de statistiek die de bin vertegenwoordigt. De eerste weergave met content wordt bijvoorbeeld gemeten in milliseconden en weergegeven als gehele getallen. Daarom gebruiken de statistiekbakken int32's voor de begin- en eindtypen. Cumulative Layout Shift wordt gemeten in decimalen zonder eenheid en wordt weergegeven als een decimaal gecodeerd als een tekenreeks. Daarom gebruiken de statistiekbakken tekenreeksen voor het waardetype.

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

(integer | string)

Start is het begin van de gegevensbak.

end

(integer | string)

Einde is het einde van de gegevensbak. Als er geen einddatum is ingevuld, heeft de periode geen einddatum en is deze geldig vanaf de startdatum tot +inf.

density

number

Het percentage gebruikers dat de waarde van deze container heeft ervaren voor de opgegeven statistiek.

Dichtheden worden afgerond op 4 decimalen.

Percentielen

Percentiles bevat synthetische waarden van een statistiek op een bepaald statistisch percentiel. Deze worden gebruikt om de waarde van een statistiek te schatten zoals die wordt ervaren door een percentage van de gebruikers van het totale aantal gebruikers.

{
  "P75": value
}
Velden
p75

(integer | string)

75% van de pagina's die zijn geladen, had de aangegeven statistiek op of onder deze waarde.

Breuken

Fractions bevat gelabelde breuken die samen ongeveer 1 zijn. Elk label beschrijft op een bepaalde manier het laden van een pagina. Statistieken die op deze manier worden weergegeven, kunnen dus worden beschouwd als statistieken die verschillende waarden produceren in plaats van numerieke waarden. De fracties geven aan hoe vaak een bepaalde afzonderlijke waarde is gemeten.

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

Net als de dichtheidswaarden in histogramklassen is elke fraction een getal 0.0 <= value <= 1.0 en is de som ongeveer 1,0.

UrlNormalization

Object dat de normalisatieacties vertegenwoordigt die zijn uitgevoerd om een URL te normaliseren, zodat de kans op een succesvolle zoekopdracht groter is. Dit zijn eenvoudige, geautomatiseerde wijzigingen die worden doorgevoerd als het opzoeken van de verstrekte url_pattern mislukt. Complexe acties, zoals omleidingen volgen, worden niet verwerkt.

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

string

De oorspronkelijke aangevraagde URL vóór normalisatieacties.

normalizedUrl

string

De URL na normalisatieacties. Dit is een geldige URL voor gebruikerservaring die redelijkerwijs kan worden opgezocht.

Tarieflimieten

De CrUX API is beperkt tot 150 query's per minuut per Google Cloud-project. Dit wordt kosteloos aangeboden. Deze limiet en je huidige gebruik kun je bekijken in de Google Cloud Console. Dit royale quotum is voldoende voor de meeste toepassingen. Het is niet mogelijk om te betalen voor een hoger quotum.