CrUX Geçmişi API'si

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Yayınlanma tarihi: 7 Şubat 2023, Son güncelleme: 11 Nisan 2025

CrUX Geçmişi API'si, sayfa ve kaynak ayrıntı düzeyinde altı aylık geçmiş gerçek kullanıcı deneyimi verilerine düşük gecikmeli erişim sağlar.

Deneyin.

Yaygın kullanım alanı

CrUX Geçmişi API'si, belirli bir URI için geçmiş kullanıcı deneyimi metriklerinin sorgulanması olanağı sunar (ör. "https://example.com kaynağının geçmiş kullanıcı deneyimi trendlerini alın").

Geçmiş API'si, günlük CrUX API ile aynı yapıya sahiptir. Tek fark, değerlerin bir dizede verilmesi ve anahtarların çoğul isimlerle etiketlenmesidir (örneğin, histogram yerine histogramTimeseries veya p75 yerine p75s).

CrUX API anahtarı

Günlük API gibi, CrUX History API'yi kullanmak için Chrome UX Report API kullanımı için hazırlanmış bir Google Cloud API anahtarı gerekir. Günlük ve geçmiş API'si için aynı anahtar kullanılabilir.

API anahtarı edinme ve kullanma

veya Kimlik Bilgileri sayfasında bir tane oluşturun.

API anahtarınız olduktan sonra uygulamanız, key=yourAPIKey sorgu parametresini tüm istek URL'lerine ekleyebilir.

API anahtarı, URL'lere yerleştirmek için güvenlidir; herhangi bir kodlama yapmanız gerekmez.

Örnek sorgular bölümüne bakın.

Veri modeli

Bu bölümde, isteklerdeki ve yanıtlardaki verilerin yapısı ayrıntılı olarak açıklanmaktadır.

Kaydet

Bir sayfa veya siteyle ilgili ayrı bir bilgi parçası. Bir kayıtta, bir tanımlayıcıya ve belirli bir boyut kombinasyonuna özgü veriler bulunabilir. Bir kayıtta bir veya daha fazla metriğe ait veriler bulunabilir.

Tanımlayıcılar

Tanımlayıcılar, hangi kayıtların aranacağını belirtir. CrUX'ta bu tanımlayıcılar web sayfaları ve web siteleridir.

Köken

Tanımlayıcı bir kaynak olduğunda, söz konusu kaynaktaki tüm sayfalar için mevcut olan tüm veriler birlikte toplanır. Örneğin, http://www.example.com kaynağının şu site haritasında belirtilen sayfaları olduğunu varsayalım:

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

Bu, Chrome UX Report'u kaynak http://www.example.com olarak ayarlayarak sorgularken http://www.example.com/, http://www.example.com/foo.html ve http://www.example.com/bar.html sayfalarına ait verilerin, bu kaynak altındaki tüm sayfalar oldukları için birlikte toplanmış şekilde döndürüleceği anlamına gelir.

URL'ler

Tanımlayıcı bir URL olduğunda yalnızca söz konusu URL'ye ait veriler döndürülür. http://www.example.com kaynak site haritasına tekrar bakalım:

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

Tanımlayıcı, http://www.example.com/foo.html değerine sahip URL olarak ayarlanırsa yalnızca ilgili sayfanın verileri döndürülür.

Boyutlar

Boyutlar, bir kaydın birleştirildiği belirli bir veri grubunu tanımlar. Örneğin, PHONE biçim faktörü, kaydın mobil cihazda gerçekleşen yüklemelerle ilgili bilgiler içerdiğini gösterir.

Form Faktörü

CrUX Geçmişi API'si yalnızca form faktörü boyutuna göre toplanmış olarak kullanılabilir. Bu, PHONE, TABLET ve DESKTOP olarak ayrılmış genel bir cihaz sınıfıdır.

Metrik

Metrikleri, histogramlar, yüzde dilimleri ve kesirler olan istatistiksel toplama zaman serilerinde raporlarız.

Histogramlar

Metrikler bir histogram dizisiyle ifade edildiğinde her zaman serisi girişi, metriğin bir aralığa düştüğü sayfa yüklemelerinin yüzdesini tümüne orantılı olarak temsil eder. Veri noktaları, API tarafından da döndürülen veri toplama dönemi tarihlerinin sırasına göre sunulur. İlk nokta en erken dönem, son nokta ise en son veri toplama dönemidir.

Örnek bir metrik için üç binlik bir histogram aşağıdaki gibi görünür:

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

Bu veriler, sayfa yüklemelerinin% 91,90'ının geçmişteki ilk toplama döneminde 0 ms ile 2.500 ms arasında örnek metrik değerini yaşadığını, ardından %92,03, %91,94... Metrik birimleri bu histogramde yer almadığı için bu durumda milisaniye olduğunu varsayacağız.

Ayrıca, sayfa yüklemelerinin% 5,21'inde,geçmişteki ilk toplama döneminde örnek metrik değeri 2.500 ms ile 4.000 ms arasındaydı ve sayfa yüklemelerinin% 2, 88'inde,geçmişteki ilk toplama döneminde 4.000 ms'den büyük bir değer görüldü.

Yüzdelik dilim

Metrikler, ek analizler için yararlı olabilecek yüzdelik dilim zaman serileri de içerebilir.

Veri noktaları, API tarafından da döndürülen veri toplama dönemi tarihlerinin sırasına göre sunulur. İlk nokta en erken dönem, son nokta ise en son veri toplama dönemidir.

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

Bu yüzdelik dilimler, söz konusu metrik için belirli yüzdelik dilimlerdeki belirli metrik değerlerini gösterebilir. Bunlar, nihai gruplandırılmış verileri değil, mevcut verilerin tamamını temel alır. Bu nedenle, nihai gruplandırılmış histograma dayalı bir enterpolasyonlu yüzdeyle eşleşmeyebilir.

Kesirler

Metrikler, etiketli kesirlerin zaman serisi olarak ifade edilebilir. Her etiket, sayfa yüklemesini belirli bir şekilde tanımlar. Veri noktaları, API tarafından da döndürülen veri toplama dönemi tarihlerinin sırasına göre sunulur. İlk nokta en erken dönem, son nokta ise en son veri toplama dönemidir.

Örnek:

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

Bu örnekte, en son veri noktası sayfa yüklemelerinin% 14,21'inin masaüstünden, %82,88'inin ise telefonlardan geldiğini gösterir.

Metrik değer türleri

CrUX Geçmişi API'si aynı metrik değer türlerini kullandığından daha fazla bilgi için günlük CrUX API metrik değer türleri belgelerine bakabilirsiniz.

Metrik uygunluğu

Uygunluk ölçütlerine bağlı olarak bir kaynak veya URL, CrUX History API tarafından kapsanan toplama dönemlerinin yalnızca bazılarında uygun olabilir. Bu durumlarda CrUX Geçmişi API'si, uygun veri içermeyen toplama dönemleri için histogramTimeseries yoğunlukları için "NaN" ve percentilesTimeseries için null döndürür. Farkın nedeni, histogram yoğunluklarının her zaman sayı olması, yüzdelik dilimlerin ise sayı veya dize olabilmesidir (CLS, sayı gibi görünse bile dize kullanır).

Örneğin, ikinci dönemde uygun veri yoksa bu durum şu şekilde gösterilir:

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

Zaman içinde uygunluk durumunu değiştiren URL'ler veya kaynaklar için birçok girişin eksik olduğunu fark edebilirsiniz.

Toplama dönemleri

CrUX History API, her bir toplama penceresinin başlangıç ve bitiş tarihlerini temsil eden bir firstDate ve endDate alanı dizisi içeren bir collectionPeriods nesnesi içerir. Örneğin:

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

Bu toplama dönemleri artan düzendedir ve yanıtın diğer bölümlerindeki veri noktalarının her birinin tarih aralığını temsil eder.

Geçmiş API'si her Pazartesi güncellenir ve önceki Cumartesi gününe kadarki verileri içerir (standart 2 günlük gecikmeyle). Önceki 40 haftaya ait verileri (haftada bir toplama dönemi) içerir. Varsayılan olarak 25 toplama dönemi döndürülür. Bu değer, istekteki "collectionPeriodCount" değerinin 1 ile 40 arasında bir sayı olarak ayarlanmasıyla değiştirilebilir.

Her toplama dönemi önceki 28 günün toplu verilerini içerdiğinden ve toplama dönemleri haftalık olduğundan toplama dönemleri çakışır. Bu değerler, verilerin hareketli ortalamasına benzer. Sonraki her döneme üç haftalık veri dahil edilir ve bir hafta farklı olur.

Örnek sorgular

Sorgular, https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]" adresine POST isteği gönderilerek JSON nesnesi olarak gönderilir. Sorgu verileri, POST gövdesinde JSON nesnesi olarak gönderilir.

Günlük CrUX API'sinin queryRecord yerine queryHistoryRecord kullanıldığını unutmayın.

Örnek bir mesaj şöyle olabilir:

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

Örneğin, bu komut aşağıdaki komut satırıyla curl adresinden çağrılabilir (API_KEY, anahtarınızla değiştirilir):

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

Sayfa düzeyindeki veriler, sorguda origin yerine url mülkü iletilerek API üzerinden kullanılabilir:

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

metrics mülkü ayarlanmazsa mevcut tüm metrikler döndürülür:

• 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 (yalnızca istekte formFactor belirtilmemişse raporlanır)

formFactor değeri sağlanmazsa değerler tüm form faktörlerinde toplanır.

Daha fazla örnek sorgu için CrUX History API'yi kullanma kılavuzuna bakın.

Veri ardışık düzeni

CrUX veri kümesi, API üzerinden kullanıma sunulmadan önce verileri birleştirmek, toplamak ve filtrelemek için bir ardışık düzen üzerinden işlenir.

Hareketli ortalama

Chrome kullanıcı deneyimi raporundaki veriler, birleştirilmiş metriklerin 28 günlük hareketli ortalamasıdır. Bu, Chrome UX Report'ta herhangi bir zamanda sunulan verilerin aslında son 28 güne ait verilerin toplanmış hali olduğu anlamına gelir.

Geçmiş API'si, her biri bu 28 günü kapsayan çeşitli toplama dönemleri içerir. Her toplama dönemi önceki 28 günün toplu verilerini içerdiğinden ve toplama dönemleri haftalık olduğundan toplama dönemleri çakışır. Bu değerler, verilerin hareketli ortalamasına benzer. Sonraki her döneme üç haftalık veri dahil edilir ve bir hafta farklı olur.

Haftalık güncellemeler

History API her pazartesi saat 04:00 (UTC) civarında güncellenir ve önceki cumartesiye kadar olan verileri içerir (standart 2 günlük gecikmeyle). Haftada bir toplama dönemi olmak üzere, önceki 40 haftaya (yaklaşık 10 ay) ait verileri içerir. Varsayılan olarak zaman serisi başına 25 giriş döndürdüğümüzü ancak bu değerin collectionPeriodCount istek parametresi ile geçersiz kılınabileceğini unutmayın.

Güncelleme süreleri için hizmet düzeyi sözleşmesi yoktur. Güncelleme her gün mümkün olduğunca yapılır.

Şema

CrUX History API için POST HTTP isteklerini kabul eden tek bir uç nokta vardır. API, istenen kaynak veya sayfayla ilgili performans verilerine karşılık gelen bir veya daha fazla metrics içeren bir record döndürür.

HTTP isteği

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

URL, gRPC Kod Dönüştürme söz dizimini kullanır.

İstek içeriği

CrUX History API, günlük CrUX API ile benzer istek gövdeleri kullanır ve bunlara isteğe bağlı bir "collectionPeriodCount" alanı ekler:

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

  "collectionPeriodCount": int32 // Optional: Number of periods to collect
}

Örneğin, web.dev ana sayfası için masaüstündeki Largest Contentful Paint değerlerini istemek üzere:

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

Bu benzer istek, isteğe bağlı collectionPeriodCount alanını içerir ve https://web.dev kaynağı için yaklaşık 10 aylık web performansı geçmişi sağlayan 40 zaman serisi girişi oluşturur:

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

Yanıt gövdesi

Başarılı istekler, aşağıdaki yapıda bir record nesnesi ve urlNormalizationDetails içeren yanıtlar döndürür:

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

Örneğin, önceki istekteki istek gövdesine verilen yanıt şu olabilir:

{
  "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 }
      }, {
        ...
      }
    ]
  }
}

Anahtar

Key, bu kaydı benzersiz olarak tanımlayan tüm boyutları tanımlar.

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

Metrikler

metric, ilk zengin içerikli boyama gibi tek bir web performans metriğiyle ilgili kullanıcı deneyimi verileri kümesidir. Gerçek dünyadaki Chrome kullanımının özet histogramını bins dizisi olarak içerir.

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

veya

"fractionTimeseries": {
  object (Fractions)
}

Bölme

bin, başlangıçtan sona kadar veya bitiş belirtilmemişse başlangıçtan pozitif sonsuzluk değerine kadar olan verilerin ayrık bir bölümüdür.

Bir paketin başlangıç ve bitiş değerleri, temsil ettiği metriğin değer türünde verilir. Örneğin, ilk zengin içerikli boyama milisaniye cinsinden ölçülür ve tam sayı olarak gösterilir. Bu nedenle, metrik kapsayıcılarında başlangıç ve bitiş türleri için int32 kullanılır. Ancak kümülatif düzen kayması, birimsiz ondalık sayılarla ölçülür ve dize olarak kodlanmış bir ondalık sayı olarak gösterilir. Bu nedenle, metrik kapları değer türü için dizeler kullanır.

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

Yüzdelik dilim

Percentiles, belirli bir istatistiksel yüzdelik dilimdeki bir metriğin sentetik değerlerini içerir. Bunlar, bir metriğin değerini toplam kullanıcı sayısı içindeki kullanıcı yüzdesinin deneyimlediği şekilde tahmin etmek için kullanılır.

{
  "P75": value
}

Kesirler

Fractions, giriş başına toplamı yaklaşık 1 olan etiketli kesirler zaman serisi içerir. Her etiket bir sayfa yüklemesini bir şekilde tanımlar. Bu nedenle, bu şekilde temsil edilen metriklerin sayısal değerler yerine farklı değerler ürettiği düşünülebilir. Kesirler ise belirli bir farklı değerin ne sıklıkta ölçüldüğünü ifade eder.

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

Histogram kutularındaki yoğunluk değerlerine benzer şekilde, her fraction bir sayı 0.0 <= value <= 1.0'dır ve toplamları yaklaşık 1, 0'dur. Belirli bir toplama dönemi için metrik kullanılamadığında, ilgili giriş tüm kesirli sayı dizilerinde "NaN" olur.

UrlNormalization

Daha yüksek bir başarılı arama şansı elde etmek için bir URL'yi normalleştirmek üzere gerçekleştirilen normalleştirme işlemlerini temsil eden nesne. Bunlar, sağlanan url_pattern'ün başarısız olduğu bilindiğinde yapılan temel, otomatik değişikliklerdir. Yönlendirmeleri takip etme gibi karmaşık işlemler ele alınmaz.

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

Hız sınırları

CrUX Geçmişi API'si, her iki API için de Google Cloud projesi başına dakikada 150 sorgu olan ve ücretsiz olarak sunulan CrUX API ile aynı sınırı paylaşır. Bu sınırı ve mevcut kullanımınızı Google Cloud Console'da görebilirsiniz. Bu geniş kota, kullanım alanlarının büyük çoğunluğu için yeterli olacaktır. Daha yüksek kota için ödeme yapmak mümkün değildir.