このページは 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 を使用するには、Google Cloud API キーが必要です。日次 API と履歴 API には同じキーを使用できます。

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

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

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

識別子が 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 ミリ秒のサンプル指標値が発生し、次いで 92.03%、91.94% であったことを示しています。指標の単位はこのヒストグラムに含まれません。この例ではミリ秒と仮定します。

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

パーセンタイル

指標には、詳細な分析に役立つ時系列のパーセンタイルが含まれる場合もあります。

データポイントは、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 の指標の値タイプに関する日別のドキュメントをご覧ください。

指標の利用条件

利用条件によっては、CrUX History API の対象となる収集期間の一部に、オリジンまたは URL を利用できる場合があります。このような場合、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 回の収集期間）が含まれます。

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

クエリの例

クエリは、POST 本文でクエリデータを JSON オブジェクトとして指定した https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]" への 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"]}'

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

API を介してページレベルのデータを使用するには、クエリで origin ではなく url プロパティを渡します。

{
  "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
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 日間の遅延に従って）前土曜日までのデータが含まれています。過去 25 週間（約 6 か月）分のデータ（週 1 回の収集期間）が含まれます。

更新時間に関するサービスレベル契約はなく、ベストエフォートベースで毎日実行されます。

スキーマ

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

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 はミリ秒単位で測定され、整数として公開されるため、指標ビンでは start タイプと end タイプとして int32 が使用されます。ただし、累積レイアウトシフトは単位なしの 10 進数で測定され、文字列としてエンコードされた 10 進数として公開されるため、指標ビンでは値の型に文字列が使用されます。

{
  "start": value,
  "end": value,
  "densities": [number, number, number...etc.]
}

フィールド

フィールド
`start`	`(integer \| string)` [開始] はデータビンの先頭です。
`end`	`(integer \| string)` End はデータビンの終わりです。end に値が入っていない場合、ビンに終わりはなく、start から +inf まで有効です。
`densities`	`array[number]` 特定の指標に対するこのビンの値を受けたユーザーの割合の時系列。密度は小数第 4 位に四捨五入されます。

start

(integer | string)

[開始] はデータビンの先頭です。

end

(integer | string)

End はデータビンの終わりです。end に値が入っていない場合、ビンに終わりはなく、start から +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 と同じ上限で、どちらの API についても Google Cloud プロジェクトごとに 1 分あたり 150 クエリという上限があります（料金はかかりません）。この上限と現在の使用量は、Google Cloud コンソールで確認できます。ほとんどのユースケースは、この十分な割り当てで十分です。割り当ての増加に対して支払うことはできません。

CrUX History API

一般的なユースケース

CrUX API キー

データモデル

記録

識別子

起源

URL

ディメンション

指標

ヒストグラム

パーセンタイル

分数

指標の値のタイプ

指標の利用条件

収集期間

クエリの例

データ パイプライン

移動平均

毎週の更新

スキーマ

HTTP リクエスト

リクエスト本文

レスポンスの本文

キー

指標

ビン

パーセンタイル

分数

UrlNormalization

レート制限

データパイプライン