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 のヒストグラム | 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 |
なし |
収集期間
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"]}'
クエリで 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 |
有効な接続タイプは、レコードのデータが属する有効なネットワーク クラスを指定するクエリ ディメンションです。 このフィールドには、Network Information API 仕様で指定されている値 注: 有効な接続タイプが指定されていない場合は、すべての有効な接続タイプの集計データを含む特別なレコードが返されます。 |
formFactor |
フォーム ファクタは、レコードのデータが属するデバイスクラスを指定するクエリ ディメンションです。 このフィールドでは、値 注: フォーム ファクタが指定されていない場合は、すべてのフォーム ファクタの集計データを含む特別なレコードが返されます。 |
metrics[] |
レスポンスに含める必要がある指標。指定しない場合は、見つかったすべての指標が返されます。 使用できる値: |
共用体フィールド url_ 。url_pattern は、レコード検索のメイン識別子です。次のいずれか 1 つのみを指定できます。 |
|
origin |
例: |
url |
例: |
たとえば、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 |
フォーム ファクタは、すべてのユーザーがこのレコードのサイトにアクセスするために使用するデバイスクラスです。 フォーム ファクタが指定されていない場合は、すべてのフォーム ファクタの集計データが返されます。 |
effectiveConnectionType |
有効な接続タイプは、このレコードですべてのユーザーが経験した一般的な接続クラスです。このフィールドでは、https://wicg.github.io/netinfo/#effective-connection-types で指定されている値 ["offline", "slow-2G", "2G", "3G", "4G"] が使用されます。 有効な接続タイプが指定されていない場合は、すべての有効な接続タイプの集計データが返されます。 |
共用体フィールド url_ 。URL パターンは、レコードが適用される URL です。url_ は次のいずれかになります。 |
|
origin |
注: |
url |
注: |
指標
metric
は、1 つのウェブ パフォーマンス指標(First Contentful Paint など)について集計されたユーザー エクスペリエンス データのセットです。
これには、実際の Chrome 使用状況のサマリー ヒストグラムが、一連の bins
(特定のパーセンタイル データ)として含まれる場合があります。
または、ラベル付きの分数が含まれていることがあります。
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
または
{
"fractions": {
object (Fractions)
}
}
フィールド | |
---|---|
histogram[] |
指標のユーザー エクスペリエンスのヒストグラム。ヒストグラムには少なくとも 1 つのビンがあり、すべてのビンの密度の合計が約 1 になります。 |
percentiles |
指標の一般的な有用なパーセンタイル。パーセンタイルの値の型は、ヒストグラムのビンに指定された値の型と同じです。 |
fractions |
このオブジェクトにはラベル付きの分数が含まれています。合計で最大 1 になります。 小数は小数点第 4 位に四捨五入されます。 |
ビン
bin
は、開始から終了までにわたる、または開始から正の無限大まで終了が指定されていない場合、データの離散部分です。
ビンの開始値と終了値は、ビンが表す指標の値の型で指定されます。たとえば、First Contentful Paint はミリ秒単位で測定され、int として公開されるため、指標ビンでは開始型と終了型に int32 が使用されます。ただし、累積レイアウト シフトは単位のない 10 進数で測定され、文字列としてエンコードされた 10 進数として公開されるため、指標ビンはその値の型に文字列を使用します。
{
"start": value,
"end": value,
"density": number
}
フィールド | |
---|---|
start |
Start はデータビンの先頭です。 |
end |
[終了] は、データビンの終わりです。end が設定されていない場合、ビンには終了がなく、開始から +inf まで有効です。 |
density |
特定の指標でこのビンの値が発生したユーザーの割合。 密度は小数点第 4 位に四捨五入されます。 |
パーセンタイル
Percentiles
には、特定の統計パーセンタイルにおける指標の合成値が含まれます。合計ユーザー数に対する一定の割合のユーザーが経験する指標の値を推定するために使用されます。
{
"P75": value
}
フィールド | |
---|---|
p75 |
ページの読み込みの 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 |
正規化アクションの前にリクエストされていた元の URL。 |
normalizedUrl |
正規化アクション後の URL。これは妥当な検索が可能な、有効なユーザー エクスペリエンス URL です。 |
レート制限
CrUX API は、Google Cloud プロジェクトごとに 1 分あたり 150 クエリに制限されています。これは無料で提供されます。この上限と現在の使用量は、Google Cloud コンソールで確認できます。大半のユースケースには、この十分な割り当てで十分です。割り当ての増加に対して料金を支払うことはできません。