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

Of maak er een 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 kan veilig worden ingesloten in URL's. Er is geen codering nodig.

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 het Chrome UX Report opvraagt 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 identificeren een specifieke groep gegevens waartegen een record wordt verzameld, bijvoorbeeld een vormfactor van PHONE geeft aan dat de record informatie bevat over belastingen die op een mobiel apparaat hebben plaatsgevonden. Elke dimensie heeft een bepaald aantal waarden. Als u die dimensie niet opgeeft, wordt de dimensie samengevoegd voor alle waarden. Als je bijvoorbeeld geen vormfactor opgeeft, geeft dit aan dat de record informatie bevat over laadacties die hebben plaatsgevonden op een vormfactor.

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 rapportagestatistieken als statistische aggregaties, in histogrammen, percentielen en fracties.

Waarden met zwevende komma's worden afgerond op 4 decimalen (de statistieken van cumulative_layout_shift zijn doubles die als tekenreeks zijn gecodeerd, dus worden niet beschouwd als zwevende komma's en worden gerapporteerd op 2 decimalen binnen de tekenreeks).

Histogram

Als statistieken in een histogram worden getoond, tonen we de percentages van paginaloads die in bepaalde bereiken voor die statistiek vallen.

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 pagina's die worden geladen,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 statistische waarden 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 het laden van pagina's gemeten met de statistiekwaarde <= 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% oplevert.

Typen statistiekwaarden

Toewijzing van BigQuery-statistieknamen

Verzamelperiode

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

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

Zo krijgt u 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 met een POST-verzoek naar https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" met querygegevens als json-object in de POST-body:

{
  "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_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 ingevoerd 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 formFactorwaarde is ingevoerd, worden de waarden verzameld voor alle vormfactoren.

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

Gegevenspipeline

De CrUX-dataset wordt verwerkt via een pijplijn om de gegevens samen te voegen, 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 over 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 van de afgelopen 28 dagen die zijn verzameld.

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

Dagelijkse updates

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

Schema

Er is één eindpunt voor de CrUX API dat POST HTTP-verzoeken accepteert. De API retourneert een record die een of meer metrics bevat die overeenkomen met prestatiegegevens over de gevraagde 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.
}

Zo vraag je bijvoorbeeld de Largest Contentful Paint-waarden voor desktop op 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.
}

Statistieken

Een metric is een set verzamelde gegevens over de gebruikerservaring voor één statistiek voor webprestaties, zoals First Contentful Paint. Het kan een samenvattend histogram van het Chrome-gebruik in de echte wereld bevatten als een reeks bins, specifieke percentielgegevens (zoals het 75e percentiel) of gelabelde breuken.

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

of

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

Ruimte

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

De begin- en eindwaarden van een bak worden gegeven in het waardetype van de statistiek die de bak 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. Cumulatieve lay-outverschuiving wordt gemeten in eenheidsloze decimalen en wordt getoond als een decimaal getal dat is gecodeerd als een tekenreeks. Daarom gebruiken de statistiekbakken tekenreeksen voor het waardetype.

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

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
}

Breuken

Fractions bevat gelabelde breuken die samen ongeveer 1 zijn. Elk label beschrijft een pagina-laadtijd op een bepaalde manier. Statistieken die op deze manier worden getoond, kunnen dus worden beschouwd als het produceren van afzonderlijke waarden in plaats van numerieke waarden. De breuken 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 en de kans op een geslaagde zoekopdracht te vergroten. Dit zijn basiswijzigingen die automatisch worden doorgevoerd als we weten dat het opzoeken van de verstrekte url_pattern mislukt. Complexe acties, zoals het volgen van omleidingen, worden niet verwerkt.

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

Tarieflimieten

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