如何使用 CrUX History API

Johannes Henkel

Jasmine Yan

Barry Pollard

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

本指南将介绍 Chrome 用户体验报告 (CrUX) 历史记录 API 端点，该端点可提供时间序列的 Web 性能数据。此数据每周更新一次，可让您查看大约 6 个月的历史数据，其中包含 40 个数据点，每个数据点之间相隔一周。

与原始 CrUX API 端点提供的每日更新数据搭配使用时，您现在可以快速查看最新数据和之前的数据，从而能够轻松了解网页随时间的变化情况。

在此页面上试用 API

试试看！

查询每日 CrUX API

回顾一下之前一篇关于 CrUX API 的文章，您可以通过以下方式获取特定来源的实地数据快照：

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" --header 'Content-Type: application/json' --data '{"origin": "https://web.dev"}'

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [{
          "start": 0, "end": 2500, "density": 0.9192
        }, {
          "start": 2500, "end": 4000, "density": 0.0513
        }, {
          "start": 4000, "density": 0.0294
        }],
        "percentiles": {
          "p75": 1303
        }
      }
      // ...
    },
    "collectionPeriod": {
      "firstDate": { "year": 2022, "month": 12, "day": 27 },
      "lastDate": { "year": 2023, "month": 1, "day": 23 }
    }
  }
}

此快照包含特定 28 天收集期（在本例中为 2022 年 12 月 27 日至 2023 年 1 月 23 日）的直方图密度值和百分位数值。

查询 CrUX History API

如需调用历史记录端点，请将 curl 命令中的网址中的 queryRecord 更改为 queryHistoryRecord。使用与上次调用相同的 CrUX API 密钥即可。collectionPeriodCount 用于指定要返回的时序条目数；最大值为 40。如果未指定，则默认为 25。

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
 --header 'Content-Type: application/json' \
 --data '{"origin": "https://web.dev", "collectionPeriodCount": 40}'

响应的总体形状类似，但数据量要大得多！现在，包含第 75 百分位数 (p75) 和直方图密度值的字段不再是单个数据点，而是时序。

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

在此示例中，最大内容渲染时间 (LCP) 指标的 0 到 2500 毫秒区间的 densities 时间序列为 [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].。每个密度都是在相应的 collectionPeriods 条目期间观测到的。例如，第五个密度 0.9183 是第五个收集周期（截至 2022 年 9 月 3 日）的密度，而 0.9187 是截至该周之后一周的密度。

换句话说，如果解读 https://web.dev 示例中的最后几个时间序列条目，会发现从 2022 年 8 月 14 日到 2022 年 9 月 10 日，91.87% 的网页加载的 LCP 值小于 2500 毫秒，5.27% 的网页加载的 LCP 值介于 2500 毫秒到 4000 毫秒之间，2.85% 的网页加载的 LCP 值大于 4000 毫秒。

同样，还有一个针对 p75 值的时间序列：2022 年 8 月 14 日至 2022 年 9 月 10 日的 LCP p75 值为 1377。这意味着，在此收集期内，75% 的用户体验的 LCP 低于 1377 毫秒，而 25% 的用户体验的 LCP 高于 1377 毫秒。

虽然示例仅列出了 6 个时间序列条目和收集周期，但 API 的响应默认提供 25 个时间序列条目，如果请求中指定了 "collectionPeriodCount": 40，则最多提供 40 个。由于每个收集周期的结束日期都是相隔 7 天的周六，因此 "collectionPeriodCount": 40 涵盖了 10 个月。

在任何给定的响应中，直方图箱密度和 p75 值的时间序列的长度将与 collectionPeriods 字段中数组的长度完全相同：这些数组之间存在基于索引的一对一对应关系。

查询网页级数据

除了来源级数据之外，CrUX History API 还允许访问历史网页级数据。虽然之前可以使用 BigQuery 上的 CrUX 数据集获取源级数据，但只有当网站自行收集并存储网页级历史数据时，才能获取这些数据。现在，通过新的 API，您可以获取这些历史网页级数据。

您可以采用相同的方式查询网页级数据，但需在载荷中使用 url 而不是 origin：

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
 --header 'Content-Type: application/json' \
 --data '{"url": "https://web.dev/blog/"}'

网页级（和来源级）历史数据与 CrUX 的其余部分一样，需要满足相同的资格要求，因此特定网页可能没有完整的历史记录。在这些情况下，“缺失”的数据将以 "NaN" 表示 histogramTimeseries 密度，以 null 表示 percentilesTimeseries。出现这种差异的原因是，直方图密度始终是数字，而百分位数可以是数字或字符串（CLS 使用字符串，即使它们看起来像数字）。

直观呈现数据

直观呈现数据的最简单方法是使用 CrUX Vis，这是一款专门用于展示 CrUX History API 强大功能的工具。如需了解详情，请参阅 CrUX Vis 文档。

如需自行生成类似的图表，请参阅我们创建的 Colab 示例。借助 Colab（全称“Colaboratory”），您可在浏览器中编写和执行 Python 代码。CrUX History API Colab（来源）使用 Python 调用 API 并绘制数据图表。

通过填写简短的表单，您可以使用此 Colab 制作 p75 图表、三箱图表，以表格形式获取数据，并查看 CrUX API 的请求和响应对。您无需是程序员即可使用此功能，但您当然可以查看 Python 代码并将其修改为令人惊叹的内容！欢迎体验，并随时提供反馈！

当然，您不一定非要使用 Colab 或 Python，这只是使用此新 API 的一个示例。作为基于 JSON 的 HTTP 端点，该 API 可通过任何技术进行查询。

总结

在推出 CrUX History API 端点之前，网站所有者可以从 CrUX 获取的历史信息有限。虽然可以使用 BigQuery 获取每月来源级数据，但无法获取每周数据，也无法获取网页级历史数据。网站所有者可以使用每日 API 自行记录这些数据，但通常只有在指标出现回归后才会发现需要这样做。

我们希望通过推出此 CrUX History API，让网站所有者更好地了解不断变化的网站指标，并将其作为出现问题时的诊断工具。如果您使用的是新版 API，欢迎您在 Chrome UX Report（讨论）Google 群组中提供反馈。

致谢

主打图片提供者：Unsplash 上的 Dave Herring

如何使用 CrUX History API 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。