このガイドでは、時系列のウェブ パフォーマンス データを提供する Chrome UX Report（CrUX）History API エンドポイントについて説明します。このデータは毎週更新され、約 6 か月分の履歴（25 個のデータポイントを 1 週間の間隔で）を確認できます。
元の CrUX API エンドポイントからの日次更新と併用すると、最新のデータと過去に発生したデータの両方をすばやく確認できるため、時間の経過に伴うウェブページの変化を確認できる強力なツールとなっています。
日次 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 に対してクエリを実行する
履歴エンドポイントを呼び出すには、curl コマンドの URL の queryRecord を 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 日までの LCP 値が 2,500 ミリ秒未満の場合は 91.87%、2,500 ミリ秒から 4,000 ミリ秒を超える値は 5.27%、0.4% を超える値は 5.27% であることがわかりました。
同様に、p75 値の時系列があります。2022 年 8 月 14 日から 2022 年 9 月 10 日までの LCP p75 は 1377 でした。つまり、この収集期間では、ユーザー エクスペリエンスの 75% の LCP が 1,377 ミリ秒未満で、25% のユーザー エクスペリエンスの LCP が 1,377 ミリ秒を上回っています。
この例では 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 つのビンがあるためです。
X 軸は、各収集期間の lastDate として設定されています。ただし、今回の Y 軸は INP 指標の特定の範囲に該当するページ読み込みの割合であり、積み上げ棒グラフで示されます。p75 グラフでは概要がわかりやすく示されています。1 つのグラフ内で、複数の指標を追加したり、PHONE と DESKTOP の両方の線を表示したりできます。トライビン グラフは、各収集期間中に測定された指標値の分布を示します。
たとえば、p75 グラフでは、観察期間中に https://web.dev の INP 値がほぼ許容範囲内であったことが示されていますが、トライビン グラフでは、ページ読み込みのごく一部で、INP が実際には低いことがわかります。どちらのグラフでも、10 月末に始まって 11 月中旬に修正されたパフォーマンスの低下は比較的容易に推測できます。
このようなグラフを自分で生成するために、サンプルの Colab を作成しました。Colab（Colaboratory）を使用すると、ブラウザから Python を記述、実行できます。CrUX History API Colab（ソース）は、Python を使用して API を呼び出し、データをグラフ化します。
この Colab では、簡単なフォームに入力して、p75 グラフやトライビン グラフを作成したり、表形式でデータを取得したり、CrUX API のリクエストとレスポンスのペアを確認したりできます。プログラマーでなくても使用できますが、Python コードを確認して、魅力的なものに変更できます。ご満足いただけましたら、ぜひフィードバックをお寄せください。
当然ながら、使用できるのは Colab や Python に限定されません。これは、この新しい API の使用方法の一例にすぎません。この API は JSON ベースの HTTP エンドポイントであるため、あらゆるテクノロジーからクエリできます。
おわりに
CrUX History API エンドポイントを導入する前は、サイト所有者が CrUX から取得できる履歴情報は限られていました。オリジン レベルの月次データは BigQuery と CrUX ダッシュボードを使用して入手できましたが、週次データは利用できず、ページレベルの履歴データもありませんでした。サイト所有者は、日次 API を使用してこのデータを自分で記録できましたが、多くの場合、その必要性は指標の回帰後に初めて発見されました。
この CrUX History API を導入することで、サイト所有者の皆様がサイトの指標の変化について理解を深め、問題が発生したときの診断ツールとして活用できるようになることを願っています。新しい API をお使いの場合は、Chrome UX レポート（ディスカッション）Google グループでフィードバックをお寄せください。
謝辞
ヒーロー画像（作成者: Dave Herring、出典: Unsplash）