CrUX API

CrUX API 可让您以低延迟访问页面和来源粒度的汇总真实用户体验数据。

试试看！

常见用例

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

CrUX API 密钥

使用 CrUX API 需要为 Chrome UX Report API 使用预配 Google Cloud 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

这意味着，在查询 Chrome 用户体验报告时，如果将源设置为 http://www.example.com，系统会返回 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 的设备类型表示记录包含有关在移动设备上发生的加载的信息。每个维度都有一定数量的值，如果未指定某个维度，则意味着该维度会汇总所有值。例如，如果未指定设备规格，则表示记录包含有关在任何设备规格上发生的加载的信息。

设备规格

最终用户用于导航到网页的设备类别。这是一类通用设备，分为PHONE、TABLET和DESKTOP。

指标

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

浮点值会四舍五入到小数点后 4 位（请注意，cumulative_layout_shift 指标是编码为字符串的双精度值，因此不被视为浮点值，在字符串中会报告到小数点后 2 位）。

直方图

当指标以直方图表示时，我们会显示该指标在特定范围内的网页加载百分比。

示例指标的三分箱直方图如下所示：

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

此数据表明，对于 38.18% 的网页加载，示例指标的测量值介于 0 毫秒和 1,000 毫秒之间。此直方图中不包含指标的单位，在这种情况下，我们将假定为毫秒。

此外，49.91% 的网页加载的指标值介于 1,000 毫秒和 3,000 毫秒之间，11.92% 的网页加载的指标值大于 3,000 毫秒。

百分位

指标还可能包含百分位数，这对于进一步分析非常有用。 我们会报告该指标在给定百分位处的具体指标值。它们基于完整的可用数据集，而不是最终的分箱数据，因此不一定与基于最终分箱直方图的插值百分位数匹配。

{
  "percentiles": {
    "p75": 2063
  }
}

在此示例中，至少 75% 的网页加载测得的指标值为 <= 2063。

注意：每个百分位的值都是通过综合计算得出的，这并不意味着任何用户都实际体验过所示的值，而只是表示有一定百分比的网页加载体验到的指标值低于给定的值。

分数

分数表示可以采用特定方式标记的网页加载百分比。 在这种情况下，指标值就是这些标签。

例如，form_factors 指标由一个 fractions 对象组成，该对象列出了给定查询所涵盖的外形规格（或设备）的细分：

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

在本例中，3.77% 的网页加载是在桌面设备上测量的，2.88% 是在平板电脑上测量的，93.35% 是在手机上测量的，总计 100%。

指标值类型

CrUX API 指标名称	数据类型	公制单位	统计汇总	文档
cumulative_layout_shift	编码为字符串的双精度浮点数（保留 2 位小数）	无单位	包含三个分箱的直方图，百分位数为 p75	CLS
interaction_to_next_paint	int	毫秒	包含三个分箱的直方图，百分位数为 p75	INP
largest_contentful_paint	int	毫秒	包含三个分箱的直方图，百分位数为 p75	LCP
experimental_cumulative_layout_shift_with_softnavs	编码为字符串的双精度浮点数（保留 2 位小数）	无单位	包含三个分箱的直方图，百分位数为 p75	博客
experimental_interaction_to_next_paint_with_softnavs	int	毫秒	包含三个分箱的直方图，百分位数为 p75	博客
experimental_largest_contentful_paint_with_softnavs	int	毫秒	包含三个分箱的直方图，百分位数为 p75	博客
first_contentful_paint	int	毫秒	包含三个分箱的直方图，百分位数为 p75	FCP
experimental_first_contentful_paint_with_softnavs	int	毫秒	包含三个分箱的直方图，百分位数为 p75	博客
experimental_time_to_first_byte	int	毫秒	包含三个分箱的直方图，百分位数为 p75	TTFB
form_factors	4 位小数的双精度浮点数	百分比	从设备规格到分数的映射	设备类型
navigation_types	4 位小数的双精度浮点数	百分比	从导航类型到分数的映射	导航类型
experimental_navigation_types_with_softnavs	4 位小数的双精度浮点数	百分比	从导航类型到分数的映射	博客
round_trip_time	int	毫秒	包含三个分箱的直方图，百分位数为 p75	RTT 指标
largest_contentful_paint_resource_type	4 位小数的双精度浮点数	百分比	从导航类型到分数的映射	LCP 资源类型
largest_contentful_paint_image_time_to_first_byte	int	毫秒	百分位数（含 p75）	LCP 子部分
largest_contentful_paint_image_resource_load_delay	int	毫秒	百分位数（含 p75）	LCP 子部分
largest_contentful_paint_image_resource_load_duration	int	毫秒	百分位数（含 p75）	LCP 子部分
largest_contentful_paint_image_element_render_delay	int	毫秒	百分位数（含 p75）	LCP 子部分
experimental_ad_count	保留 2 位小数的双精度浮点数	无单位	仅限 p75	广告数量
experimental_ad_density	保留 2 位小数的双精度浮点数	无单位	仅限 p75	广告密度
experimental_ad_cpu	int	毫秒	仅限 p75	广告权重：CPU
experimental_ad_kilobytes	int	KB	仅限 p75	广告权重：广告网络

BigQuery 指标名称映射

CrUX API 指标名称	BigQuery 指标名称
cumulative_layout_shift	layout_instability.cumulative_layout_shift
first_contentful_paint	first_contentful_paint
interaction_to_next_paint	interaction_to_next_paint
largest_contentful_paint	largest_contentful_paint
experimental_time_to_first_byte	experimental.time_to_first_byte
experimental_cumulative_layout_shift_with_softnavs	experimental.cumulative_layout_shift_with_softnavs
experimental_first_contentful_paint_with_softnavs	n/a
experimental_interaction_to_next_paint_with_softnavs	experimental.interaction_to_next_paint_with_softnavs
experimental_largest_contentful_paint_with_softnavs	experimental.largest_contentful_paint_with_softnavs
navigation_types	navigation_types
experimental_navigation_types_with_softnavs	n/a
form_factors	无
round_trip_time	round_trip_time
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	无
experimental_ad_count	n/a
experimental_ad_density	n/a
experimental_ad_cpu	n/a
experimental_ad_kilobytes	n/a

注意：在 CrUX BigQuery 中，每个来源在不同设备类型上的直方图密度总和为 100%，因此我们在 API 中支持的 form_factors 指标改为表示为 first_contentful_paint 的直方图密度。

收集时段

自 2022 年 10 月起，CrUX API 包含一个 collectionPeriod 对象，其中 firstDate 和 endDate 字段表示汇总窗口的开始日期和结束日期。例如：

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

这样，您就可以更好地了解数据，以及数据是否已在当天更新，或者是否返回与昨天相同的数据。

注意：CrUX API 的数据大约比当天日期晚两天，因为它需要等待当天的完整数据，并且在 API 中提供这些数据之前需要一些处理时间。所用时区为太平洋标准时间 (PST)，不会因夏令时而发生变化。

PageSpeed Insights 中也提供了收集期：

PageSpeed Insights 中的收集期日期。

此外，collectionPeriod 将始终显示 28 天，即使数据未涵盖完整的 28 天（例如，如果网页发布时间不到 28 天）。collectionPeriod 是 CrUX 数据的汇总时间段，不一定是数据所代表的时间段。

示例查询

查询通过 POST 请求以 JSON 对象的形式提交到 https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]"，查询数据作为 JSON 对象包含在 POST 正文中：

{
  "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:queryRecord?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_cumulative_layout_shift_with_softnavs
• experimental_first_contentful_paint_with_softnavs
• experimental_interaction_to_next_paint_with_softnavs
• experimental_largest_contentful_paint_with_softnavs
• experimental_navigation_types_with_softnavs
• 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 时报告）
• experimental_ad_count（仅针对广告指标中包含的网页进行报告）
• experimental_ad_density（仅针对广告指标中包含的网页进行报告）
• experimental_ad_cpu（仅针对广告指标中包含的网页进行报告）
• experimental_ad_kilobytes（仅针对广告指标中包含的网页进行报告）

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

如需查看更多查询示例，请参阅使用 Chrome 用户体验报告 API。

数据流水线

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

滚动平均值

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

这与 BigQuery 上的 CrUX 数据集汇总月度报告的方式类似。

每日更新

数据每天在世界协调时间 (UTC) 04:00 左右更新。更新时间没有服务等级协议；系统会每天尽力运行。

注意：数据在世界协调时间 (UTC) 凌晨 4 点左右更新后，当天内不会发生变化，重复调用会产生相同的结果。

架构

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

HTTP 请求

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

网址采用 gRPC 转码语法。

请求正文

请求正文应包含结构如下的数据：

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

字段
formFactor	enum (FormFactor) 设备规格是一个查询维度，用于指定记录的数据应属于哪种设备类别。 此字段使用值 DESKTOP、PHONE 或 TABLET。 注意：如果未指定设备规格，系统将返回一条包含所有设备规格汇总数据的特殊记录。
metrics[]	string 应包含在响应中的指标。如果未指定任何指标，则系统会返回找到的所有指标。 允许的值：["cumulative_layout_shift", "first_contentful_paint", "interaction_to_next_paint", "largest_contentful_paint", "experimental_cumulative_layout_shift_with_softnavs", "experimental_first_contentful_paint_with_softnavs", "experimental_interaction_to_next_paint_with_softnavs", "experimental_largest_contentful_paint_with_softnavs", "experimental_time_to_first_byte", "experimental_navigation_types_with_softnavs", "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", "experimental_ad_count", "experimental_ad_density", "experimental_ad_cpu", "experimental_ad_kilobytes"]
联合字段 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/"

例如，如需请求 Chrome 开发者文档首页的桌面设备 Largest Contentful Paint 值，请运行以下命令：

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

响应正文

成功的请求会返回包含 record 对象和 urlNormalizationDetails 的响应，其结构如下：

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

例如，对上一个请求中的请求正文的响应可能如下所示：

{
  "record": {
    "key": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.9815
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.0108
          },
          {
            "start": 4000,
            "density": 0.0077
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

键

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 指定此记录所针对的源站。 注意：指定 origin 时，此源下所有网页的加载数据都会汇总到源级用户体验数据中。
url	string url 指定此记录所针对的具体网址。 注意：指定 url 时，系统只会汇总该特定网址的数据。

指标

metric是一组针对单个网页效果指标（例如 First Contentful Paint）的汇总用户体验数据。它可能包含一系列 bins 形式的 Chrome 实际使用情况摘要直方图、特定百分位数据（例如 p75），也可能包含带标签的分数。

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

或

{
  "fractions": {
    object (Fractions)
  }
}

字段
histogram[]	object (Bin) 某个指标的用户体验直方图。直方图将至少有一个分箱，并且所有分箱的密度总和约为 1。
percentiles	object (Percentiles) 指标的常见有用百分位数。百分位数的值类型将与为直方图分箱指定的值类型相同。
fractions	object (Fractions) 此对象包含带标签的分数，这些分数相加约为 1。 分数会四舍五入到小数点后 4 位。

分箱

bin 是从开始到结束（如果未指定结束，则从开始到正无穷大）的离散数据部分。

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

{
  "start": value,
  "end": value,
  "density": number
}

字段
start	(integer | string) “Start”是数据分箱的起点。
end	(integer | string) “End”是数据分箱的结束值。如果未填充 end，则表示该分箱没有结束时间，并且从 start 到 +inf 均有效。
density	number 在给定指标下，体验到此分箱值的用户所占的比例。 密度会四舍五入到小数点后 4 位。

百分位

Percentiles 包含给定统计百分位数的指标合成值。这些百分位数用于估算一定比例的用户（占总用户数的百分比）所体验到的指标值。

{
  "P75": value
}

字段
p75	(integer | string) 75% 的网页加载体验到的给定指标值不高于此值。

分数

Fractions 包含带标签的分数，其总和约为 1。每个标签都以某种方式描述网页加载，因此以这种方式表示的指标可以被视为产生不同的值（而非数值），而分数则表示测量特定不同值的频率。

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

与直方图分箱中的密度值非常相似，每个 fraction 都是一个数字 0.0 <= value <= 1.0，它们的总和约为 1.0。

UrlNormalization

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

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

字段
originalUrl	string 执行任何标准化操作之前的原始请求网址。
normalizedUrl	string 执行任何标准化操作后的网址。这是一个有效的用户体验网址，可以合理地进行查找。

速率限制

CrUX API 的查询次数上限为每个 Google Cloud 项目每分钟 150 次，此服务免费提供。您可以在 Google Cloud 控制台中查看此限制和当前用量。这一慷慨的配额应该足以满足绝大多数用例的需求，并且无法通过付费来增加配额。