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 では、これらの識別子はウェブページとウェブサイトです。

出発地

識別子がオリジンの場合、そのオリジン内のすべてのページに存在するすべてのデータが集計されます。たとえば、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 

識別子が URL に設定され、値が http://www.example.com/foo.html の場合、そのページのデータのみが返されます。

ディメンション

ディメンションは、レコードが集計される特定のデータグループを識別します。たとえば、フォーム ファクタが PHONE の場合、レコードにはモバイル デバイスで行われた読み込みに関する情報が含まれていることを示します。各ディメンションには一定数の値があり、そのディメンションを指定しない場合、そのディメンションはすべての値で集計されます。たとえば、フォーム ファクタを指定しない場合は、どのフォーム ファクタで行われた読み込みに関する情報がレコードに含まれることを示します。

フォーム ファクタ

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

指標

指標は、ヒストグラム、パーセンタイル、小数で統計集計として報告されます。

浮動小数点値は小数点以下 4 桁に丸められます（cumulative_layout_shift 指標は文字列としてエンコードされたダブル値であるため、浮動小数点数と見なされず、文字列内で小数点以下 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% となります。

指標値の型

BigQuery 指標名のマッピング

収集期間

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

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

これにより、データの状況を把握し、その日のデータがまだ更新されていないか、昨日と同じデータが返されているかを把握できます。

収集期間は PageSpeed Insights でも確認できます。

また、データが 28 日間分ではない場合でも（たとえば、ページがリリースされてから 28 日未満の場合）、collectionPeriod には常に 28 日間と表示されます。collectionPeriod は、CrUX データが集計された期間であり、必ずしもデータが表す期間ではありません。

クエリの例

クエリは、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
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• form_factors（リクエストで formFactor が指定されていない場合にのみ報告されます）

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

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

データ パイプライン

CrUX データセットはパイプラインを介して処理され、統合、集計、フィルタリングされた後、API で使用できるようになります。

移動平均

Chrome UX レポートのデータは、集計された指標の 28 日間の移動平均です。つまり、Chrome UX レポートに表示されるデータは、実際には過去 28 日間のデータが集計されたものです。

これは、BigQuery の CrUX データセットが月次レポートを集計する方法と同様です。

毎日の通知

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

スキーマ

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

HTTP リクエスト

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

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

リクエストの本文

リクエストの本文には、次の構造のデータを含めます。

{   "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. } 

たとえば、Chrome デベロッパー ドキュメントのホームページのデスクトップの Largest 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 は、このレコードを一意として識別するすべてのディメンションを定義します。

{   "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. } 

指標

metric は、単一のウェブ パフォーマンス指標（First Contentful Paint など）の集計されたユーザー エクスペリエンス データのセットです。実際の Chrome の使用状況の概要ヒストグラム（一連の bins、特定のパーセンタイル データ（p75 など））が含まれる場合や、ラベル付きの分数を含む場合があります。

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

または

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

ビン

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

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

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

パーセンタイル

Percentiles には、特定の統計的パーセンタイルにおける指標の合成値が含まれます。これらの指標は、ユーザーの合計数のうち、何% のユーザーが経験したかを示す指標の値を推定するために使用されます。

{   "P75": value } 

分数

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 } 

レート制限

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