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

CrUX API

CrUX API を使用すると、ページと配信元の粒度で集約された実際のユーザーエクスペリエンスデータに低レイテンシでアクセスできます。

試してみる

一般的なユースケース

CrUX API を使用すると、「https://example.com オリジンの指標を取得する」など、特定の URI に対してユーザーエクスペリエンス指標をクエリできます。

CrUX API キー

CrUX API を使用するには、Chrome UX Report API で使用するためにプロビジョニングされた Google Cloud 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 は、モバイルデバイスで行われた読み込みに関する情報がレコードに含まれていることを示します。各ディメンションには一定数の値がありますが、ディメンションを指定しないと、そのディメンションはすべての値に基づいて集計されます。たとえば、フォームファクタを指定しないと、レコードには任意のフォームファクタで発生した読み込みに関する情報が含まれることになります。

フォーム・ファクタ

エンドユーザーがページに移動するために使用したデバイスクラス。これはデバイスの一般的なクラスで、PHONE、TABLET、DESKTOP に分類されます。

効果的な接続タイプ

有効な接続タイプは、ページに移動したときのデバイスの推定接続品質です。このクラスは、offline、slow-2G、2G、3G、4G に分類されます。

指標

指標は、ヒストグラム、パーセンタイル、比率の統計集計としてレポートされます。

浮動小数点値は小数点第 4 位に丸められます（cumulative_layout_shift 指標は文字列として double にエンコードされるため、浮動小数点数とはみなされず、文字列内の小数点以下 2 桁に報告されます）。

ヒストグラム

指標をヒストグラムで表している場合は、ページ読み込みのうちその指標の特定の範囲を選択します。

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

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

このデータは、ページ読み込みの 38.18% でサンプルの指標が測定されたことを示しています 0 ～ 1,000 ms に設定します。このヒストグラムには指標の単位が含まれていません。ここではミリ秒単位と仮定します。

さらに、ページ読み込みの 49.91% で 1,000 ～ 3,000 ms の指標値が見られ、11.92% が 3,000ms を超える値を確認しました

パーセンタイル

指標には、追加の分析に役立つパーセンタイルが含まれている場合もあります。特定の指標の特定のパーセンタイル値が報告されます。最終的なビニングされたデータではなく、利用可能なすべてのデータに基づくものです。ですから、予測値に基づく補間パーセンタイルと最終的なビンニングヒストグラムになります。

{
  "percentiles": {
    "p75": 2063
  }
}

この例では、ページの読み込みの 75% 以上が指標値 <= 2063 で測定されています。

分数

割合は、特定の方法でラベル付けできるページ読み込みの割合を示します。この場合、指標値はこれらのラベルです。

たとえば、form_factors 指標は、指定されたクエリがカバーするフォームファクタ（またはデバイス）の内訳を示す fractions オブジェクトで構成されています。

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

この例では、ページ読み込みの 3.77% がパソコンで、2.88% がタブレットで、93.35% がスマートフォンで測定されており、合計で 100% となります。

指標値のタイプ

CrUX API の指標名	データ型	メートル単位	統計集計	ドキュメント
`cumulative_layout_shift`	文字列として二重エンコードされる小数点以下 2 桁	単位なし	3 つのビン、パーセンタイルが p75 のヒストグラム	cls
`first_contentful_paint`	int	ミリ秒	3 つのビン、パーセンタイルが p75 のヒストグラム	fcp
`interaction_to_next_paint`	int	ミリ秒	3 つのビン、パーセンタイルが p75 のヒストグラム	inp
`largest_contentful_paint`	int	ミリ秒	3 つのビン、パーセンタイルが p75 のヒストグラム	lcp
`experimental_time_to_first_byte`	int	ミリ秒	3 つのビン、パーセンタイルが p75 のヒストグラム	ttfb
`form_factors`	小数第 4 位の倍精度	パーセント	フォームファクタからフラクションへのマッピング	フォームファクタ
`navigation_types`	小数第 4 位の倍精度	パーセント	ナビゲーションタイプから分数へのマッピング	ナビゲーションタイプ
`round_trip_time`	int	ミリ秒	パーセンタイルを p75 と	rtt

BigQuery 指標名のマッピング

CrUX API の指標名	BigQuery 指標名
`cumulative_layout_shift`	`layout_instability.cumulative_layout_shift`
`first_contentful_paint`	`first_contentful_paint`
`interaction_to_next_paint`	`interaction_to_next_paint`
`largest_contentful_paint`	`largest_contentful_paint`
`experimental_time_to_first_byte`	`experimental.time_to_first_byte`
`navigation_types`	`navigation_types`
`form_factors`	なし
`round_trip_time`	なし

注: CrUX BigQuery では、ヒストグラムの密度とすべてのフォームファクタで原点ごとに 100% になるため、form_factors ヒストグラムで表します。 first_contentful_paint の密度。

収集期間

2022 年 10 月現在、CrUX API には、集計期間の開始日と終了日を表す firstDate フィールドと endDate フィールドを持つ collectionPeriod オブジェクトが含まれています。例:

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

これにより、データの詳細や、その日のデータがまだ更新されていないか、昨日と同じデータが返されているかを確認できます。

CrUX API は、その日の完成データを待つため、その日の約 2 日遅れています。また、この API で使用可能になるまでに、ある程度の処理時間を要することに注意してください。使用されるタイムゾーンは太平洋標準時（PST）で、夏時間の変更はありません。

クエリの例

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

{
  "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:queryRecord?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 行を使用する必要があります。

クエリで 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
form_factors（リクエストで formFactor が指定されていない場合にのみ報告）

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

その他のクエリの例については、Chrome UX Report API を使用するをご覧ください。

データパイプライン

CrUX データセットはパイプラインで処理され、API で使用可能になる前にデータを統合、集計、フィルタします。

移動平均

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

これは、BigQuery の CrUX データセットで月次レポートを集計する方法に似ています。

毎日の通知

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

スキーマ

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

HTTP リクエスト

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

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

リクエスト本文

リクエストの本文には、次の構造のデータを含める必要があります。

{
  "effectiveConnectionType": string,
  "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.
}

フィールド
`effectiveConnectionType`	`string` 有効な接続タイプは、レコードのデータが属する有効なネットワーククラスを指定するクエリディメンションです。このフィールドには、Network Information API 仕様で指定されている値 `["offline", "slow-2G", "2G", "3G", "4G"]` を使用します。注: 有効な接続タイプが指定されていない場合は、すべての有効な接続タイプの集計データを含む特別なレコードが返されます。
`formFactor`	`enum`（`FormFactor`）フォームファクタは、レコードのデータが属するデバイスクラスを指定するクエリディメンションです。このフィールドには、`DESKTOP`、`PHONE`、または `TABLET` の値を使用します。注: フォームファクタが指定されていない場合は、すべてのフォームファクタの集計データを含む特別なレコードが返されます。
`metrics[]`	`string` レスポンスに含める必要がある指標。指定しない場合は、見つかったすべての指標が返されます。使用できる値: `["cumulative_layout_shift", "first_contentful_paint", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]`
共用体フィールド `url_pattern`。`url_pattern` は、レコード検索のメイン識別子です。次のいずれか 1 つのみを指定できます。
`origin`	`string` `url_pattern` の「origin」ウェブサイトのオリジンである 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/"`

たとえば、Chrome デベロッパー向けドキュメントのホームページについて、パソコンで最大の Contentful Paint 値をリクエストするには、次のようにします。

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

レスポンスの本文

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

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

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

{
  "record": {
    "key": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.9815
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.0108
          },
          {
            "start": 4000,
            "density": 0.0077
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

キー

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

{
  "effectiveConnectionType": string,
  "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)` フォームファクタは、すべてのユーザーがこのレコードのサイトにアクセスするために使用するデバイスクラスです。フォームファクタが指定されていない場合は、すべてのフォームファクタの集計データが返されます。
`effectiveConnectionType`	`string` 有効な接続タイプは、このレコードですべてのユーザーが経験した一般的な接続クラスです。このフィールドでは、https://wicg.github.io/netinfo/#effective-connection-types で指定されている値 ["offline", "slow-2G", "2G", "3G", "4G"] が使用されます。有効な接続タイプが指定されていない場合は、すべての有効な接続タイプの集計データが返されます。
共用体フィールド `url_pattern`。URL パターンは、レコードが適用される URL です。`url_pattern` は次のいずれかになります。
`origin`	`string` `origin` には、このレコードの対象となるオリジンを指定します。注: `origin` を指定すると、このオリジンでのすべてのページにわたる読み込みデータが、オリジンレベルのユーザーエクスペリエンスデータに集計されます。
`url`	`string` `url` には、このレコードの対象となる特定の URL を指定します。注: `url` を指定した場合は、その URL のデータのみが集計されます。

指標

metric は、単一のウェブパフォーマンス指標（ファーストコンテンツペイントなど）の集計されたユーザーエクスペリエンスデータのセットです。これには、実際の Chrome 使用状況のサマリーヒストグラムが、一連の bins（特定のパーセンタイルデータ）として含まれる場合があります。または、ラベル付きの分数が含まれていることがあります。

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

または

{
  "fractions": {
    object (Fractions)
  }
}

フィールド

フィールド
`histogram[]`	`object (Bin)` 指標のユーザーエクスペリエンスのヒストグラム。ヒストグラムには少なくとも 1 つのビンがあり、すべてのビンの密度の合計が約 1 になります。
`percentiles`	`object (Percentiles)` 指標の一般的な有用なパーセンタイル。パーセンタイル値の値の型は、ヒストグラムのビンに指定された値の型と同じになります。
`fractions`	`object (Fractions)` このオブジェクトにはラベル付きの分数が含まれています。合計で最大 1 になります。小数は小数点第 4 位に四捨五入されます。

histogram[]

object (Bin)

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

percentiles

object (Percentiles)

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

fractions

object (Fractions)

このオブジェクトにはラベル付きの分数が含まれています。合計で最大 1 になります。

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

ビン

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

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

{
  "start": value,
  "end": value,
  "density": number
}

フィールド

フィールド
`start`	`(integer \| string)` Start はデータビンの先頭です。
`end`	`(integer \| string)` [終了] は、データビンの終わりです。end が設定されていない場合、ビンには終了がなく、開始から +inf まで有効です。
`density`	`number` 特定の指標でこのビンの値が発生したユーザーの割合。密度は小数点第 4 位に四捨五入されます。

start

(integer | string)

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

end

(integer | string)

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

density

number

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

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

パーセンタイル

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

{
  "P75": value
}

フィールド

フィールド
`p75`	`(integer \| string)` ページの読み込みの 75% で、指定した指標がこの値以下でした。

p75

(integer | string)

ページの読み込みの 75% で、指定した指標がこの値以下でした。

分数

Fractions には、合計で最大 1 となるラベル付きの分数が含まれます。各ラベルは、表示されるため、この形式で表される指標は数値の代わりに個別の値を生成し、比率を特定の個別値が測定される頻度です

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

ヒストグラムのビンの密度値と同様に、各 fraction は数値です。 0.0 <= value <= 1.0 合計すると約 1.0 になります。

UrlNormalization

正常なルックアップを実現するために URL を正規化するために実行された正規化アクションを表すオブジェクト。これらは、指定された url_pattern の検索が失敗することが判明した場合に実行される、単純な自動変更です。リダイレクトの後の処理のような複雑なアクションは処理されません。

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

フィールド

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

originalUrl

string

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

normalizedUrl

string

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

レート制限

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

CrUX API

一般的なユースケース

CrUX API キー

API キーの取得と使用

データモデル

記録

識別子

出発地

URL

ディメンション

フォーム・ファクタ

効果的な接続タイプ

指標

ヒストグラム

パーセンタイル

分数

指標値のタイプ

BigQuery 指標名のマッピング

収集期間

クエリの例

データ パイプライン

移動平均

毎日の通知

スキーマ

HTTP リクエスト

リクエスト本文

レスポンスの本文

キー

指標

ビン

パーセンタイル

分数

UrlNormalization

レート制限

データパイプライン