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

这意味着，当来源设置为 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，则表示记录包含移动设备上发生的加载的相关信息。每个维度都有一定数量的值，如果不指定该维度，就意味着该维度将针对所有值进行汇总。例如，如果未指定任何外形规格，则表示记录包含与任何外形规格上发生的加载相关的信息。

设备规格

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

有效连接类型

有效的连接类型是指导航到网页时设备的估算连接质量。这是一个分为 offline、slow-2G、2G、3G 和 4G 的常规类。

指标

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

浮点值会四舍五入到小数点后 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
first_contentful_paint int 毫秒 包含三个分箱的直方图，百分位数为 p75 fcp
interaction_to_next_paint int 毫秒 包含三个分箱的直方图，百分位数为 p75 inp
largest_contentful_paint int 毫秒 包含三个分箱的直方图，百分位数为 p75 lcp
experimental_time_to_first_byte int 毫秒 包含三个分箱的直方图，百分位数为 p75 ttfb
form_factors 4 位小数 百分比 从设备规格映射到比例 外形规格
navigation_types 4 位小数 百分比 从导航类型映射到分数 导航类型
round_trip_time int 毫秒 百分位数为 p75 rtt

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
navigation_types navigation_types
form_factors 不适用
round_trip_time 不适用

收集期

自 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)，夏令时间保持不变。

示例查询

您可以使用 POST 请求向 https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" 提交 JSON 对象形式的查询，并在 POST 正文中将查询数据作为 JSON 对象：

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

若要通过该 API 获得网页级数据，请在查询中传递 url 属性（而非 origin）：

{
  "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
  • form_factors（仅当请求中未指定 formFactor 时才报告）

如果您未提供任何 formFactor 值，系统会针对所有设备类型对这些值进行汇总。

如需查看更多示例查询，请参阅使用 Chrome UX Report API。

数据流水线

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

滚动平均值

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

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

每日动态

数据每天在世界协调时间 (UTC) 04:00 左右更新。没有针对更新时间的服务等级协议；我们每天都在尽最大努力运行

架构

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

HTTP 请求

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

网址采用 gRPC 转码语法。

请求正文

请求正文应包含具有以下结构的数据：

{
  "effectiveConnectionType": string,
  "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.
}
字段
effectiveConnectionType

string

有效连接类型是一个查询维度，用于指定记录的数据应属于的有效网络类。

此字段使用 Network Information API 规范中指定的值 ["offline", "slow-2G", "2G", "3G", "4G"]

注意：如果未指定有效的连接类型，系统将返回一个包含所有有效连接类型汇总数据的特殊记录。
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"]
联合字段 url_pattern。url_pattern 是记录查询的主要标识符。它只能是下列其中一项：
origin

string

url_pattern“origin”是指一种网址格式，即网站的来源。

示例："https://example.com"、"https://cloud.google.com"
url

string

url_pattern url 是指网址格式，即任意网址。

示例："https://example.com/、https://cloud.google.com/why-google-cloud/"

例如，要请求 Chrome 开发者文档主页的桌面设备最大内容渲染值，请使用以下代码：

{
  "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 定义了将此记录标识为唯一的所有维度。

{
  "effectiveConnectionType": string,
  "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)

设备规格是指用于访问此记录的网站的设备类别。

如果未指定外形规格，系统将返回所有外形规格的汇总数据。
effectiveConnectionType

string

有效连接类型是所有用户在遇到该记录时遇到的常规连接类别。此字段使用的值 ["offline", "slow-2G", "2G", "3G", "4G"] 中指定的值：https://wicg.github.io/netinfo/#effective-connection-types

如果未指定有效连接类型，系统将返回所有有效连接类型的汇总数据。
联合字段 url_pattern。网址格式是记录适用的网址。url_pattern 只能是下列其中一项：
origin

string

origin 指定此记录的来源。

注意：如果指定 origin，此来源下所有网页加载的数据会汇总为来源级用户体验数据。
url

string

url 用于指定此记录对应的特定网址。

注意：指定 url 时，系统只会汇总该特定网址的数据。

指标

metric 是单个网页性能指标（例如首次内容渲染）的一组汇总用户体验数据。 其中可能包含实际 Chrome 使用情况的汇总直方图（显示为一系列特定百分位数据）bins （如 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 以毫秒为单位进行测量，并以 int 的形式公开，因此其指标 bin 将使用 int32s 作为 start 和 end 类型。不过，累积布局偏移以无单位的小数形式衡量，并以字符串编码的形式公开，因此其指标分箱将使用字符串作为其值类型。

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

(integer | string)

起始位置是数据箱的起始位置。
end

(integer | string)

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 控制台中查看此限额和您当前的用量。这种宽裕的配额应该足以满足绝大多数用例的需要，并且无法为增加的配额付费。