本頁面由 Cloud Translation API 翻譯而成。

CrUX History API
bookmark_border 透過集合功能整理內容你可以依據偏好儲存及分類內容。

發布日期：2023 年 2 月 7 日，上次更新日期：2025 年 4 月 11 日

CrUX History API 可讓您以低延遲的方式存取六個月的歷來實際使用者體驗資料，並以網頁和來源為單位進行細分。

試試看！

常見用途

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

History API 的結構與每日 CrUX API 相同，但值會以陣列形式提供，且索引鍵會標示為複數名稱 (例如 histogramTimeseries 而非 histogram，或 p75s 而非 p75)。

CrUX API 金鑰

與 daily API 一樣，使用 CrUX History API 需要為 Chrome UX Report API 使用情形預先提供 Google Cloud API 金鑰。同一個金鑰可用於每日和歷來 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，表示記錄包含行動裝置上載入作業的相關資訊。

板型規格

CrUX History API 只能依板型規格維度匯總。這是裝置的一般類別，可分為 PHONE、TABLET 和 DESKTOP。

指標

我們會以統計匯總的時間序列回報指標，包括直方圖、百分位數和分數。

直方圖

當指標以直方圖陣列表示時，每個時序記錄都代表指標落在某個間隔的網頁載入百分比，與所有記錄的比率相同。資料點會按照 API 傳回的收集期間日期順序顯示，第一個點是最早的期間，最後一個點則是最新的收集期間。

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

{
  "histogramTimeseries": [
    {
      "start": 0,
      "end": 2500,
      "densities": [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]
    },
    {
      "start": 2500,
      "end": 4000,
      "densities": [0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527]
    },
    {
      "start": 4000,
      "densities": [0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285]
    }
  ],
}

這項資料指出，在歷史記錄中的第一個收集期間，91.90% 的網頁載入體驗到達範例指標值介於 0 毫秒和 2,500 毫秒之間，其次為 92.03%、91.94%... 這個直方圖中並未包含指標的單位，在本例中，我們假設單位為毫秒。

此外，5.21% 的網頁載入作業在歷史資料中的第一次收集期間，其範例指標值介於 2,500 毫秒和 4,000 毫秒之間，而 2.88% 的網頁載入作業在歷史資料中的第一次收集期間，其值則大於 4,000 毫秒。

百分位數

指標也可能包含百分位數時序，可用於進一步分析。

資料點會按照 API 傳回的收集期間日期順序顯示，第一個點是最早的期間，最後一個點則是最新的收集期間。

{
  "percentilesTimeseries": {
    "p75s": [1362, 1352, 1344, 1356, 1366, 1377]
  },
}

這些百分位數可顯示該指標在特定百分位數的特定值。這些百分比是根據完整的資料集計算，而非最終分箱資料，因此不一定會與根據最終分箱直方圖計算的內插百分比相符。

分數

指標可以以標記片段的時間序列表示；每個標記都會以特定方式描述網頁載入情形。資料點會按照 API 傳回的收集期間日期順序顯示，第一個點是最早的期間，最後一個點則是最新的收集期間。

範例：

{    
  "fractionTimeseries": {
    "desktop": {"fractions": [0.3195, 0.2115, 0.1421]},
    "phone": {"fractions": [0.6295, 0.7544, 0.8288]},
    "tablet": {"fractions": [0.051, 0.0341, 0.029]}
  }
}

在這個範例中，最新的資料點指出 14.21% 的網頁載入來自電腦，82.88% 來自手機。

指標值類型

由於 CrUX History API 使用相同的指標值類型，您可以參考每日 CrUX API 指標值類型的說明文件，進一步瞭解相關資訊。

指標資格條件

根據資格條件，某些來源或網址可能只符合 CrUX History API 涵蓋的部分收集期間資格。在這種情況下，CrUX History API 會針對收集期間沒有符合資格的資料，針對 histogramTimeseries 密度傳回 "NaN"，針對 percentilesTimeseries 傳回 null。之所以有差異，是因為直方圖密度一律是數字，而百分位數可以是數字或字串 (CLS 使用的是字串，即使看起來像數字也一樣)。

舉例來說，如果第二個期間沒有任何符合資格的資料，系統會顯示以下內容：

{
  "histogramTimeseries": [
    {
      "start": 0,
      "end": 2500,
      "densities": [0.9190, "NaN", 0.9194, 0.9195, 0.9183, 0.9187]
    },
    {
      "start": 2500,
      "end": 4000,
      "densities": [0.0521, "NaN", 0.0518, 0.0518, 0.0526, 0.0527]
    },
    {
      "start": 4000,
      "densities": [0.0288, "NaN", 0.0286, 0.0285, 0.0290, 0.0285]
    }
  ],
  "percentilesTimeseries": {
    "p75s": [1362, null, 1344, 1356, 1366, 1377]
  },
}

如果網址或來源在一段時間內符合資格，然後又不符合資格，您可能會發現許多項目缺少。

收集期間

CrUX History API 包含 collectionPeriods 物件，其中包含 firstDate 和 endDate 欄位的陣列，代表每個匯總時間區間的開始和結束日期。例如：

    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }
    ]

這些收集期間會以遞增順序顯示，代表回應中其他部分中每個資料點的日期範圍。

歷史資料 API 會在每週一更新，並包含上週六之前的資料 (根據標準的 2 天延遲時間)。其中包含過去 40 週的資料，每週收集一次。系統預設會傳回 25 個收集期間。如要變更這項設定，請將要求中的 "collectionPeriodCount" 設為介於 1 到 40 的數字。

由於每個收集期間都包含前 28 天的匯總資料，且收集期間為每週，因此收集期間會重疊。這類資料類似於資料的移動平均值，每個後續期間會包含三週的資料，而每週的資料都不同。

查詢範例

使用 POST 要求將查詢以 JSON 物件的形式提交至 https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]"，其中查詢資料為 POST 主體中的 JSON 物件。

請注意，使用 queryHistoryRecord 取代每日 CrUX API 的 queryRecord。

內容範例如下：

{
  "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:queryHistoryRecord?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"]}'

注意：上述範例適用於 macOS 或 Linux 系統，包括適用於 Windows 的 Git BASH shell。其他系統可能需要稍微修改。舉例來說，cmd.exe 指令列不允許參數使用單引號，也不允許使用換行符號 (\)，因此必須使用雙引號 (並視需要使用 \" 逸出內部引號)，以及使用單行。

您可以透過在查詢中傳遞 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 值，系統會在所有板型規格中匯總這些值。

如需更多查詢範例，請參閱「使用 CrUX History API」指南。

資料管道

CrUX 資料集會透過管道處理，以便在透過 API 提供資料前，先整合、匯總及篩選資料。

累計平均

Chrome 使用者體驗報告中的資料是匯總指標的 28 天滾動平均值。也就是說，Chrome 使用者體驗報告在任何時間點顯示的資料，其實是匯總過去 28 天的資料。

History API 包含多個收集期間，每個期間都涵蓋這 28 天。由於每個收集期間都包含前 28 天的匯總資料，且收集期間為每週，因此收集期間會重疊。這類資料類似於資料的移動平均值，每個後續期間會包含三週的資料，而每週的資料都不同。

每週更新

History API 會在每週一約世界標準時間 04:00 更新，並包含上一個星期六之前的資料 (根據標準的 2 天延遲時間)。其中包含過去 40 週 (約 10 個月) 的資料，每週收集一次。請注意，根據預設，每個時序會傳回 25 個項目，但您可以指定 collectionPeriodCount 要求參數來覆寫這個值。

更新時間沒有服務水準協議，系統會每天盡力執行。

結構定義

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

HTTP 要求

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

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

要求主體

CrUX History API 使用與每日 CrUX API 相似的要求主體，但會額外提供一個選用的 "collectionPeriodCount" 欄位：

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

  "collectionPeriodCount": int32 // Optional: Number of periods to collect
}

欄位
`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", "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"]`
聯集欄位 `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/"`
聯集欄位 `url_pattern` 結束。
`collectionPeriodCount`	`int32` (選填) 要傳回的收集週期數，介於 1 和 40 之間。預設值為 25。請注意，如未指定 `collectionPeriodCount`，系統會傳回預設值 25。

舉例來說，如要為 web.dev 首頁要求電腦版 Largest Contentful Paint 值，請按照下列步驟操作：

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

這項類似要求包含選用的 collectionPeriodCount 欄位，會產生 40 個時序記錄，提供 https://web.dev 來源大約 10 個月的網站效能記錄：

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ],
  "collectionPeriodCount": 40
}

回應主體

成功的要求會傳回回應，其中包含 record 物件和 urlNormalizationDetails，結構如下：

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

舉例來說，針對先前要求中的要求主體，回應可能會是：

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogramTimeseries": [{
            "start": 0, "end": 2500, "densities": [
              0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187, ...
            ]
          }, {
            "start": 2500, "end": 4000, "densities": [
              0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527, ...
            ]
          },  {
            "start": 4000, "densities": [
              0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285, ...
            ]
          }
        ],
        "percentilesTimeseries": {
          "p75s": [
            1362, 1352, 1344, 1356, 1366, 1377, ...
          ]
        }
      }
    },
    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }, {
        ...
      }
    ]
  }
}

鍵

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.
}

欄位
`formFactor`	`enum (FormFactor)` 外型規格是指所有使用者用來存取此記錄的裝置類別。如果未指定板型規格，系統會傳回所有板型規格的匯總資料。
聯集欄位 `url_pattern`。網址模式是記錄適用的網址。`url_pattern` 只能是下列其中一項：
`origin`	`string` Origin 會指定此記錄的來源。注意：指定來源後，所有網頁中此來源下載的資料都會匯總為來源層級使用者體驗資料。
`url`	`string` `url` 可指定此記錄適用的特定網址。注意：指定 `url` 時，系統只會匯總該特定網址的資料。

指標

metric 是一組使用者體驗資料，適用於單一網站效能指標 (例如 First Contentful Paint)。這份報告包含 Chrome 實際使用情形的摘要直方圖，以一系列 bins 呈現。

{
  "histogramTimeseries": [
    {
      object (Bin)
    }
  ],
  "percentilesTimeseries": {
    object (Percentiles)
  }
}

或

"fractionTimeseries": {
  object (Fractions)
}

欄位

欄位
`histogramTimeseries[]`	`object (Bin)` 指標使用者體驗的時間序列直方圖。時序直方圖至少會有一個值區，且所有值區的密度加總約為 1。該收集期間的缺少值會標示為 `"NaN"`。
`percentilesTimeseries`	`object (Percentiles)` 指標的常用百分位數。百分位數的值類型會與直方圖區塊的值類型相同。該收集期間的缺少值會標示為 `null`。
`fractionTimeseries`	`object (Fractions)` 這個物件包含標記分數的時間序列，每個項目加總約為 1。小數會四捨五入到小數點後 4 位。缺少的項目會在所有分數中以 `"NaN"` 表示。

histogramTimeseries[]

object (Bin)

指標使用者體驗的時間序列直方圖。時序直方圖至少會有一個值區，且所有值區的密度加總約為 1。

該收集期間的缺少值會標示為 "NaN"。

percentilesTimeseries

object (Percentiles)

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

該收集期間的缺少值會標示為 null。

fractionTimeseries

object (Fractions)

這個物件包含標記分數的時間序列，每個項目加總約為 1。

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

缺少的項目會在所有分數中以 `"NaN"` 表示。

特徵分塊

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

區塊的起始和結束值會以代表該區塊的指標的值類型提供。舉例來說，首次顯示內容所需時間是以毫秒為單位，並以整數呈現，因此其指標分箱會使用 int32 做為開始和結束類型。不過，累積版面配置偏移是以無單位的十進位數來計算，並以字串編碼的十進位數公開，因此其指標分箱會使用字串做為值類型。

{
  "start": value,
  "end": value,
  "densities": [number, number, number...etc.]
}

欄位

欄位
`start`	`(integer \| string)` Start 是資料區塊的起始位置。
`end`	`(integer \| string)` 結束是資料區塊的結尾。如果未填入 end，則該區塊沒有結束，且有效範圍為從 start 到 +inf。
`densities`	`array[number]` 時間序列，顯示在指定指標中，使用者遇到此區間值的比例。密度會四捨五入至小數點後 4 位。

start

(integer | string)

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

end

(integer | string)

結束是資料區塊的結尾。如果未填入 end，則該區塊沒有結束，且有效範圍為從 start 到 +inf。

densities

array[number]

時間序列，顯示在指定指標中，使用者遇到此區間值的比例。

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

百分位數

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

{
  "P75": value
}

欄位

欄位
`p75s`	`array[(integer \| string)]` 75% 的網頁載入體驗到特定指標低於或等於這個值的時間序列。

p75s

array[(integer | string)]

75% 的網頁載入體驗到特定指標低於或等於這個值的時間序列。

分數

Fractions 包含標記的時間序列，每個項目的標記加總約為 1。每個標籤都會以某種方式描述網頁載入情形，因此以這種方式呈現的指標可視為產生不重複值，而非數值，而分數則表示特定不重複值的測量頻率。

{
  "label_1": { "fractions": array[fraction]},
  "label_1": { "fractions": array[fraction]},
  ...
  "label_n": { "fractions": array[fraction]}
}

就像直方圖值區中的密度值一樣，每個 fraction 都是數字 0.0 <= value <= 1.0，加總起來約為 1.0。如果特定收集期間的指標無法使用，則所有分數陣列中的對應項目會為「NaN」。

欄位

欄位
`p75s`	`array[(integer \| string)]` 75% 的網頁載入體驗到特定指標低於或等於這個值的時間序列。

p75s

array[(integer | string)]

75% 的網頁載入體驗到特定指標低於或等於這個值的時間序列。

UrlNormalization

代表用於將網址標準化的標準化動作的物件，可提高查詢成功的機率。這些是基本自動變更，在查詢提供的 url_pattern 時，系統會知道這些變更會失敗。系統不會處理複雜的動作，例如追蹤重新導向。

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

欄位

欄位
`originalUrl`	`string` 在任何正規化動作之前，原始要求的網址。
`normalizedUrl`	`string` 經過任何正規化動作後的網址。這是有效的使用者體驗網址，可合理查詢。

originalUrl

string

在任何正規化動作之前，原始要求的網址。

normalizedUrl

string

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

頻率限制

CrUX History API 與 CrUX API 共用相同的限制，即每個 Google Cloud 專案每分鐘 150 個查詢，兩者均免費提供。您可以在 Google Cloud 控制台中查看這項限制和目前的使用量。這項配額相當充裕，應可滿足大多數用途的需求，而且無法透過付費來提高配額。

CrUX History API bookmark_borderbookmark 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

常見用途

CrUX API 金鑰

取得並使用 API 金鑰

資料模型

錄影

ID

來源

網址

尺寸

板型規格

指標

直方圖

百分位數

分數

指標值類型

指標資格條件

收集期間

查詢範例

資料管道

累計平均

每週更新

結構定義

HTTP 要求

要求主體

回應主體

鍵

指標

特徵分塊

百分位數

分數

UrlNormalization

頻率限制

CrUX History API
bookmark_border 透過集合功能整理內容你可以依據偏好儲存及分類內容。