CrUX History API の使用方法

このガイドでは、Chrome UX Report (CrUX) History API エンドポイントについて説明します。このエンドポイントは、ウェブ パフォーマンスの時系列データを提供します。このデータは毎週更新され、25 個のデータポイントが 1 週間の間隔を空けて約 6 か月分の履歴が表示されます。

元の 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 の queryRecordqueryHistoryRecord に変更します。前の呼び出しと同じ 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 値は、ページ読み込みの 91.87% で 2,500 ms 未満、5.27% は 2,500 ~ 4,008 ms の範囲内であり、0.27% は

同様に、p75 値の時系列もあります。2022 年 8 月 14 日から 2022 年 9 月 10 日までの LCP p75 は 1377 でした。つまり、この収集期間において、ユーザー エクスペリエンスの 75% で 1,377 ミリ秒未満の LCP があり、ユーザー エクスペリエンスの 25% で 1,377 ミリ秒を超える LCP でした。

この例では、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 値のグラフを以下に示します。

2022 年 11 月頃に回帰を示す p75 値の時系列グラフ

この折れ線グラフでは、Y 軸の各値は p75s 時系列の p75 値、X 軸は各収集期間の lastDate として設定された時間です。

このヒストグラムには 3 つのビンがあるため、ヒストグラム ビンの時系列(トライビン チャートと呼ばれます)のグラフを示します。

積み上げ棒グラフ。良好、改善が必要、不良の相対的な割合の推移を示します。

X 軸は、各収集期間の lastDate として設定されます。一方、今回の Y 軸は INP 指標の特定範囲内に該当するページ読み込みの割合で、積み上げ棒グラフで表示されます。p75 グラフでは概要を簡単に確認できます。1 つのグラフ内で複数の指標を追加したり、PHONEDESKTOP の両方の折れ線を表示したりするのが比較的簡単です。トライビン グラフでは、各収集期間に測定された指標値の分布を把握できます。

たとえば、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 の使用方法の一例にすぎません。JSON ベースの HTTP エンドポイントとして、あらゆるテクノロジーから API に対してクエリを実行できます。

まとめ

CrUX History API エンドポイントが導入される前は、サイト所有者は CrUX から取得できる履歴情報に限界がありました。BigQuery と CrUX ダッシュボードを使用してオリジンレベルの月次データは利用可能でしたが、週次データもページレベルの履歴データも利用できませんでした。サイト所有者は日次データ API を使用してこのデータを自分で記録できますが、多くの場合、その必要性は指標が後退した後で初めて発見されました。

この CrUX History API の導入は、サイト所有者がサイト指標の変化について理解を深め、問題が発生したときの診断ツールとして活用できるようになれば幸いです。新しい API をご利用の場合は、Chrome UX レポート(ディスカッション)Google グループにフィードバックをお寄せください。

謝辞

ヒーロー画像: Dave HerringUnsplash より)