Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

如何使用 CrUX History API

Johannes Henkel

Jasmine Yan

Barry Pollard

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

本指南介绍了 Chrome 用户体验报告 (CrUX) 历史记录 API 端点，该端点提供了一系列网页性能数据。这些数据每周更新一次，可让您查看大约 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 历史记录 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 }
      }
    ]
  }
}

在此示例中，Largest Contentful Paint (LCP) 指标的 0 到 2500 毫秒存储分区的 densities 时间序列为 Largest Contentful Paint (LCP) 指标为 [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. 这些密度值是在相应的 collectionPeriods 条目中观察到的。例如，第五个密度值 0.9183 是第五个收集期（截至 2022 年 9 月 3 日）的密度值，而 0.9187 是截至该周后一周的密度值。

换句话说，解读 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 个时间序列条目，最多提供 40 个（当请求中指定 "collectionPeriodCount": 40 时）。由于每个收集期的结束日期都是相隔 7 天的星期六，因此如果指定 "collectionPeriodCount": 40，则涵盖 10 个月。

在任何给定响应中，直方图存储分区密度的时序长度和 p75 值的时序长度将与 collectionPeriods 字段中数组的长度完全相同：它们之间存在一对一的对应关系，具体取决于这些数组的索引。

查询网页级数据

除了来源级数据之外，CrUX 历史记录 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 密度为，percentilesTimeseries 为 null。出现这种差异的原因是，直方图密度始终是数字，而百分位数可以是数字或字符串（CLS 使用字符串，即使它们看起来像数字也是如此）。

对数据进行可视化

可视化数据的最简单方法是使用 CrUX Vis，这是一款专门用于展示 CrUX 历史记录 API 强大功能的工具。如需了解详情，请参阅 CrUX Vis 文档。

如需自行生成类似的图表，我们创建了一个示例 Colab。借助 Colab（也称为“Colaboratory”），您可以在浏览器中编写和执行 Python 代码。 CrUX 历史记录 API Colab (来源) 使用 Python 调用 API 并绘制数据图表。

借助此 Colab，您可以通过填写简短的表单来制作 p75 图表、三存储分区图表，以表格形式获取数据，并查看 CrUX API 的请求和响应对。您无需成为程序员即可使用此工具，但您可以查看 Python 代码并将其修改为令人惊叹的内容。

这只是如何使用此新 API 的一个示例。由于该 API 是基于 JSON 的 HTTP 端点，因此可以从任何技术进行查询。

总结

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

我们希望通过推出此 CrUX 历史记录 API，让网站所有者能够更好地了解其网站指标的变化情况，并将其作为问题出现时的诊断工具。如果您使用的是新 API，欢迎您在 Chrome 用户体验报告（讨论）Google 群组中提供反馈。

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