CrUX API

CrUX API を使用すると、ページ単位およびオリジン単位で集計された実際のユーザー エクスペリエンス データに低レイテンシでアクセスできます。

試してみる

一般的なユースケース

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

CrUX API キー

CrUX API を使用するには、Chrome UX Report API の使用用にプロビジョニングされた Google Cloud API キーが必要です。

API キーの取得と使用

または、認証情報ページでキーを作成することもできます。

API キーを作成したら、アプリケーションですべてのリクエスト URL の末尾にクエリ パラメータ key=yourAPIKey を追加できます。

API キーは、安全に URL に埋め込むことができます。エンコーディングの必要はありません。

クエリの例をご覧ください。

データモデル

このセクションでは、リクエストとレスポンスのデータ構造について詳しく説明します。

録画

ページまたはサイトに関する個別の情報。レコードには、識別子に固有のデータと、ディメンションの特定の組み合わせに固有のデータを含めることができます。1 つのレコードに 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

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

サイズ

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

フォーム ファクタ

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

指標

レポート指標は、ヒストグラム、パーセンタイル、分数で統計的に集計してレポートします。

浮動小数点値は小数点以下 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 ミリ秒、11.92% で 3,000 ミリ秒を超えています。

パーセンタイル

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

{
  "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 でも確認できます。

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

クエリの例

クエリは、POST リクエストを使用して https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" に 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_cumulative_layout_shift_with_softnavs
• experimental_first_contentful_paint_with_softnavs
• experimental_interaction_to_next_paint_with_softnavs
• experimental_largest_contentful_paint_with_softnavs
• experimental_navigation_types_with_softnavs
• 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 が指定されていない場合にのみ報告されます）
• experimental_ad_count（広告指標に含まれるページのみレポートされます）
• experimental_ad_density（広告指標に含まれるページのみレポートされます）
• experimental_ad_cpu（広告指標に含まれるページのみレポートされます）
• experimental_ad_kilobytes（広告指標に含まれるページのみレポートされます）

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

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

データ パイプライン

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

移動平均

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

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

日次更新

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

スキーマ

CrUX API には、POST HTTP リクエストを受け入れる単一のエンドポイントがあります。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 は、1 つのウェブ パフォーマンス指標（First Contentful Paint など）に関する集計されたユーザー エクスペリエンス データのセットです。これには、一連の bins、特定のパーセンタイル データ（p75 など）として、実際の Chrome の使用状況の概要ヒストグラムが含まれる場合があります。また、ラベル付きの割合が含まれる場合もあります。

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

または

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

ビン

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

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

{
  "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 クエリに制限されており、無料で提供されています。この上限と現在の使用量は、Google Cloud コンソール で確認できます。この割り当ては、ほとんどのユースケースで十分なはずです。割り当てを増やすために料金を支払うことはできません。