このガイドでは、ウェブ パフォーマンスのタイムシリーズ データを提供する Chrome UX レポート（CrUX）History API エンドポイントについて説明します。このデータは毎週更新され、約 6 か月分の履歴（25 個のデータポイントが 1 週間ごとに配置）を確認できます。
元の CrUX API エンドポイントからの毎日の更新と組み合わせることで、最新のデータと過去のデータをすばやく確認できるようになりました。これにより、ウェブページの変化を経時的に確認するための強力なツールとなります。
このページで API を試す
1 日分の CrUX API をクエリする
CrUX API に関する前回の記事で説明したように、特定のオリジンのフィールドデータのスナップショットを取得するには、次の手順を行います。
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" --header 'Content-Type: application/json' --data '{"origin": "https://web.dev"}'
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [{
"start": 0, "end": 2500, "density": 0.9192
}, {
"start": 2500, "end": 4000, "density": 0.0513
}, {
"start": 4000, "density": 0.0294
}],
"percentiles": {
"p75": 1303
}
}
// ...
},
"collectionPeriod": {
"firstDate": { "year": 2022, "month": 12, "day": 27 },
"lastDate": { "year": 2023, "month": 1, "day": 23 }
}
}
}
このスナップショットには、特定の 28 日間の収集期間（この場合は 2022 年 12 月 27 日から 2023 年 1 月 23 日まで）のヒストグラム密度値とパーセンタイル値が含まれています。
CrUX History API にクエリを実行する
履歴エンドポイントを呼び出すには、URL の queryRecord を curl コマンドの queryHistoryRecord に変更します。前の呼び出しと同じ CrUX API キーを使用できます。
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"origin": "https://web.dev"}'
レスポンスの全体的な形状は似ていますが、データ量は大幅に増えています。単一のデータポイントではなく、75 パーセンタイル（p75）とヒストグラム密度の値を含むフィールドの時系列が表示されるようになりました。
{
"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 }
}
]
}
}
この例では、Largest Contentful Paint（LCP）指標の 0 ～ 2, 500 ms バケットの densities 時系列は [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. です。これらの密度はそれぞれ、対応する collectionPeriods エントリで観測されました。たとえば、5 番目の密度である 0.9183 は 2022 年 9 月 3 日までの 5 回目の収集期間における密度、0.9187 はそれ以降の週までの密度です。
つまり、https://web.dev の例の最後の時系列エントリを解釈すると、2022 年 8 月 14 日から 2022 年 9 月 10 日までのページ読み込みの 91.87% で LCP 値が 2,500 ミリ秒未満、5.27% で 2,500 ～ 4,000 ミリ秒、2.85% で 4,000 ミリ秒を超えていました。
同様に、p75 値の時系列もあります。2022 年 8 月 14 日から 2022 年 9 月 10 日までの LCP p75 は 1377 でした。つまり、この収集期間において、75% のユーザー エクスペリエンスの LCP は 1,377 ms 未満で、25% のユーザー エクスペリエンスの LCP は 1,377 ms を超えていました。
この例では時系列エントリと収集期間が 6 つしかリストされていません。API からのレスポンスでは 25 個の時系列エントリが提供されます。これらの収集期間の終了日は 7 日間隔の土曜日であるため、6 か月分のデータが含まれます。
どのようなレスポンスでも、ヒストグラムのビン密度と p75 値の時系列の長さは、collectionPeriods フィールドの配列の長さとまったく同じになります。これらの配列へのインデックスに基づいて、1 対 1 の対応関係があります。
ページ単位のデータをクエリする
CrUX History API を使用すると、オリジン レベルのデータだけでなく、過去のページレベルのデータにもアクセスできます。以前は、BigQuery の CrUX データセット（または CrUX ダッシュボード）を使用してオリジンレベルのデータを確認できましたが、ページレベルの過去のデータを確認できるのは、サイトがデータを収集して保存している場合のみでした。新しい API では、そのページレベルの過去のデータを利用できるようになりました。
ページレベルのデータは、ペイロードで origin の代わりに url を使用して、同じ方法でクエリできます。
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/blog/"}'
ページレベル（およびオリジンレベル）の過去のデータには、CrUX の他の部分と同じ資格要件が適用されるため、特にページでは過去の記録が不完全な場合があります。この場合、「欠落」データは、histogramTimeseries 密度の場合は "NaN"、percentilesTimeseries の場合は null で表されます。この違いは、ヒストグラムの密度は常に数値であるのに対し、パーセンタイルには数値と文字列の両方を使用できるためです（CLS では、数値のように見えても文字列を使用します）。
データを可視化する
では、なぜデータがこのように構成されているのでしょうか。これにより、グラフの描画が容易になりました。たとえば、https://web.dev の [Interaction To Next Paint (INP)] の p75 値のグラフを以下に示します。
この折れ線グラフでは、Y 軸の各値は p75s 時系列の p75 値、X 軸は各収集期間の lastDate として設定された時間です。
ヒストグラムのビン時系列のグラフ（3 ビングラフ）を次に示します。これらのヒストグラムには 3 つのビンがあるためです。
X 軸は、各収集期間の lastDate として設定されます。一方、今回の Y 軸は INP 指標の特定範囲内に該当するページ読み込みの割合で、積み上げ棒グラフで表示されます。p75 グラフは概要を簡単に把握できます。1 つのグラフ内に複数の指標を追加したり、PHONE と DESKTOP の両方の線を表示したりするのは比較的簡単です。3 分割グラフでは、各収集期間に測定された指標値の分布を把握できます。
たとえば、p75 グラフでは、https://web.dev の観測期間中の INP 値はほぼ許容範囲内と示されていますが、3 分割グラフでは、ページ読み込みのごく一部で INP が実際には低下していることがわかります。どちらのグラフでも、10 月下旬にパフォーマンスの低下が始まり、11 月中旬に修正されたことが比較的簡単に推測できます。
このようなグラフを自分で生成できるように、サンプルの Colab を作成しました。Colab（Colaboratory）を使用すると、ブラウザ内で Python を記述、実行できます。CrUX History API Colab（ソース）は Python を使用して API を呼び出し、データをグラフ化します。
この Colab では、簡単なフォームに入力することで、p75 チャートやトライビン チャートを作成したり、表形式でデータを取得したり、CrUX API のリクエストとレスポンスのペアを確認したりできます。使用するためにプログラマである必要はありませんが、Python コードを見て、素晴らしいものに変更することはできます。お気づきの点がありましたら、ぜひフィードバックをお寄せください。
もちろん、Colab や Python に限らず、これはこの新しい API の使用方法の一例にすぎません。JSON ベースの HTTP エンドポイントとして、あらゆるテクノロジーから API に対してクエリを実行できます。
まとめ
CrUX History API エンドポイントが導入される前は、サイト所有者は CrUX から入手できる履歴情報に限界がありました。BigQuery と CrUX ダッシュボードを使用してオリジンレベルの月次データは利用可能でしたが、週次データもページレベルの過去のデータも利用できませんでした。サイト所有者は、daily API を使用してこのデータを自分で記録することもできましたが、多くの場合、指標の減少後にその必要性に気付くことになります。
この CrUX History API の導入は、サイト所有者がサイト指標の変化について理解を深め、問題が発生したときの診断ツールとして活用できるようになれば幸いです。新しい API をご利用の場合は、Chrome UX レポート（ディスカッション）Google グループにフィードバックをお寄せください。
謝辞
Dave Herring によるヒーロー画像（Unsplash）