CrUX API

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

试试看！

常见用例

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

CrUX API 密钥

若要使用 CrUX API，您需要预配一个用于 Chrome UX Report API 使用的 Google Cloud API 密钥。

获取和使用 API 密钥

或在“凭据”页面中创建一个 OAuth 客户端 ID。

在您获得 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。

指标

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

浮点值会四舍五入（请注意，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%。

指标值类型

BigQuery 指标名称映射

收集时段

自 2022 年 10 月起，CRUX API 包含一个 collectionPeriod 对象，其中包含 firstDate 和 endDate 字段，分别表示汇总时间范围的开始日期和结束日期。例如：

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

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

您还可以在 PageSpeed Insights 中查看收集时间段：

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

示例查询

查询会以 JSON 对象的形式使用 POST 请求提交到 https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]"，其中 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"]}'

通过在查询中传递 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
• 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 时才会报告）

如果未提供 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 转码语法。

请求正文

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

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

例如，如需请求 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.
}

指标

metric 是一组针对单个 Web 性能指标（例如 First Contentful Paint）的汇总用户体验数据。它可能包含一系列 bins、特定百分位数据（例如第 75 百分位数）的实际 Chrome 使用情况摘要直方图，也可能包含标记的分数。

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

或

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

分箱

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

分桶的起始值和结束值采用其所代表的指标的值类型。例如，首次内容渲染以毫秒为单位进行衡量，并以整数形式显示，因此其指标分桶将使用 int32 作为其开始和结束类型。不过，累计布局偏移量以无单位的十进制数衡量，并以字符串编码的十进制数的形式显示，因此其指标分桶将使用字符串作为值类型。

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

百分位数

Percentiles 包含指标在给定统计百分位数时的合成值。这些指标用于估算某个指标在用户总数中的所占百分比的用户所获得的体验。

{
  "P75": value
}

分数

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
}

速率限制

CrUX API 的限制为每个 Google Cloud 项目每分钟 150 次查询，且无需付费。您可以在 Google Cloud 控制台中查看此限制和当前用量。这项配额非常充足，对于绝大多数用例来说应该足够了，而且您无法通过付费来增加配额。