CrUX History API

CrUX History API により、ページとオリジンの粒度で過��� 6 か月間の実際のユーザー エクスペリエンス データに低レイテンシでアクセスできます。

一般的なユースケース

CrUX History API を使用すると、「https://example.com オリジンの UX トレンドの履歴を取得する」など、特定の URI について過去のユーザー エクスペリエンス指標をクエリできます。

History API の構造は、日々の CrUX API と同じです。ただし、値は配列で指定し、キーは複数の名前でラベル付けします（たとえば、histogram ではなく histogramTimeseries、p75 ではなく p75s など）。

CrUX API キー

毎日の API と同様に、CrUX History API を使用するには Google Cloud API キーが必要です。同じキーを Daily API と History API で使用できます。

[認証情報] ページでアカウントを作成し、Chrome UX Report API で使用できるようにプロビジョニングできます。

API キーを作成すると、アプリケーションはすべてのリクエスト URL にクエリ パラメータ key=[YOUR_API_KEY] を追加できます。クエリの例をご覧ください。

API キーは URL に埋め込んでも安全です。エンコーディングの必要はありません。

データモデル

このセクションでは、リクエストとレスポンスのデータ構造について詳しく説明します。

記録

ページまたはサイトに関する個別の情報。レコードには、識別子と特定のディメンションの組み合わせに固有のデータを含めることができます。レコードには、1 つ以上の指標のデータを含めることができます。

識別子

識別子は、検索するレコードを指定します。CrUX では、ウェブページとウェブサイトが ID に該当します。

出発地

識別子がオリジンの場合、そのオリジンのすべてのページに存在するすべてのデータが集計されます。たとえば、http://www.example.com のオリジンに、次のサイトマップで規定されているページがあるとします。

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

つまり、オリジンを http://www.example.com に設定して Chrome UX レポートをクエリすると、http://www.example.com/、http://www.example.com/foo.html、http://www.example.com/bar.html のデータが集約されて返されます。これらは、すべて該当オリジンのページであるためです。

URL

識別子が URL の場合は、その URL のデータのみが返されます。http://www.example.com オリジン サイトマップを再度確認します。

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

ID が http://www.example.com/foo.html の値の URL に設定されている場合は、そのページのデータのみが返されます。

表示サイズ

ディメンションは、レコードの集計対象となる特定のデータグループを識別します。たとえば、フォーム ファクタ PHONE は、モバイル デバイスで行われた読み込みに関する情報がレコードに含まれていることを示します。

CrUX History API は、フォーム ファクタのディメンションによる集計でのみ使用できます。これはデバイスの一般的なクラスで、PHONE、TABLET、DESKTOP に分割されます。

指標

指標は、ヒストグラム、パーセンタイル、比率の統計集計の時系列で報告されます。

ヒストグラム

指標がヒストグラム配列で表現されている場合、各時系列エントリは、指標が特定の間隔に該当するページ読み込みの割合（すべてに比例して）を表します。データポイントは、API によっても返された収集期間の日付順で表示されます。最初のポイントは最も早い期間、最後のポイントは最新の収集期間を表します。

指標の例の簡単な 3 つのビンのヒストグラムは次のようになります。

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

このデータは、履歴の最初の収集期間でページ読み込みの 91.90% でサンプル指標値が 0 ～ 2,500 ms で発生し、次いで 92.03%、91.94%... このヒストグラムには指標の単位は含まれません。この例ではミリ秒と見なされます。

さらに、履歴の最初の収集期間では、ページ読み込みの 5.21% でサンプル指標値が 2,500 ～ 4,000 ms で発生し、2.88% のページ読み込みで、履歴の最初の収集期間で 4,000 ms を超える値が発生しました。

パーセンタイル

指標には、追加の分析に役立つパーセンタイルの時系列を含めることもできます。

データポイントは、API によっても返された収集期間の日付順で表示されます。最初のポイントは最も早い期間、最後のポイントは最新の収集期間を表します。

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

これらのパーセンタイルでは、その指標の特定のパーセンタイルにおける特定の指標値を表示できます。最終的なビニングされたデータではなく、利用可能なすべてのデータに基づくため、最終的なビニングされたヒストグラムに基づく補間パーセンタイルと必ずしも一致しません。

分数

指標は、ラベルが付けられた割合の時系列で表すことができます。各ラベルは、特定の方法でページ読み込みを表します。データポイントは、API によっても返された収集期間の日付順で表示されます。最初のポイントは最も早い期間、最後のポイントは最新の収集期間を表します。

例:

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

この例では、最新のデータポイントにより、ページの読み込みの 14.21% がパソコンから、82.88% がスマートフォンから発生していることがわかります。

指標値のタイプ

CrUX History API でも同じ指標値タイプが使用されるため、詳しくは毎日の CrUX API 指標の値タイプに関するドキュメントをご覧ください。

指標の要件

利用条件に基づき、オリジンまたは URL は、CrUX History API でカバーされる収集期間の一部にしか使用できない場合があります。このような場合、CrUX History API は、密度 histogramTimeseries に対して "NaN"、収集対象データがない収集期間 percentilesTimeseries に対して null を返します。差異の理由は、ヒストグラムの密度は常に数値であるのに対し、パーセンタイルは数値または文字列であるからです（CLS では数値のように見えても文字列が使用されます）。

たとえば、2 つ目の期間に対象となるデータがない場合は、次のように表示されます。

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

URL やオリジンが時間の経過とともに対象外となる場合、多数のエントリが欠落することがあります。

収集期間

CrUX History API には、各集計期間の開始日と終了日を表す firstDate フィールドと endDate フィールドの配列を含む collectionPeriods オブジェクトが含まれています。次に例を示します。

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

これらの収集期間は昇順で、回答の他のセクションの各データポイントの期間を表します。

History API は毎週月曜日に更新され、データには前の土曜日までのデータが格納されています（2 日間の標準タイムラグに基づきます）。過去 25 週間分のデータが含まれています（収集期間は 1 週間に 1 回）。

各収集期間には過去 28 日間の集計データが含まれ、収集期間は 1 週間ごとであるため、収集期間は重複します。これはデータの移動平均に似ており、後続の各期間に 3 週間分のデータが含まれます（1 週間は異なります）。

クエリの例

クエリは、https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]" への POST リクエストを使用して JSON オブジェクトとして送信されます。POST 本文には、クエリデータを JSON オブジェクトとして指定します。

毎日の CrUX API の queryRecord の代わりに、queryHistoryRecord が使用されていることに注意してください。

本文の例は次のとおりです。

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

たとえば、次のコマンドラインを使用して curl から呼び出すことができます（API_KEY は実際の鍵に置き換えます）。

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

クエリで origin ではなく url プロパティを渡すことで、API でページ単位のデータを利用できます。

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

metrics プロパティが設定されていない場合、使用可能なすべての指標が返されます。

  • cumulative_layout_shift
  • first_contentful_paint
  • first_input_delay
  • interaction_to_next_paint
  • largest_contentful_paint
  • experimental_time_to_first_byte
  • navigation_types
  • round_trip_time
  • form_factors（リクエストで formFactor が指定されていない場合にのみ報告）

formFactor 値が指定されていない場合、値はすべてのフォーム ファクタで集計されます。

クエリの例については、CrUX History API の使用に関するガイドをご覧ください。

データのパイプライン

CrUX データセットはパイプラインで処理され、データを統合、集計、フィルタしてから API を通じて利用できるようになります。

移動平均

Chrome UX レポートのデータは、集計指標の 28 日間の移動平均です。つまり、Chrome UX レポートに表示される特定の時点のデータは、実際には過去 28 日間の集計データであるということです。

History API には、それぞれ過去 28 日間にわたるさまざまな収集期間が含まれています。各収集期間には過去 28 日間の集計データが含まれ、収集期間は 1 週間ごとであるため、収集期間は重複します。これはデータの移動平均に似ており、後続の各期間に 3 週間分のデータが含まれます（1 週間は異なります）。

毎週の更新

History API は毎週月曜日の 04:00 UTC 頃に更新され、（標準の 2 日間のラグに従って）前の土曜日までのデータが格納されています。過去 25 週間（約 6 か月）分のデータが含まれます。収集期間は 1 週間に 1 回です。

更新時刻に関するサービスレベル契約はありません。更新はベスト エフォート ベースで毎日実行されます。

スキーマ

CrUX History API には POST HTTP リクエストを受け入れるエンドポイントが 1 つあります。API は、リクエストされたオリジンまたはページに関するパフォーマンス データに対応する 1 つ以上の metrics を含む record を返します。

HTTP リクエスト

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

この URL は gRPC Transcoding 構文を使用します。

リクエスト本文

CrUX History API は、effectiveConnectionType リクエスト フィールドがサポートされていないことを除き、毎日の CrUX API と同じリクエスト本文を使用します。

たとえば、web.dev ホームページのパソコン用の Largest Contentful Paint 値をリクエストするには、次のようにします。

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

レスポンスの本文

リクエストが成功すると、record オブジェクトと urlNormalizationDetails を含むレスポンスが次の構造の形で返されます。

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

たとえば、前のリクエストのリクエスト本文に対するレスポンスは次のようになります。

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

キー

Key は、このレコードを一意として識別するすべてのディメンションを定義します。

{
  "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.
}
フィールド
formFactor

enum (FormFactor)

フォーム ファクタは、すべてのユーザーがこのレコードのサイトにアクセスするために使用するデバイスクラスです。

フォーム ファクタが指定されていない場合は、すべてのフォーム ファクタの集計データが返されます。
共用体フィールド url_pattern。URL パターンは、レコードが適用される URL です。url_pattern は次のいずれかになります。
origin

string

Origin には、このレコードの対象となるオリジンを指定します。

注: オリジンを指定すると、そのオリジンでのすべてのページにわたる読み込みデータは、オリジン レベルのユーザー エクスペリエンス データに集計されます。
url

string

url には、このレコードの対象となる特定の URL を指定します。

注: url を指定した場合は、その URL のデータのみが集計されます。

指標

metric は、First Contentful Paint など、単一のウェブ パフォーマンス指標のユーザー エクスペリエンス データのセットです。これには、実際の Chrome 使用状況のサマリー ヒストグラムが一連の bins として含まれます。

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

または

"fractionTimeseries": {
  object (Fractions)
}
フィールド
histogramTimeseries[]

object (Bin)

指標のユーザー エクスペリエンスの時系列ヒストグラム。時系列ヒストグラムには少なくとも 1 つのビンがあり、すべてのビンの密度の合計が約 1 になります。

特定の収集期間で欠損している値は、"NaN" とマークされます。
percentilesTimeseries

object (Percentiles)

指標の一般的な有用なパーセンタイル。パーセンタイルの値の型は、ヒストグラムのビンに指定された値の型と同じです。

特定の収集期間で欠損している値は、null とマークされます。
fractionTimeseries

object (Fractions)

このオブジェクトには、ラベル付きの割合の時系列が含まれます。合計でエントリあたり最大 1 になります。

小数は小数点第 4 位に四捨五入されます。

欠落しているエントリは、すべての分数で「NaN」と表されます。

ビン

bin は、開始から終了までにわたる、または開始から正の無限大まで終了が指定されていない場合、データの離散部分です。

ビンの開始値と終了値は、ビンが表す指標の値の型で指定されます。たとえば、First Contentful Paint はミリ秒単位で測定され、int として公開されるため、指標ビンでは開始型と終了型に int32 が使用されます。ただし、累積レイアウト シフトは単位のない 10 進数で測定され、文字列としてエンコードされた 10 進数として公開されるため、指標ビンはその値の型に文字列を使用します。

{
  "start": value,
  "end": value,
  "densities": [number, number, number...etc.]
}
フィールド
start

(integer | string)

Start はデータビンの先頭です。
end

(integer | string)

[終了] は、データビンの終わりです。end が設定されていない場合、ビンには終了がなく、開始から +inf まで有効です。
densities

array[number]

特定の指標でこのビンの値が発生したユーザーの割合の時系列。

密度は小数点第 4 位に四捨五入されます。

パーセンタイル

Percentiles には、特定の統計パーセンタイルにおける指標の合成値が含まれます。合計ユーザー数に対する一定の割合のユーザーが経験する指標の値を推定するために使用されます。

{
  "P75": value
}
フィールド
p75s

array[(integer | string)]

この値以下の特定の指標が、ページ読み込みの 75% で発生している値の時系列です。

分数

Fractions には、エントリごとに合計で最大 1 となるラベル付き小数の時系列が含まれます。各ラベルはページ読み込みをなんらかの方法で表しているため、この方法で表される指標は数値ではなく個別の値を生成すると考えることができ、比率は特定の個別の値が測定される頻度を表します。

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

ヒストグラムのビンの密度値と同様に、各 fraction は 0.0 <= value <= 1.0 ��数値で、合計で約 1.0 になります。特定の収集期間で指標が使用できない場合、対応するエントリは小数のすべての配列で「NaN」になります。

フィールド
p75s

array[(integer | string)]

この値以下の特定の指標が、ページ読み込みの 75% で発生している値の時系列です。

UrlNormalization

検索の成功率を高めるために URL を正規化するために実行される正規化アクションを表すオブジェクト。これらは、指定された url_pattern の検索時に行われる単純な自動変更であり、失敗することがわかっています。リダイレクトの後の処理のような複雑なアクションは処理されません。

{
  "originalUrl": string,
  "normalizedUrl": string
}
フィールド
originalUrl

string

正規化アクションの前にリクエストされていた元の URL。
normalizedUrl

string

正規化アクション後の URL。これは妥当な検索が可能な、有効なユーザー エクスペリエンス URL です。

レート制限

CrUX History API でも、CrUX API と同じ上限が適用され、Google Cloud プロジェクトごとに 1 分あたり 150 クエリまでクエリできます。なお、この API は無料で提供されます。この上限と現在の使用量は、Google Cloud コンソールで確認できます。大半のユースケースには、この十分な割り当てで十分です。割り当ての増加に対して料金を支払うことはできません。