CrUX API

CrUX API 可讓您以低延遲的方式，取得以網頁和來源為精細層級的匯總實際使用者體驗資料。

試試看！

常見用途

CrUX API 可讓您針對特定 URI 查詢使用者體驗指標，例如「取得 https://example.com 來源的指標」。

CrUX API 金鑰

如要使用 CrUX API，您必須為 Chrome UX Report API 使用方式提供 Google Cloud API 金鑰。

取得並使用 API 金鑰

或者，您也可以在「憑證」頁面中建立一個。

取得 API 金鑰後，您的應用程式可以將查詢參數 key=yourAPIKey 附加到所有的要求網址。

API 金鑰可以安全地嵌入網址中，不需任何編碼。

請參閱「查詢範例」。

資料模型

本節將詳細說明要求和回應中的資料結構。

錄影

網頁或網站的個別資訊。記錄可以包含特定 ID 和維度組合的資料。記錄可包含一或多個指標的資料。

ID

識別碼會指定應查詢的記錄。在 CrUX 中，這些 ID 是網頁和網站。

來源

如果 ID 是來源，系統會將該來源中所有網頁的所有資料匯總在一起。舉例來說，假設 http://www.example.com 來源有以下 Sitemap 所列的網頁：

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

也就是說，當您查詢 Chrome 使用者體驗報告時，如果來源設為 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 來源 Sitemap：

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

如果 ID 設為網址，且值為 http://www.example.com/foo.html，系統只會傳回該網頁的資料。

尺寸

維度可識別記錄匯總的特定資料群組，例如，如果格式為 PHONE，表示記錄包含行動裝置上載入作業的相關資訊。每個維度都會有一定數量的值，如果未明確指定該維度，系統會將維度匯總為所有值。舉例來說，如果指定為「無」板型規格，表示記錄包含任何板型規格載入作業的相關資訊。

板型規格

使用者用來前往網頁的裝置類別。這是裝置的一般類別，可分為 PHONE、TABLET 和 DESKTOP。

指標

我們會以統計匯總資料，以直方圖、百分位數和小數的形式回報指標。

浮點值會四捨五入 (請注意，cumulative_layout_shift 指標是將雙精度編碼為字串，因此不視為浮點數，且會以字串格式回報至小數點後 2 位)。

直方圖

當指標以直方圖表示時，我們會顯示網頁載入量落在該指標特定範圍內的百分比。

以下是某個指標的三個值區直方圖：

{
  "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,000ms 和 3,000ms 之間，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%。

指標值類型

BigQuery 指標名稱對應

收集期間

自 2022 年 10 月起，CrUX API 包含 collectionPeriod 物件，其中 firstDate 和 endDate 欄位代表匯總期間的開始日期和結束日期。例如：

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

這樣一來，您就能更深入瞭解資料，並判斷資料是否已更新至當天，或是會傳回與前一天相同的資料。

您也可以在 PageSpeed Insights 中查看收集期間：

此外，即使資料並非涵蓋整個 28 天 (例如網頁推出時間不到 28 天)，collectionPeriod 一律會顯示 28 天。collectionPeriod 是 CrUX 資料匯總的時間範圍，不一定是資料代表的時間範圍。

查詢範例

查詢會以 JSON 物件形式，透過 POST 要求提交至 https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]"，其中查詢資料會以 POST 主體中的 JSON 物件形式傳送：

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

舉例來說，您可以使用下列指令列 (將 API_KEY 替換為您的鍵) 從 curl 呼叫此方法：

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

您可以透過在查詢中傳遞 url 屬性 (而非 origin)，透過 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 使用者體驗報告中的資料是匯總指標的 28 天滾動平均值。也就是說，Chrome 使用者體驗報告在任何時間點顯示的資料，其實是過去 28 天的資料匯總。

這與 BigQuery 中的 CRUX 資料集匯總月報的方式類似。

每日更新

資料每天會在世界標準時間 04:00 左右更新。更新時間沒有服務水準協議，系統會每天盡力執行。

結構定義

CrUX API 只有一個端點，可接受 POST HTTP 要求。API 會傳回 record，其中包含一或多個 metrics，對應至要求來源或網頁的效能資料。

HTTP 要求

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

這個網址使用 gRPC 轉碼語法。

要求主體

要求主體應包含結構如下的資料：

{
  "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 開發人員說明文件首頁的電腦版最大內容繪製時間值，請按照下列步驟操作：

{
  "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)。這張圖表可能會以一系列 bins 的形式，提供實際 Chrome 使用情形的摘要統計圖，並顯示特定百分比資料 (例如 p75)，或是標示分數。

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

或

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

特徵分塊

bin 是從開始到結束，或從開始到正無限的資料區間。如果沒有指定結束，則從開始到正無限。

區塊的起始和結束值會以代表該區塊的指標的值類型提供。舉例來說，首次顯示內容所需時間是以毫秒為單位，並以整數呈現，因此其指標分箱會使用 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_pattern 時，系統會知道這些變更會失敗。系統不會處理複雜的動作，例如追蹤重新導向。

{
  "originalUrl": string,
  "normalizedUrl": string
}

頻率限制

每個 Google Cloud 專案的 CrUX API 每分鐘最多可執行 150 次查詢，且不收取費用。您可以在 Google Cloud 控制台中查看這項限制和目前的使用量。這項配額相當充裕，應可滿足大多數用途的需求，而且無法透過付費來提高配額。