CrUX History API

借助 CrUX History API，您可以低延迟访问六个月以页面和源粒度的历史真实用户体验数据。

试试看！

常见用例

借助 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 密钥

获取密钥

或者在“凭据”页面中创建一个。

在您获得 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 不同，CrUX History API 不包含根据有效连接类型 (ECT) 汇总的数据。

指标

我们以统计汇总的时序形式报告指标，包括直方图、百分位数 和分数。

直方图

如果指标以直方图数组表示，则每个时间序列条目表示 指标属于某个时间间隔的网页加载（与总加载次数成比例）。 这些数据点会按照该 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 天延迟）。其中包含过去 25 周的数据（每周收集一次）。

由于每个收集期都包含之前 28 天的汇总数据，并且收集期是每周的，因此这两个收集期会重叠。它们类似于数据的移动平均值，每个后续时间段包含三周的数据，而一周的数据则不同。

示例查询

您可以使用向 https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]" 发出的 POST 请求（将查询数据作为 JSON 对象包含在 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"]}'

注意：上一个示例适用于基于 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
• navigation_types
• round_trip_time
• form_factors（仅当请求中未指定 formFactor 时才报告）

如果未提供 formFactor 值，则系统会汇总所有外形规格的值。

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

数据流水线

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

滚动平均值

Chrome 用户体验报告中的数据是汇总指标的 28 天滚动平均值。也就是说，Chrome 用户体验报告在任何给定时间中显示的数据实际上是过去 28 天的数据汇总在一起。

History API 包含多个收集周期，每个周期都涵盖这 28 天。由于每个收集期都包含之前 28 天的汇总数据，并且收集期是每周的，因此这两个收集期会重叠。它们类似于数据的移动平均值，每个后续时间段包含三周的数据，而一周的数据则不同。

每周更新

History API 会在世界协调时间 (UTC) 每周一 04:00 左右更新，包含截至上周六的数据（根据标准的 2 天延迟）。它包含过去 25 周（大约 6 个月）的数据，每周收集一次数据。

没有针对更新时间的服务等级协议；我们每天都在尽最大努力运行

注意：在每周一的 04:00 UTC 左右更新数据后，同一周的数据不会出现差异，重复调用会产生相同的结果。

架构

CrUX History API 只有一个端点，可接受 POST HTTP 请求。API 会返回一个 record，其中包含一个或多个 metrics，对应于所请求来源或网页的效果数据。

HTTP 请求

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

网址采用 gRPC 转码语法。

请求正文

CrUX History API 使用与每日 CrUX API 相同的请求正文，但不支持 effectiveConnectionType 请求字段。

例如，要请求 web.dev 首页的桌面设备 Largest Contentful Paint 值：

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

响应正文

成功的请求会返回具有以下结构的 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 是单个网页性能指标（例如首次内容渲染）的一组用户体验数据。它包含一系列 bins，其中包含真实 Chrome 使用情况的摘要直方图。

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

或

"fractionTimeseries": {
  object (Fractions)
}

字段
histogramTimeseries[]	object (Bin) 指标用户体验的时间序列直方图。时间序列直方图将至少有一个分箱，并且所有分箱的密度加起来约为 1。 该特定收集期的缺失值将被标记为 "NaN"。
percentilesTimeseries	object (Percentiles) 指标的常见实用百分位数。百分位的值类型与为直方图分箱指定的值类型相同。 相应收集周期缺失的值将标记为 null。
fractionTimeseries	object (Fractions) 此对象包含带标签分数的时间序列，每个条目加起来约 1 个。 分数会四舍五入到小数点后 4 位。 缺失的条目在所有分数中均以“NaN”表示。

分箱

bin 是数据中从开始到结束的离散部分，或者如果从开始到正无穷大没有指定结束值。

分箱的起始值和结束值以其所代表的指标值类型指定。例如，First Contentful Paint 以毫秒为单位进行测量，并以 int 的形式公开，因此其指标 bin 将使用 int32s 作为 start 和 end 类型。不过，累积布局偏移以无单位的小数形式衡量，并以字符串编码的形式公开，因此其指标分箱将使用字符串作为其值类型。

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

字段
start	(integer | string) 起始位置是数据箱的起始位置。
end	(integer | string) 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 控制台中查看此限额和您当前的用量。这种宽裕的配额应该足以满足绝大多数用例的需要，并且无法为增加的配额付费。