De CrUX API biedt toegang met lage vertraging tot verzamelde gegevens over de gebruikerservaring van echte gebruikers op pagina- en oorsprongsniveau.
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 krijgenJe 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:
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_shiftfirst_contentful_paintinteraction_to_next_paintlargest_contentful_paintexperimental_cumulative_layout_shift_with_softnavsexperimental_first_contentful_paint_with_softnavsexperimental_interaction_to_next_paint_with_softnavsexperimental_largest_contentful_paint_with_softnavsexperimental_navigation_types_with_softnavsexperimental_time_to_first_bytelargest_contentful_paint_resource_typelargest_contentful_paint_image_time_to_first_bytelargest_contentful_paint_image_resource_load_delaylargest_contentful_paint_image_resource_load_durationlargest_contentful_paint_image_element_render_delaynavigation_typesround_trip_timeform_factors(wordt alleen gerapporteerd als er geenformFactoris 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 |
De vormfactor is een querydimensie die de apparaatklasse aangeeft waartoe de gegevens van de record moeten behoren. Dit veld gebruikt de waarden Opmerking: Als er geen vormfactor is opgegeven, wordt er een speciale record met verzamelde gegevens voor alle vormfactoren geretourneerd. |
metrics[] |
De statistieken die in de reactie moeten worden opgenomen. Als er geen worden opgegeven, worden alle gevonden statistieken geretourneerd. Toegestane waarden: |
Unieveld url_. De url_pattern is de belangrijkste ID voor een recordzoekopdracht. Dit kan maar een van de volgende zijn: |
|
origin |
De Voorbeelden: |
url |
De Voorbeelden: |
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 |
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_. Het URL-patroon is de URL waarop de record van toepassing is. url_ kan maar een van de volgende zijn: |
|
origin |
Opmerking: Als je een |
url |
Opmerking: Als je een |
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[] |
Het histogram van gebruikerservaringen voor een statistiek. Het histogram heeft minstens één bin en de dichtheden van alle bins tellen op tot ~1. |
percentiles |
Veelgebruikte nuttige percentielen van de statistiek. Het waardetype voor de percentielen is hetzelfde als de waardetypen die zijn opgegeven voor de histogramklassen. |
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 |
Start is het begin van de gegevensbak. |
end |
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 |
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 |
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 |
De oorspronkelijke aangevraagde URL vóór normalisatieacties. |
normalizedUrl |
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.