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 ではウェブページやウェブサイトが識別子となります。

原点

識別子がオリジンの場合、そのオリジンのすべてのページに存在するすべてのデータが集計されます。たとえば、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.htmlhttp://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 の場合、レコードにモバイル デバイスで発生した読み込みに関する情報が含まれていることを示します。各ディメンションには特定の数の値があります。そのディメンションを指定しないと、そのディメンションはすべての値に対して集計されます。たとえば、フォーム ファクタを指定しない場合、任意のフォーム ファクタで発生した負荷に関する情報がレコードに含まれます。

フォーム ファクタ

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

有効な接続タイプ

[有効な接続タイプ] は、ページにアクセスしたときに予測されるデバイスの接続品質を示します。これは offlineslow-2G2G3G4G に分かれた一般的なクラスです。

指標

指標は、統計的集計(ヒストグラム、パーセンタイル、分数)で報告されます。

ヒストグラム

指標がヒストグラムで表されている場合は、その指標の特定の範囲内に含まれるページ読み込みの割合が表示されます。

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

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.38179
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.49905
    },
    {
      "start": 3000,
      "density": 0.11916
    }
  ]
}

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

さらに、ページ読み込みの 49.905% で 1,000 ~ 3,000 ミリ秒の範囲の指標値が、11.916% で 3,000 ミリ秒を超える値が表示されていました。

パーセンタイル

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

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

この例では、ページ読み込みの少なくとも 75% が指標値 <= 2063 で測定されました。

分数

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

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

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

指標値のタイプ

CrUX API の指標名 データ型 メートル単位 統計集計 web.dev ドキュメント
cumulative_layout_shift 文字列として二重エンコード 単位なし 3 つのビンを含むヒストグラム、p75 のパーセンタイル cls
first_contentful_paint int ミリ秒 3 つのビンを含むヒストグラム、p75 のパーセンタイル NFC
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

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
form_factors なし

収集期間

2022 年 10 月の時点で、CrUX API には collectionPeriod オブジェクトが含まれており、firstDate フィールドと endDate フィールドは集計期間の開始日と終了日を表します。以下に例を示します。

    "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 オブジェクトとして https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" に送信されます。クエリデータは JSON オブジェクトとしての POST 本文に含められます。次に例を示します。

{
  "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"]}'

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
  • 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 リクエストを受け付ける単一のエンドポイントがあります。API は record を返します。これには、リクエストされたオリジンまたはページに関するパフォーマンス データに対応する 1 つ以上の metrics が含まれます。

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)

フォーム ファクタは、レコードのデータが属するデバイスクラスを指定するクエリ ディメンションです。

このフィールドでは値 DESKTOPPHONETABLET を使用します。

注: フォーム ファクタが指定されていない場合は、すべてのフォーム ファクタの集計データを含む特別なレコードが返されます。

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 パターンは、レコード ルックアップの主な識別子です。複数の型の値のいずれかを指定できます。url_pattern は次のいずれかになります。
origin

string

URL パターンの「origin」は、ウェブサイトのオリジンである URL パターンを指します。

例: "https://example.com""https://cloud.google.com"

url

string

URL パターン「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.98148451581189577
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.010814353596591841
          },
          {
            "start": 4000,
            "density": 0.0077011305915124116
          }
        ],
        "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] では、このレコードの対象オリジンを指定します。

注: オリジンを指定すると、そのオリジンの下でのすべてのページにわたる読み込みデータが、オリジン レベルのユーザー エクスペリエンス データに集計されます。

url

string

Url には、このレコードの対象となる特定の URL を指定します。

注: 「url」を指定すると、その特定の URL のデータのみが集計されます。

指標

metric は、1 つのウェブ パフォーマンス指標(First Contentful Paint など)の集計ユーザー エクスペリエンス データのセットです。実際の Chrome 使用状況のサマリー ヒストグラムには、一連の bins や特定のパーセンタイル データ(p75 など)が含まれることがあります。また、ラベル付きの分数が含まれることもあります。

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

or

{
  "fractions": {
    object (Fractions)
  }
}
フィールド
histogram[]

object (Bin)

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

percentiles

object (Percentiles)

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

fractions

object (Fractions)

このオブジェクトにはラベル付き分数が含まれ、その合計は 1 以下になります。

ビン

bin は、開始から終了までの範囲のデータの個別の部分です。または、開始から正の無限大までの終了が指定されていない場合は、この部分です。

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

{
  "start": value,
  "end": value,
  "density": number
}
フィールド
start

value (Value format)

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

end

value (Value format)

End はデータビンの終わりです。end が入力されていない場合、bin には終わりがなく、start から +inf まで有効です。

density

number

特定の指標について、このビンの値が発生したユーザーの割合。

パーセンタイル

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

{
  "P75": value
}
フィールド
p75

value (Value format)

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 です。

レート制限

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