公開日: 2023 年 2 月 7 日、最終更新日: 2025 年 4 月 11 日
このガイドでは、ウェブ パフォーマンス データの時系列を提供する Chrome ユーザー エクスペリエンス レポート（CrUX）History API エンドポイントについて説明します。このデータは毎週更新され、約 6 か月分の履歴（40 個のデータポイントが 1 週間ごとに配置）を確認できます。
元の CrUX API エンドポイントからの毎日の更新と組み合わせて使用すると、最新のデータと過去のデータがすぐにわかるため、ウェブページの経時的な変化を確認する強力なツールとなります。
このページの 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 キーを使用しても問題ありません。collectionPeriodCount は、返される時系列エントリの数を指定します。最大値は 40 です。指定しない場合、デフォルトは 25 です。
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", "collectionPeriodCount": 40}'
レスポンスの全体的な形状は似ていますが、データが大幅に増えています。単一のデータポイントではなく、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 ミリ秒バケットの 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 ミリ秒未満であり、25% のユーザー エクスペリエンスで LCP が 1,377 ミリ秒を超えていたことになります。
この例では、6 つの時系列エントリと収集期間のみがリストされていますが、API からのレスポンスでは、デフォルトで 25 個の時系列エントリが提供され、リクエストで "collectionPeriodCount": 40 が指定されている場合は最大 40 個の時系列エントリが提供されます。各収集期間の終了日は 7 日間隔の土曜日であるため、"collectionPeriodCount": 40 で 10 か月間をカバーします。
任意のレスポンスで、ヒストグラム ビン密度と p75 値の時系列の長さは、collectionPeriods フィールドの配列の長さとまったく同じになります。これらの配列のインデックスに基づく 1 対 1 の対応があります。
ページレベルのデータをクエリする
CrUX History API では、オリジン単位のデータだけでなく、過去のページ単位のデータにもアクセスできます。オリジン レベルのデータは、以前から BigQuery の 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 は数値のように見えても文字列を使用します）であるためです。
データを可視化する
データを可視化する最も簡単な方法は、CrUX Vis を使用することです。これは、CrUX History API の機能を実証するために特別に作成されたツールです。詳しくは、CrUX Vis のドキュメントをご覧ください。
同様のグラフを自分で生成するために、サンプル 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 を使用して月単位のオリジンレベルのデータは利用できましたが、週単位のデータやページレベルの過去のデータは利用できませんでした。サイト所有者は、日次 API を使用してこのデータを自分で記録できますが、多くの場合、指標の回帰後にこの必要性が判明します。
この CrUX 履歴 API の導入により、サイト所有者はサイト指標の変化をより深く理解し、問題が発生した際の診断ツールとして活用できるようになることが期待されます。新しい API を使用している場合は、Chrome UX Report（ディスカッション）の Google グループでフィードバックをお寄せください。
謝辞
ヒーロー画像: Dave Herring（Unsplash）