API Histori CrUX

Dipublikasikan: 7 Februari 2023, Terakhir diperbarui: 11 April 2025

CrUX History API memberikan akses latensi rendah ke data historis pengalaman pengguna sebenarnya selama enam bulan dengan tingkat perincian halaman dan origin.

Cobalah!

Kasus penggunaan umum

CrUX History API memungkinkan kueri metrik pengalaman pengguna historis untuk URI tertentu seperti "Dapatkan tren UX historis untuk origin https://example.com".

History API mengikuti struktur yang sama dengan CrUX API harian, kecuali nilai diberikan dalam array, dan kunci diberi label dengan nama jamak (misalnya, histogramTimeseries, bukan histogram, atau p75s, bukan p75).

Kunci API CrUX

Seperti API harian, penggunaan CrUX History API memerlukan kunci Google Cloud API yang disediakan untuk penggunaan Chrome UX Report API. Kunci yang sama dapat digunakan untuk API harian dan histori.

Mendapatkan dan menggunakan kunci API

Atau, buat di halaman Credentials.

Setelah memiliki kunci API, aplikasi Anda dapat menambahkan parameter kueri key=yourAPIKey ke semua URL permintaan.

Kunci API aman untuk disematkan di URL; kunci API tidak memerlukan encoding apa pun.

Lihat Contoh kueri.

Model data

Bagian ini menjelaskan struktur data dalam permintaan dan respons.

Rekam

Bagian informasi terpisah tentang halaman atau situs. Data dapat memiliki data yang spesifik untuk ID dan untuk kombinasi dimensi tertentu. Kumpulan data dapat berisi data untuk satu atau beberapa metrik.

Pengenal

ID menentukan data yang akan dicari. Di CrUX, ID ini adalah halaman web dan situs.

Asal

Jika ID adalah origin, semua data yang ada untuk semua halaman di origin tersebut akan digabungkan. Misalnya, asal http://www.example.com memiliki halaman seperti yang ditetapkan oleh peta situs ini:

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

Artinya, saat membuat kueri Chrome UX Report dengan origin yang ditetapkan ke http://www.example.com, data untuk http://www.example.com/, http://www.example.com/foo.html, dan http://www.example.com/bar.html akan ditampilkan, digabungkan, karena semuanya adalah halaman di bawah origin tersebut.

URL

Jika ID-nya adalah URL, hanya data untuk URL tertentu tersebut yang akan ditampilkan. Melihat kembali peta situs asal http://www.example.com:

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

Jika ID ditetapkan ke URL dengan nilai http://www.example.com/foo.html, hanya data untuk halaman tersebut yang akan ditampilkan.

Dimensi

Dimensi mengidentifikasi grup data tertentu yang digunakan untuk menggabungkan data. Misalnya, faktor bentuk PHONE menunjukkan bahwa data berisi informasi tentang pemuatan yang terjadi di perangkat seluler.

Faktor Bentuk

CrUX History API hanya tersedia gabungan menurut dimensi faktor bentuk. Ini adalah class perangkat umum yang dibagi menjadi PHONE, TABLET, dan DESKTOP.

Metrik

Kami melaporkan metrik dalam deret waktu agregasi statistik, yaitu histogram, persentil, dan fraksi.

Histogram

Jika metrik dinyatakan dalam array histogram, setiap entri deret waktu mewakili persentase pemuatan halaman yang metriknya berada dalam interval, secara proporsional untuk semua. Titik data ditampilkan dalam urutan tanggal periode pengumpulan yang juga ditampilkan oleh API, dengan titik pertama adalah periode paling awal, dan titik terakhir adalah periode pengumpulan terbaru.

Histogram tiga bin untuk contoh metrik terlihat seperti ini:

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

Data ini menunjukkan bahwa 91,90% pemuatan halaman mengalami nilai metrik contoh antara 0 md dan 2.500 md untuk periode pengumpulan pertama dalam histori, diikuti dengan 92,03%, 91,94%... Satuan metrik tidak terdapat dalam histogram ini, dalam hal ini kita akan mengasumsikan milidetik.

Selain itu, 5,21% pemuatan halaman mengalami nilai metrik contoh antara 2.500 md dan 4.000 md dalam periode pengumpulan pertama dalam histori, dan 2,88% pemuatan halaman mengalami nilai lebih besar dari 4.000 md dalam periode pengumpulan pertama dalam histori.

Persentil

Metrik juga dapat berisi deret waktu persentil yang dapat berguna untuk analisis tambahan.

Titik data ditampilkan dalam urutan tanggal periode pengumpulan yang juga ditampilkan oleh API, dengan titik pertama adalah periode paling awal, dan titik terakhir adalah periode pengumpulan terbaru.

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

Persentil ini dapat menampilkan nilai metrik tertentu pada persentil tertentu untuk metrik tersebut. Data ini didasarkan pada kumpulan lengkap data yang tersedia, bukan data yang dikelompokkan secara final, sehingga tidak selalu cocok dengan persentil yang diinterpolasi yang didasarkan pada histogram yang dikelompokkan secara final.

Pecahan

Metrik dapat dinyatakan sebagai deret waktu dari fraksi berlabel; setiap label menjelaskan pemuatan halaman dengan cara tertentu. Titik data ditampilkan dalam urutan tanggal periode pengumpulan yang juga ditampilkan oleh API, dengan titik pertama adalah periode paling awal, dan titik terakhir adalah periode pengumpulan terbaru.

Contoh:

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

Dalam contoh ini, titik data terbaru menunjukkan bahwa 14,21% pemuatan halaman berasal dari desktop, dan 82,88% berasal dari ponsel.

Jenis nilai metrik

Karena CrUX History API menggunakan jenis nilai metrik yang sama, Anda dapat melihat dokumentasi jenis nilai metrik CrUX API harian untuk mengetahui detail selengkapnya.

Kelayakan metrik

Berdasarkan kriteria kelayakan, origin atau URL mungkin hanya memenuhi syarat untuk beberapa periode pengumpulan yang tercakup dalam CrUX History API. Dalam hal ini, CrUX History API akan menampilkan "NaN" untuk kepadatan histogramTimeseries dan null untuk percentilesTimeseries untuk periode pengumpulan yang tidak memiliki data yang memenuhi syarat. Penyebab perbedaannya adalah kepadatan histogram selalu berupa angka, sedangkan persentil dapat berupa angka atau string (CLS menggunakan string, meskipun terlihat seperti angka).

Misalnya, jika periode kedua tidak memiliki data yang memenuhi syarat, data tersebut akan ditampilkan sebagai:

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

Untuk URL atau origin yang memenuhi syarat dan tidak memenuhi syarat dari waktu ke waktu, Anda mungkin melihat banyak entri yang tidak ada.

Periode pengumpulan

CrUX History API berisi objek collectionPeriods dengan array kolom firstDate dan endDate yang mewakili tanggal awal dan akhir setiap periode agregasi. Contoh:

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

Periode pengumpulan ini diurutkan menaik dan mewakili rentang tanggal setiap titik data di bagian respons lainnya.

History API diperbarui setiap hari Senin dan berisi data hingga Sabtu sebelumnya (sesuai dengan keterlambatan standar 2 hari). Data ini berisi data selama 40 minggu sebelumnya—satu periode pengumpulan per minggu. Secara default, 25 periode pengumpulan akan ditampilkan. Ini dapat diubah dengan menetapkan "collectionPeriodCount" dalam permintaan ke angka antara 1 dan 40.

Karena setiap periode pengumpulan berisi data gabungan 28 hari sebelumnya, dan periode pengumpulannya adalah per minggu, ini berarti periode pengumpulan akan tumpang-tindih. Data ini mirip dengan data rata-rata bergerak, dengan data selama tiga minggu disertakan dalam setiap periode berikutnya, dan satu minggu berbeda.

Contoh kueri

Kueri dikirim sebagai objek JSON menggunakan permintaan POST ke https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]" dengan data kueri sebagai objek JSON dalam isi POST.

Perhatikan penggunaan queryHistoryRecord yang menggantikan queryRecord dari CrUX API harian.

Contoh isi adalah:

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

Misalnya, ini dapat dipanggil dari curl dengan command line berikut (mengganti API_KEY dengan kunci Anda):

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

Data tingkat halaman tersedia melalui API dengan meneruskan properti url dalam kueri, bukan origin:

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

Jika properti metrics tidak ditetapkan, semua metrik yang tersedia akan ditampilkan:

• 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 (hanya dilaporkan jika tidak ada formFactor yang ditentukan dalam permintaan)

Jika tidak ada nilai formFactor yang diberikan, nilai akan digabungkan di semua faktor bentuk.

Lihat panduan Menggunakan CrUX History API untuk contoh kueri lainnya.

Pipeline data

Set data CrUX diproses melalui pipeline untuk menggabungkan, menggabungkan, dan memfilter data sebelum tersedia melalui API.

Rata-rata penggiliran

Data dalam Laporan UX Chrome adalah rata-rata penggiliran 28 hari dari metrik gabungan. Artinya, data yang ditampilkan dalam Laporan UX Chrome pada waktu tertentu sebenarnya adalah data selama 28 hari terakhir yang digabungkan.

History API berisi sejumlah periode pengumpulan, masing-masing mencakup 28 hari ini. Karena setiap periode pengumpulan berisi data gabungan 28 hari sebelumnya, dan periode pengumpulannya adalah per minggu, ini berarti periode pengumpulan akan tumpang-tindih. Data ini mirip dengan data rata-rata bergerak, dengan data selama tiga minggu disertakan dalam setiap periode berikutnya, dan satu minggu berbeda.

Update mingguan

History API diperbarui setiap Senin sekitar pukul 04.00 UTC dan berisi data hingga Sabtu sebelumnya (sesuai dengan jeda 2 hari standar). Data ini berisi data selama 40 minggu sebelumnya (sekitar 10 bulan), satu periode pengumpulan per minggu. Perhatikan bahwa secara default, kami menampilkan 25 entri per deret waktu; tetapi hal ini dapat diganti dengan menentukan parameter permintaan collectionPeriodCount.

Tidak ada perjanjian tingkat layanan untuk waktu update; update dijalankan berdasarkan upaya terbaik setiap hari.

Skema

Ada satu endpoint untuk CrUX History API yang menerima permintaan HTTP POST. API menampilkan record yang berisi satu atau beberapa metrics yang sesuai dengan data performa tentang origin atau halaman yang diminta.

Permintaan HTTP

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

URL menggunakan sintaksis gRPC Transcoding.

Isi permintaan

CrUX History API menggunakan isi permintaan yang serupa dengan CrUX API harian, dengan satu kolom "collectionPeriodCount" opsional tambahan:

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

Misalnya, untuk meminta nilai Largest Contentful Paint desktop untuk halaman beranda web.dev:

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

Permintaan serupa ini menyertakan kolom collectionPeriodCount opsional dan akan menghasilkan 40 entri deret waktu yang memberikan histori performa web sekitar 10 bulan untuk origin https://web.dev:

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

Isi respons

Permintaan yang berhasil akan menampilkan respons dengan objek record dan urlNormalizationDetails dalam struktur berikut:

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

Misalnya, respons terhadap isi permintaan dalam permintaan sebelumnya dapat berupa:

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

Kunci

Key menentukan semua dimensi yang mengidentifikasi data ini sebagai unik.

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

Metrik

metric adalah kumpulan data pengalaman pengguna untuk satu metrik performa web, seperti first contentful paint. File ini berisi histogram ringkasan penggunaan Chrome di dunia nyata sebagai serangkaian bins.

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

atau

"fractionTimeseries": {
  object (Fractions)
}

Kotak

bin adalah bagian data terpisah yang mencakup dari awal hingga akhir, atau jika tidak ada akhir yang diberikan dari awal hingga tak terhingga positif.

Nilai awal dan akhir bin diberikan dalam jenis nilai metrik yang diwakilinya. Misalnya, first contentful paint diukur dalam milidetik dan ditampilkan sebagai int, sehingga bucket metriknya akan menggunakan int32 untuk jenis awal dan akhirnya. Namun, pergeseran tata letak kumulatif diukur dalam desimal tanpa satuan dan ditampilkan sebagai desimal yang dienkode sebagai string, sehingga bucket metriknya akan menggunakan string untuk jenis nilainya.

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

Persentil

Percentiles berisi nilai sintetis metrik pada persentil statistik tertentu. Metrik ini digunakan untuk memperkirakan nilai metrik seperti yang dialami oleh persentase pengguna dari total jumlah pengguna.

{
  "P75": value
}

Pecahan

Fractions berisi deret waktu fraksi berlabel yang jumlahnya mencapai ~1, per entri. Setiap label menjelaskan pemuatan halaman dengan cara tertentu, sehingga metrik yang direpresentasikan dengan cara ini dapat dianggap menghasilkan nilai yang berbeda, bukan nilai numerik, dan fraksi menyatakan frekuensi pengukuran nilai tertentu yang berbeda.

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

Sama seperti nilai kepadatan dalam bucket histogram, setiap fraction adalah angka 0.0 <= value <= 1.0, dan jumlahnya mencapai ~1,0. Jika metrik tidak tersedia untuk periode pengumpulan tertentu, entri yang sesuai akan berupa "NaN" di semua array pecahan.

UrlNormalization

Objek yang mewakili tindakan normalisasi yang dilakukan untuk menormalisasi URL guna mencapai peluang yang lebih tinggi untuk pencarian yang berhasil. Ini adalah perubahan otomatis dasar yang dilakukan saat mencari url_pattern yang disediakan akan diketahui gagal. Tindakan kompleks seperti mengikuti pengalihan tidak ditangani.

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

Batas kapasitas

CrUX History API memiliki batas yang sama dengan CrUX API untuk 150 kueri per menit per project Google Cloud untuk kedua API tersebut, yang ditawarkan tanpa biaya. Batas ini, dan penggunaan Anda saat ini, dapat dilihat di Konsol Google Cloud. Kuota yang besar ini seharusnya sudah cukup untuk sebagian besar kasus penggunaan dan Anda tidak dapat membayar untuk meningkatkan kuota.