このページは Cloud Translation API によって翻訳されました。

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 を使用するには、Chrome UX Report API で使用するためにプロビジョニングされた Google Cloud API キーが必要です。同じキーを Daily API と History API で使用できます。

API キーの取得と使用

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

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

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

注: 上記の例は、Windows 用の Git BASH シェルを含む、macOS または Linux ベースのシステム用です。わずかな変更が必要なシステムもあります。たとえば、cmd.exe コマンドラインでは、パラメータに単一引用符を使用することも、行の継続（\）も使用できないため、二重引用符を使用すること（\" で必要に応じて内側の引用符をエスケープする）と、1 行を使用する必要があります。

クエリで 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
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」と表されます。

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 位に四捨五入されます。

start

(integer | string)

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

end

(integer | string)

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

densities

array[number]

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

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

パーセンタイル

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

{
  "P75": value
}

フィールド

フィールド
`p75s`	`array[(integer \| string)]` この値以下の特定の指標が、ページ読み込みの 75% で発生している値の時系列です。

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% で発生している値の時系列です。

p75s

array[(integer | string)]

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

UrlNormalization

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

{
  "originalUrl": string,
  "normalizedUrl": string
}

フィールド

フィールド
`originalUrl`	`string` 正規化アクションの前にリクエストされていた元の URL。
`normalizedUrl`	`string` 正規化アクション後の URL。これは妥当な検索が可能な、有効なユーザーエクスペリエンス URL です。

originalUrl

string

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

normalizedUrl

string

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

レート制限

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

CrUX History API

一般的なユースケース

CrUX API キー

API キーの取得と使用

データモデル

記録

識別子

出発地

URL

ディメンション

指標

ヒストグラム

パーセンタイル

分数

指標値のタイプ

指標の要件

収集期間

クエリの例

データ パイプライン

移動平均

毎週の更新

スキーマ

HTTP リクエスト

リクエスト本文

レスポンスの本文

キー

指標

ビン

パーセンタイル

分数

UrlNormalization

レート制限

データパイプライン