Crux-geschiedenis-API

De CrUX History API biedt toegang met lage latentie tot zes maanden aan historische gegevens over de echte gebruikerservaring op pagina- en oorsprongsgranulariteit.

Probeer het!

Veelvoorkomend gebruiksscenario

Met de CrUX History API kunnen historische gegevens over de gebruikerservaring worden opgevraagd voor een specifieke URI, zoals 'Ontvang de historische UX-trends voor de oorsprong van https://example.com '.

De History API volgt dezelfde structuur als de dagelijkse CrUX API, behalve dat waarden in een array worden gegeven en sleutels worden gelabeld met meervoudige namen (bijvoorbeeld histogramTimeseries in plaats van histogram , of p75s in plaats van p75 ).

Crux API-sleutel

Net als bij de dagelijkse API is voor het gebruik van de Crux History API een Google Cloud API-sleutel vereist die is ingericht voor gebruik van Chrome UX Report API . Dezelfde sleutel kan worden gebruikt voor de dagelijkse en geschiedenis-API.

Een API-sleutel verkrijgen en gebruiken

Koop een sleutel

Of maak er een aan op de pagina Referenties .

Nadat u een API-sleutel heeft, kan uw toepassing de queryparameter key= yourAPIKey aan alle aanvraag-URL's toevoegen.

De API-sleutel kan veilig worden ingesloten in URL's; het heeft geen codering nodig.

Zie Voorbeeldquery's .

Gegevensmodel

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

Dossier

Een discreet stukje informatie over een pagina of site. Een record kan gegevens bevatten die specifiek zijn voor een identifier en voor een specifieke combinatie van dimensies. Een record kan gegevens bevatten voor een of meer metrieken.

Identificatiegegevens

Identifiers specificeren welke records moeten worden opgezocht. In Crux zijn deze identifiers webpagina's en websites.

Oorsprong

Wanneer de identifier een oorsprong is, worden alle aanwezige gegevens voor alle pagina's in die oorsprong samengevoegd. Stel bijvoorbeeld dat de oorsprong van http://www.example.com pagina's had zoals weergegeven in deze sitemap:

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

Dit zou betekenen dat bij het opvragen van het Chrome UX-rapport 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 zouden worden geretourneerd, samengevoegd, omdat dit alle pagina's onder die oorsprong zijn.

URL's

Wanneer de ID een URL is, worden alleen gegevens voor die specifieke URL geretourneerd. Kijk nog eens naar de oorspronkelijke sitemap 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 samengevoegd. De vormfactor PHONE geeft bijvoorbeeld aan dat het record informatie bevat over ladingen die op een mobiel apparaat hebben plaatsgevonden.

De CrUX History API is alleen beschikbaar geaggregeerd per vormfactordimensie. Dit is een algemene apparaatklasse, opgesplitst in PHONE , TABLET en DESKTOP .

Metrisch

We rapporteren statistieken in tijdreeksen van statistische aggregaties, dit zijn histogrammen, percentielen en breuken.

Histogrammen

Wanneer metrieken worden uitgedrukt in een histogramarray, vertegenwoordigt elke tijdreeksinvoer het percentage paginaladingen waarvoor de metriek in een interval viel, proportioneel aan alles. De gegevenspunten worden gepresenteerd in de volgorde van de verzamelperiodedata die ook door de API worden geretourneerd, waarbij het eerste punt de vroegste periode is en het laatste punt de meest recente verzamelperiode.

Een histogram met drie bakken voor een voorbeeldstatistiek ziet er als volgt uit:

{
  "histogramTimeseries": [
    {
      "start": 0,
      "end": 2500,
      "densities": [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]
    },
    {
      "start": 2500,
      "end": 4000,
      "densities": [0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527]
    },
    {
      "start": 4000,
      "densities": [0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285]
    }
  ],
}

Uit deze gegevens blijkt dat 91,90% van de geladen pagina's de voorbeeldstatistiekwaarde tussen 0 ms en 2500 ms heeft ervaren voor de eerste verzamelperiode in de geschiedenis, gevolgd door 92,03%, 91,94%... De eenheden van de metriek zijn niet opgenomen in dit histogram. in dit geval gaan we uit van milliseconden.

Bovendien ondervond 5,21% van de paginaladingen de voorbeeldstatistiekwaarde tussen 2500 ms en 4000 ms in de eerste verzamelperiode in de geschiedenis, en ondervond 2,88% van de paginaladingen een waarde groter dan 4000 ms in de eerste verzamelperiode in de geschiedenis.

Percentielen

Statistieken kunnen ook tijdreeksen van percentielen bevatten die nuttig kunnen zijn voor aanvullende analyses.

De gegevenspunten worden gepresenteerd in de volgorde van de verzamelperiodedata die ook door de API worden geretourneerd, waarbij het eerste punt de vroegste periode is en het laatste punt de meest recente verzamelperiode.

{
  "percentilesTimeseries": {
    "p75s": [1362, 1352, 1344, 1356, 1366, 1377]
  },
}

Deze percentielen kunnen specifieke metriekwaarden weergeven voor het gegeven percentiel voor die metriek. Ze zijn gebaseerd op de volledige set beschikbare gegevens en niet op de uiteindelijke opgeslagen gegevens. Ze komen dus niet noodzakelijkerwijs overeen met een geïnterpoleerd percentiel dat is gebaseerd op het uiteindelijke opgeslagen histogram.

Breuken

Metrieken kunnen worden uitgedrukt als tijdreeksen van gelabelde breuken; elk label beschrijft het laden van een pagina op een bepaalde manier. De gegevenspunten worden gepresenteerd in de volgorde van de verzamelperiodedata die ook door de API worden geretourneerd, waarbij het eerste punt de vroegste periode is en het laatste punt de meest recente verzamelperiode.

Voorbeeld:

{    
  "fractionTimeseries": {
    "desktop": {"fractions": [0.3195, 0.2115, 0.1421]},
    "phone": {"fractions": [0.6295, 0.7544, 0.8288]},
    "tablet": {"fractions": [0.051, 0.0341, 0.029]}
  }
}

In dit voorbeeld geeft het meest recente gegevenspunt aan dat 14,21% van de paginaladingen afkomstig was van desktops, en 82,88% van telefoons.

Typen metrische waarden

Omdat de CrUX History API dezelfde metrische waardetypen gebruikt, kunt u voor meer informatie de dagelijkse documentatie over metrische waardetypen van de CrUX API raadplegen.

Geschiktheid voor statistieken

Op basis van de geschiktheidscriteria komt een herkomst of URL mogelijk slechts in aanmerking voor enkele van de verzamelperiodes die worden gedekt door de CrUX History API. In deze gevallen retourneert de CrUX History API "NaN" voor de histogramTimeseries dichtheden en null voor de percentilesTimeseries voor de verzamelperioden die geen in aanmerking komende gegevens bevatten. De reden voor het verschil is dat de histogramdichtheden altijd getallen zijn, terwijl de percentielen getallen of tekenreeksen kunnen zijn (CLS gebruikt tekenreeksen, zelfs als ze op getallen lijken).

Als de tweede periode bijvoorbeeld geen geschikte gegevens bevatte, zou dit er als volgt uitzien:

{
  "histogramTimeseries": [
    {
      "start": 0,
      "end": 2500,
      "densities": [0.9190, "NaN", 0.9194, 0.9195, 0.9183, 0.9187]
    },
    {
      "start": 2500,
      "end": 4000,
      "densities": [0.0521, "NaN", 0.0518, 0.0518, 0.0526, 0.0527]
    },
    {
      "start": 4000,
      "densities": [0.0288, "NaN", 0.0286, 0.0285, 0.0290, 0.0285]
    }
  ],
  "percentilesTimeseries": {
    "p75s": [1362, null, 1344, 1356, 1366, 1377]
  },
}

Voor URL's of herkomsten die in de loop van de tijd wel of niet in aanmerking komen, ziet u mogelijk veel ontbrekende vermeldingen.

Verzamelperiodes

De CrUX History API bevat een collectionPeriods object met een array van firstDate en endDate velden die de begin- en einddatum van elk aggregatievenster vertegenwoordigen. Bijvoorbeeld:

    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }
    ]

Deze verzamelperioden zijn in oplopende volgorde en vertegenwoordigen de periode van elk van de gegevenspunten in de andere secties van het antwoord.

De History API wordt elke maandag bijgewerkt en bevat gegevens tot de voorgaande zaterdag (volgens de standaard vertraging van twee dagen). Het bevat de gegevens van de afgelopen 25 weken: één verzamelperiode per week.

Omdat elke verzamelperiode de verzamelde gegevens van de afgelopen 28 dagen bevat en de verzamelperioden per week zijn, betekent dit dat de verzamelperioden elkaar overlappen. Ze zijn vergelijkbaar met een voortschrijdend gemiddelde van gegevens, waarbij in elke volgende periode drie weken aan gegevens worden opgenomen en één week verschillend is.

Voorbeeldvragen

Query's worden verzonden als JSON-objecten met behulp van een POST-verzoek naar https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]" met querygegevens als JSON-object in de POST-tekst.

Let op het gebruik van queryHistoryRecord ter vervanging van de queryRecord van de dagelijkse CrUX API.

Een voorbeeldlichaam is:

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

Dit kan bijvoorbeeld vanuit curl worden aangeroepen met de volgende opdrachtregel (waarbij API_KEY wordt vervangen door uw sleutel):

curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?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 eigenschap in de query door te geven, in plaats van origin :

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

Als de eigenschap 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
  • navigation_types
  • round_trip_time
  • form_factors (alleen gerapporteerd als er geen formFactor is opgegeven in de aanvraag)

Als er geen formFactor waarde wordt opgegeven, worden de waarden voor alle vormfactoren samengevoegd.

Zie De handleiding voor de Crux History API gebruiken voor meer voorbeeldquery's.

Gegevenspijplijn

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

Het voortschrijdend gemiddelde

De gegevens in het Chrome UX-rapport zijn een voortschrijdend gemiddelde over 28 dagen van verzamelde statistieken. Dit betekent dat de gegevens die op een bepaald moment in het Chrome UX-rapport worden weergegeven, feitelijk gegevens zijn van de afgelopen 28 dagen bij elkaar opgeteld.

De History API bevat een aantal verzamelperiodes die elk deze 28 dagen beslaan. Omdat elke verzamelperiode de verzamelde gegevens van de afgelopen 28 dagen bevat en de verzamelperioden per week zijn, betekent dit dat de verzamelperioden elkaar overlappen. Ze zijn vergelijkbaar met een voortschrijdend gemiddelde van gegevens, waarbij in elke volgende periode drie weken aan gegevens worden opgenomen en één week verschillend is.

Wekelijkse updates

De History API wordt elke maandag rond 04:00 UTC bijgewerkt en bevat gegevens tot de voorgaande zaterdag (volgens de standaard vertraging van twee dagen). Het bevat gegevens van de afgelopen 25 weken (ongeveer 6 maanden), één verzamelperiode per week.

Er is geen Service Level Agreement voor updatetijden; het wordt elke dag op een best-effort-basis uitgevoerd.

Schema

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

HTTP-verzoek

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

De URL gebruikt de syntaxis van gRPC-transcodering .

Lichaam aanvragen

De CrUX History API gebruikt dezelfde verzoekteksten als de dagelijkse CrUX API .

Om bijvoorbeeld de desktop Largest Contentful Paint-waarden voor de web.dev-startpagina op te vragen:

{
  "origin": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

Reactie lichaam

Succesvolle verzoeken retourneren antwoorden met een record en urlNormalizationDetails in de volgende structuur:

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

Het antwoord op de verzoektekst in het vorige verzoek zou bijvoorbeeld kunnen zijn:

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogramTimeseries": [{
            "start": 0, "end": 2500, "densities": [
              0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187, ...
            ]
          }, {
            "start": 2500, "end": 4000, "densities": [
              0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527, ...
            ]
          },  {
            "start": 4000, "densities": [
              0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285, ...
            ]
          }
        ],
        "percentilesTimeseries": {
          "p75s": [
            1362, 1352, 1344, 1356, 1366, 1377, ...
          ]
        }
      }
    },
    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }, {
        ...
      }
    ]
  }
}

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 toegang te krijgen tot de site voor deze record.

Als de vormfactor niet is gespecificeerd, worden geaggregeerde gegevens over alle vormfactoren geretourneerd.

Unieveld url_ pattern . Het URL-patroon is de URL waarop de record van toepassing is. url_ pattern kan slechts een van de volgende zijn:
origin

string

Oorsprong specificeert de oorsprong waarvoor dit record bedoeld is.

Opmerking: Wanneer u een oorsprong opgeeft, worden gegevens voor ladingen onder deze oorsprong op alle pagina's samengevoegd tot gebruikerservaringsgegevens op oorsprongsniveau.

url

string

url specificeert een specifieke URL waarvoor deze record bedoeld is.

Opmerking: Wanneer u een url opgeeft, worden alleen de gegevens voor die specifieke URL samengevoegd.

Statistieken

Een metric is een reeks gebruikerservaringsgegevens voor één enkele webprestatiestatistiek, zoals de eerste inhoudsvolle verf. Het bevat een samenvattend histogram van Chrome-gebruik in de echte wereld, als een reeks bins .

{
  "histogramTimeseries": [
    {
      object (Bin)
    }
  ],
  "percentilesTimeseries": {
    object (Percentiles)
  }
}

of

"fractionTimeseries": {
  object (Fractions)
}
Velden
histogramTimeseries[]

object ( Bin )

Het tijdreekshistogram van gebruikerservaringen voor een statistiek. Het tijdreekshistogram zal ten minste één bin hebben en de dichtheid van alle bins zal optellen tot ~1.

Ontbrekende waarden voor die specifieke verzamelperiode worden gemarkeerd als "NaN" .

percentilesTimeseries

object ( Percentiles )

Algemene nuttige percentielen van de statistiek. Het waardetype voor de percentielen zal hetzelfde zijn als de waardetypen die voor de histogrambakken worden gegeven.

Ontbrekende waarden voor die specifieke verzamelperiode worden gemarkeerd als null .

fractionTimeseries

object ( Fractions )

Dit object bevat tijdreeksen van gelabelde breuken, die optellen tot ~1 per invoer.

Breuken worden afgerond op 4 decimalen.

Ontbrekende gegevens worden voor alle breuken uitgedrukt als `"NaN"`.

Bak

Een bin is een afzonderlijk deel van de gegevens dat zich uitstrekt van begin tot eind, of als er geen einde is opgegeven, van begin tot positieve oneindigheid.

De begin- en eindwaarden van een bak worden gegeven in het waardetype van de metriek die deze vertegenwoordigt. De eerste contentful paint wordt bijvoorbeeld gemeten in milliseconden en weergegeven als ints, daarom zullen de metrische bins int32s gebruiken voor de begin- en eindtypen. De cumulatieve lay-outverschuiving wordt echter gemeten in eenheidsloze decimalen en wordt weergegeven als een decimaal gecodeerd als een tekenreeks. Daarom zullen de metrische bins tekenreeksen gebruiken voor het waardetype.

{
  "start": value,
  "end": value,
  "densities": [number, number, number...etc.]
}
Velden
start

(integer | string)

Start is het begin van de gegevensbak.

end

(integer | string)

Einde is het einde van de gegevensbak. Als end niet is ingevuld, heeft de bak geen einde en is deze geldig van start tot +inf.

densities

array[number]

Een tijdreeks van het percentage gebruikers dat de waarde van deze opslaglocatie voor de gegeven statistiek heeft ervaren.

Dichtheden worden afgerond op 4 decimalen.

Percentielen

Percentiles bevatten synthetische waarden van een metriek bij een bepaald statistisch percentiel. Deze worden gebruikt voor het schatten van de waarde van een statistiek zoals ervaren door een percentage van de gebruikers van het totale aantal gebruikers.

{
  "P75": value
}
Velden
p75s

array[(integer | string)]

Tijdreeksen van de waarden waarbij 75% van de pagina's werd geladen, ondervonden dat de gegeven statistiek op of minder dan deze waarde lag.

Breuken

Fractions bevatten tijdreeksen van gelabelde breuken die optellen tot ~1, per invoer. Elk label beschrijft op de een of andere manier het laden van een pagina, dus statistieken die op deze manier worden weergegeven, kunnen worden gezien als afzonderlijke waarden in plaats van numerieke waarden, en de breuken geven aan hoe vaak een bepaalde afzonderlijke waarde is gemeten.

{
  "label_1": { "fractions": array[fraction]},
  "label_1": { "fractions": array[fraction]},
  ...
  "label_n": { "fractions": array[fraction]}
}

Net als de dichtheidswaarden in histogramvakken is elke fraction een getal 0.0 <= value <= 1.0 , en opgeteld is dat ~1.0. Als de metriek niet beschikbaar is voor een bepaalde verzamelperiode, is de overeenkomstige invoer 'NaN' in alle reeksen breuken.

Velden
p75s

array[(integer | string)]

Tijdreeksen van de waarden waarbij 75% van de pagina's laadden, waarbij de gegeven statistiek op of lager dan deze waarde werd ervaren.

UrlNormalisatie

Object dat de normalisatieacties vertegenwoordigt die zijn ondernomen om een ​​URL te normaliseren om een ​​grotere kans op een succesvolle zoekopdracht te bereiken. Dit zijn eenvoudige geautomatiseerde wijzigingen die worden doorgevoerd wanneer het opzoeken van het opgegeven url_pattern zou mislukken. Complexe acties zoals het volgen van omleidingen worden niet afgehandeld.

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

string

De oorspronkelijk aangevraagde URL voorafgaand aan eventuele normalisatieacties.

normalizedUrl

string

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

Tarieflimieten

De CrUX History API deelt dezelfde limiet met de CrUX API voor 150 zoekopdrachten per minuut per Google Cloud-project voor beide API's, die kosteloos worden aangeboden. Deze limiet en uw huidige verbruik kunt u zien in de Google Cloud Console . Dit genereuze quotum zou voldoende moeten zijn voor de overgrote meerderheid van de gebruiksscenario's en het is niet mogelijk om voor een verhoogd quotum te betalen.