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

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。

指標

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

浮點值會四捨五入至小數點後第 4 位 (請注意，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,000 毫秒和 3,000 毫秒之間，11.92% 的指標值則超過 3,000 毫秒。

百分位數

指標也可能包含百分位數，可用於額外分析。我們會根據指標的指定百分位數，回報特定指標值。這些值是根據一整組可用資料計算而得，而非最終分 bin 資料，因此不一定會與根據最終分 bin 直方圖計算的內插百分位數相符。

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

舉例來說，您可以使用下列指令列從 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 取得網頁層級資料，請在查詢中傳遞 url 屬性，而非 origin：

{
  "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 時才會回報)
• experimental_ad_count (僅針對廣告指標中包含的網頁回報)
• experimental_ad_density (僅針對廣告指標中包含的網頁回報)
• experimental_ad_cpu (僅針對廣告指標中包含的網頁回報)
• experimental_ad_kilobytes (僅針對廣告指標中包含的網頁回報)

如未提供 formFactor 值，系統會匯總所有外觀規格的值。

如需更多查詢範例，請參閱「使用 Chrome 使用者體驗報告 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 是從開始到結束的離散資料部分，如果沒有指定結束時間，則為從開始到正無限大的資料部分。

分 bin 的起始和結束值會以所代表指標的值類型提供。舉例來說，首次顯示內容所需時間是以毫秒為單位測量，並以整數形式公開，因此指標區間會使用 int32 做為開始和結束類型。不過，Cumulative Layout Shift 是以無單位的十進位值測量，並以字串編碼的十進位值表示，因此其指標分塊會使用字串做為值類型。

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

頻率限制

CrUX API 的限制為每個 Google Cloud 雲端專案每分鐘 150 個查詢，且不收取任何費用。您可以在 Google Cloud 控制台查看這項限制和目前用量。這項配額相當充足，應可滿足絕大多數用途，且無法付費提高配額。