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

CrUX API

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

一般的なユースケース

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

CrUX API キー

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

フォーム・ファクタ

エンドユーザーがページに移動するために使用したデバイスクラス。これはデバイスの一般的なクラスで、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 ミリ秒の間に測定されたことを示しています。このヒストグラムには指標の単位は含まれていません。この例ではミリ秒を想定しています。

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

パーセンタイル

指標には、追加の分析に役立つパーセンタイルが含まれている場合もあります。特定の指標の値は、その指標の指定されたパーセンタイルで報告されます。最終的なビニングされたデータではなく、使用可能なデータの完全なセットに基づいているため、最終的なビニングされたヒストグラムに基づく補間パーセンタイルと必ずしも一致しません。

{
  "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 のヒストグラム	FTP
`first_input_delay` （非推奨）	int	ミリ秒	3 つのビン、パーセンタイルが p75 のヒストグラム	FID
`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`
`first_input_delay`	`first_input.delay`
`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% になるため、API でサポートされている 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
first_input_delay （非推奨）
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", "first_input_delay", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]`
共用体フィールド `url_pattern`。`url_pattern` は、レコード検索のメイン識別子です。次のいずれか 1 つのみを指定できます。
`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/"`

たとえば、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 は、1 つのウェブパフォーマンス指標（First Contentful Paint など）について集計されたユーザーエクスペリエンスデータのセットです。これには、一連の bins としての実際の Chrome 使用��況のサマリーヒストグラムや��特定のパーセンタイルデータ（p75 など）が含まれることや、ラベル付きの割合が含まれる場合があります。

{
  "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 コンソールで確認できます。大半のユースケースには、この十分な割り当てで十分です。割り当ての増加に対して料金を支払うことはできません。