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

也就是說，當您查詢來源設為 http://www.example.com 的 Chrome 使用者體驗報告時，系統會將 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。

有效連線類型

有效連線類型是指使用者瀏覽至網頁時，裝置的預估連線品質。這是一個一般類別，可分為 offline、slow-2G、2G、3G 和 4G。

指標

我們的指標在直方圖、百分位數和分數呈現為統計匯總。

浮點值會四捨五入至小數點後 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,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% 的總和。

指標值類型

CrUX API 指標名稱 資料類型 公制單位 統計匯總 說明文件
cumulative_layout_shift 以字串形式編碼的小數點後 2 位 無單位 有三個特徵分塊的直方圖，第 75 個百分位數 cls
first_contentful_paint int 毫秒 有三個特徵分塊的直方圖，第 75 個百分位數 fcp
interaction_to_next_paint int 毫秒 有三個特徵分塊的直方圖，第 75 個百分位數 inp
largest_contentful_paint int 毫秒 有三個特徵分塊的直方圖，第 75 個百分位數 lcp
experimental_time_to_first_byte int 毫秒 有三個特徵分塊的直方圖，第 75 個百分位數 ttfb
form_factors 小數點後四位數 百分比 將板型規格對應至分數 板型規格
navigation_types 小數點後四位數 百分比 將瀏覽類型對應至分數 導覽類型
round_trip_time int 毫秒 第 75 個百分位數 rtt

BigQuery 指標名稱對應

CrUX API 指標名稱 BigQuery 指標名稱
cumulative_layout_shift layout_instability.cumulative_layout_shift
first_contentful_paint first_contentful_paint
interaction_to_next_paint interaction_to_next_paint
largest_contentful_paint largest_contentful_paint
experimental_time_to_first_byte experimental.time_to_first_byte
navigation_types navigation_types
form_factors 不適用
round_trip_time 不適用

收集期間

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

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

如此一來，即可更清楚瞭解資料、資料是否已針對當天更新，或傳回的資料與昨天相同。

請注意，CrUX API 會等待當天完成的資料，因此大約需要兩天的時間。在此之前，該 API 需要經過一段時間才能提供在 API 中。使用的時區為太平洋標準時間 (PST)，不隨日光節約時間變動。

查詢範例

查詢會以 JSON 物件的形式提交，方法是對 https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" 提出 POST 要求，並在 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"]}'

如要使用網頁層級資料，請在查詢中傳遞 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
  • navigation_types
  • 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 轉碼語法。

要求主體

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

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

板型規格是一種查詢維度，用於指定記錄資料所屬的裝置類別。

這個欄位會使用 DESKTOP、PHONE 或 TABLET 的值。

注意：如未指定板型規格，系統會傳回含有所有板型規格匯總資料的特殊記錄。
metrics[]

string

必須包含在回應中的指標。如未指定，系統會傳回任何找到的指標。

允許的值：["cumulative_layout_shift", "first_contentful_paint", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
聯集欄位 url_pattern。url_pattern 是記錄查詢的主要 ID。只能採用下列其中一種設定：
origin

string

url_pattern「origin」可能是指網站來源的網址模式。

範例："https://example.com"、"https://cloud.google.com"
url

string

url_pattern url 是指任何網址模式。

例如："https://example.com/、https://cloud.google.com/why-google-cloud/"

舉例來說，如果想要求電腦版 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 定義所有可識別此記錄為獨特的維度。

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

有效的連線類型是指所有使用者在這個記錄中遇到的一般連線類別。這個欄位使用的值 [「offline」、「slow-2G」、「2G」、「3G」、「4G」]，如 https://wicg.github.io/netinfo/#effective-connection-types

如果未指定有效連線類型，系統會傳回所有有效連線類型的匯總資料。
聯集欄位 url_pattern。網址模式是指記錄要套用的網址。url_pattern 只能是下列其中一項：
origin

string

origin 指定這筆記錄的來源。

注意：指定 origin 時，所有網頁上此來源下的載入資料，都會匯總為來源層級的使用者體驗資料。
url

string

url 指定這筆記錄適用的特定網址。

注意：指定 url 時，系統只會匯總該特定網址的資料。

指標

metric 是針對單一網站成效指標 (例如首次顯示內容所需時間) 的一組匯總使用者體驗資料。 也可能包含一系列 bins 特定百分位數資料的直方圖，說明 Chrome 的實際使用情形 (例如 p75) 或包含加上標籤的分數。

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

或

{
  "fractions": {
    object (Fractions)
  }
}
欄位
histogram[]

object (Bin)

指標的使用者體驗直方圖。直方圖至少會有一個特徵分塊，所有特徵分塊的密度總和等於約 1。
percentiles

object (Percentiles)

指標的常見實用百分位數。百分位數的值類型會與直方圖區塊的值類型相同。
fractions

object (Fractions)

這個物件含有加上標籤的分數，總和為 1 左右。

分數會四捨五入至小數點後 4 位。

特徵分塊

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

特徵分塊的起始值和結束值皆以其代表的指標類型為準。舉例來說，首次顯示內容繪製的測量結果是以毫秒為單位，並以 int 的形式公開，因此指標特徵分塊會針對開始和結束型別使用 int32s。不過，累積版面配置位移的測量單位為無單位小數，以小數形式公開為字串，因此指標特徵分塊會使用字串做為值類型的值。

{
  "start": value,
  "end": value,
  "density": number
}
欄位
start

(integer | string)

Start 是資料區塊的起始位置。
end

(integer | string)

End 為資料特徵分塊的結尾。如果未填入結尾，特徵分塊沒有結尾，且從頭到 +inf 有效。
density

number

在特定指標中，經歷這個特徵分塊值的使用者比例。

密度會四捨五入至小數點後 4 位。

百分位數

Percentiles 包含特定統計百分位數的指標綜合值。這些指標用於估算指標值，並根據使用者總人數的百分比，評估使用者體驗。

{
  "P75": value
}
欄位
p75

(integer | string)

75% 的網頁載入作業在指定指標達到或低於這個值。

分數

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
}
欄位
originalUrl

string

尚未進行任何正規化動作之前的原始要求網址。
normalizedUrl

string

任何正規化動作後的網址。這是可供查理的有效使用者體驗網址。

頻率限制

每個 Google Cloud 專案的 CrUX API 每分鐘只能執行 150 次查詢，且不收取費用。如要查看這項限制和目前的用量，請前往 Google Cloud 控制台。這麼多的配額應該足以應付大多數的用途，而且您無法為提高配額付費。