CrUX History API

公開日: 2023 年 2 月 7 日、最終更新日: 2025 年 4 月 11 日

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

試してみる

一般的なユースケース

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

History API は、値が配列で指定され、キーに複数形の名前が付けられていることを除き、1 日単位の CrUX API と同じ構造になっています(例: histogram ではなく histogramTimeseriesp75 ではなく p75s)。

CrUX API キー

daily API と同様に、CrUX History API を使用するには、Chrome UX Report API の使用用にプロビジョニングされた Google Cloud API キーが必要です。daily API と history API には同じキーを使用できます。

API キーの取得と使用

キーの取得

または、認証情報ページでキーを作成することもできます。

API キーを作成したら、アプリケーションですべてのリクエスト URL の末尾にクエリ パラメータ key=yourAPIKey を追加できます。

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

クエリの例をご覧ください。

データモデル

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

録画

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

識別子

識別子には、検索するレコードを指定します。CrUX では、これらの識別子はウェブページとウェブサイトです。

出発地

識別子がオリジンの場合、そのオリジン内のすべてのページに存在するすべてのデータが集計されます。たとえば、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.htmlhttp://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

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

ディメンション

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

フォーム ファクタ

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

指標

指標は、ヒストグラム、パーセンタイル、小数値などの統計集計のタイムシリーズで報告されます。

ヒストグラム

指標がヒストグラム配列で表されている場合、各時系列エントリは、指標が区間に含まれるページ読み込みの割合を、全ページ読み込みに比例して表します。データポイントは、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" を、percentilesTimeseriesnull を返します。この違いは、ヒストグラムの密度は常に数値であるのに対し、パーセンタイルには数値と文字列の両方を使用できるためです(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 日間の遅延に従います)。過去 40 週間分のデータ(1 週間あたり 1 回分の収集期間)が含まれます。デフォルトでは、25 個の収集期間が返されます。これを変更するには、リクエストの "collectionPeriodCount" を 1 ~ 40 の数字に設定します。

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

クエリの例

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

queryHistoryRecord は、日次 CrUX API の queryRecord に代わるものです。

本文の例を次に示します。

{
  "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
  • interaction_to_next_paint
  • largest_contentful_paint
  • experimental_time_to_first_byte
  • largest_contentful_paint_resource_type
  • largest_contentful_paint_image_time_to_first_byte
  • largest_contentful_paint_image_resource_load_delay
  • largest_contentful_paint_image_resource_load_duration
  • largest_contentful_paint_image_element_render_delay
  • navigation_types
  • round_trip_time
  • form_factors(リクエストで formFactor が指定されていない場合にのみ報告されます)

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

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

データ パイプライン

CrUX データセットはパイプラインを介して処理され、データの統合、集計、フィルタリングが行われてから API で利用可能になります。

移動平均

Chrome UX レポートのデータは、集計された指標の 28 日間の移動平均です。つまり、Chrome UX レポートに表示されるデータは、実際には過去 28 日間のデータが集計されたものです。

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

週次更新

History API は毎週月曜日の 04:00 UTC 頃に更新され、前週の土曜日までのデータが含まれます(標準の 2 日間の遅延に基づく)。過去 40 週間(約 10 か月)分のデータを収集し、1 週間に 1 回収集します。デフォルトでは、時系列ごとに 25 件のエントリが返されますが、collectionPeriodCount リクエスト パラメータを指定することでオーバーライドできます。

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

スキーマ

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 は、1 日単位の CrUX API と同様のリクエスト本文を使用しますが、オプションで "collectionPeriodCount" フィールドを 1 つ追加できます。

{
  "formFactor": enum (FormFactor),
  "metrics": [
    string
  ],

  // 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.

  "collectionPeriodCount": int32 // Optional: Number of periods to collect
}
フィールド
formFactor

enumFormFactor

フォーム ファクタは、レコードのデータが属するデバイスクラスを指定するクエリ ディメンションです。

このフィールドには、DESKTOPPHONE、または TABLET の値を使用します。

注: フォーム ファクタを指定しない場合は、すべてのフォーム ファクタの集計データを含む特別なレコードが返されます。

metrics[]

string

レスポンスに含める指標。指定しない場合は、見つかった指標がすべて返されます。

使用できる値: ["cumulative_layout_shift", "first_contentful_paint", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte", "largest_contentful_paint_resource_type", "largest_contentful_paint_image_time_to_first_byte", "largest_contentful_paint_image_resource_load_delay", "largest_contentful_paint_image_resource_load_duration", "largest_contentful_paint_image_element_render_delay", "navigation_types", "round_trip_time"]

共用体フィールド url_patternurl_pattern は、レコード検索の主な識別子です。次のいずれかになります。
origin

string

url_pattern の「オリジン」は、ウェブサイトのオリジンである URL パターンを指します。

例: "https://example.com""https://cloud.google.com"

url

string

url_pattern url は、任意の URL である URL パターンを参照します。

例: "https://example.com/https://cloud.google.com/why-google-cloud/"

共用体フィールド url_pattern の終了。
collectionPeriodCount

int32(省略可)

返す収集期間の数(1 ~ 40)。デフォルトは 25 です。

collectionPeriodCount が指定されていない場合は、デフォルトの 25 が返されます。

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

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

この類似リクエストには省略可能な collectionPeriodCount フィールドが含まれており、40 個の時系列エントリが生成され、https://web.dev オリジンの約 10 か月間のウェブ パフォーマンス履歴が提供されます。

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

レスポンスの本文

リクエストが成功すると、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 はデータビンの終了です。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 と同じ上限を共有しています。どちらの API でも、Google Cloud プロジェクトごとに 1 分あたり 150 件のクエリが許可され、料金は発生しません。この上限と現在の使用量は、Google Cloud コンソールで確認できます。この割り当てはほとんどのユースケースで十分な量ですが、割り当ての増加に対して料金を支払うことはできません。