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 控制台中查看這項限制和目前的使用量。這項配額相當充裕，應可滿足大多數用途的需求，而且無法透過付費來提高配額。