CrUX History API

发布时间：2023 年 2 月 7 日；上次更新时间：2025 年 4 月 11 日

CrUX History API 可让您以网页和来源级别低延迟地访问 6 个月的历史真实用户体验数据。

试试看！

常见用例

借助 CrUX History API，您可以查询特定 URI 的历史用户体验指标，例如“获取 https://example.com 来源的历史用户体验趋势”。

History API 遵循与每日 CrUX API 相同的结构，但值以数组的形式给出，并且键使用复数名称标记（例如，histogramTimeseries 而非 histogram，或 p75s 而非 p75）。

CrUX API 密钥

与每日 API 一样，使用 CrUX History API 需要预配用于 Chrome UX Report API 使用的 Google Cloud API 密钥。每日 API 和历史记录 API 可以使用相同的密钥。

获取和使用 API 密钥

获取密钥

或在“凭据”页面中创建一个 OAuth 客户端 ID。

在您获得 API 密钥后，您的应用便可在所有请求网址后附加查询参数 key=yourAPIKey。

API 密钥可以安全地嵌入网址中；不需要进行任何编码。

请参阅查询示例。

数据模型

本部分详细介绍了请求和响应中的数据结构。

录制

与网页或网站相关的独立信息。记录可以包含特定于标识符和特定维度组合的数据。一条记录可以包含一个或多个指标的数据。

标识符

标识符用于指定应查找哪些记录。在 CrUX 中，这些标识符是网页和网站。

来源

如果标识符是来源，则该来源中所有网页的所有数据都会汇总在一起。例如，假设 http://www.example.com 来源包含如下站点地图所示的网页：

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 的数据，并将其汇总在一起，因为这些都是该来源下的网页。

网址

如果标识符是网址，则系统只会返回该特定网址的数据。再次查看 http://www.example.com 来源站点地图：

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

如果将标识符设置为值为 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 }
      }
    ]

这些收集周期按升序排列，表示响应其他部分中每个数据点的日期范围。

History API 每周一更新，其中包含截至前一周六的数据（根据标准的 2 天延迟时间）。它包含过去 40 周的数据（每周一个收集周期）。默认情况下，系统会返回 25 个收集周期。您可以通过将请求中的 "collectionPeriodCount" 设置为介于 1 到 40 之间的数字来更改此设置。

由于每个数据收集期都包含过去 28 天的汇总数据，并且数据收集期为每周，这意味着数据收集期会重叠。它们类似于数据的移动平均值，每个后续时间段包含三周的数据，其中一个星期的数据不同。

示例查询

查询会以 JSON 对象的形式使用 POST 请求提交到 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"
  ]
}

例如，您可以使用以下命令行从 curl 调用此方法（将 API_KEY 替换为您的键）：

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

通过在查询中传递 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 值，则系统会汇总所有外形规格的值。

如需查看更多查询示例，请参阅 Using the CrUX History API 指南。

数据流水线

CrUX 数据集会通过流水线进行处理，以便整合、汇总和过滤数据，然后才能通过 API 提供。

滚动平均值

Chrome 用户体验报告中的数据是汇总指标的 28 天滚动平均值。这意味着，Chrome 用户体验报告中在任何给定时间显示的数据实际上是过去 28 天内汇总的数据。

History API 包含多个收集周期，每个周期都涵盖这 28 天。由于每个数据收集期都包含过去 28 天的汇总数据，并且数据收集期为每周，这意味着数据收集期会重叠。它们类似于数据的移动平均值，每个后续时间段包含三周的数据，其中一个星期的数据不同。

每周更新

History API 会在每周一凌晨 4: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 是记录查找的主要标识符。只能是下列其中一项：
origin

string

url_pattern“来源”是指网站的来源网址格式。

示例："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 是一组针对单个 Web 性能指标（例如 First Contentful Paint）的用户体验数据。它包含一系列 bins，其中包含真实 Chrome 使用情况的摘要直方图。

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

或

"fractionTimeseries": {
  object (Fractions)
}
字段
histogramTimeseries[]

object (Bin)

某个指标的用户体验时间序列直方图。时间序列直方图至少包含一个 bin，并且所有 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)

开始是数据分桶的开头。
end

(integer | string)

“End”是数据分桶的结束位置。如果未填充 end，则该分桶没有结束时间，并且从 start 到 +inf 都有效。
densities

array[number]

在给定指标中获得此分桶值的用户所占的百分比的时间序列。

密度会四舍五入到小数点后 4 位。

百分位数

Percentiles 包含指标在给定统计百分位数时的合成值。这些指标用于估算某个指标在用户总数中的所占百分比的用户所体验到的价值。

{
  "P75": value
}
字段
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% 的网页加载在给定指标达到或低于此值时所对应的值的时间序列。

UrlNormalization

表示为规范网址而执行的规范化操作的对象，以提高成功查找的几率。这些是自动进行的基本更改，在查找已知会失败的提供的 url_pattern 时会执行这些更改。系统不会处理跟踪重定向等复杂操作。

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

string

在执行任何标准化操作之前请求的原始网址。
normalizedUrl

string

执行所有规范化操作后的网址。这是可合理查询的有效用户体验网址。

速率限制

CrUX History API 与 CrUX API 共享相同的限制，即每个 Google Cloud 项目每分钟 150 次查询，这两种 API 均免费提供。您可以在 Google Cloud 控制台中查看此限制和当前用量。这项配额非常充足，对于绝大多数用例来说应该足够了，而且您无法通过付费来增加配额。