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%。

指标值类型

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]"，其中包含作为 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"]}'

通过在查询中传递 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 时报告）
• 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 左右更新。更新时间没有服务等级协议；系统会每天尽力运行。

架构

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 效果指标（例如首次内容绘制）的一组汇总用户体验数据。它可能包含实际 Chrome 使用情况的汇总直方图（以一系列 bins 表示）、具体百分位数数据（例如 p75），也可能包含带标签的分数。

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

或

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

分箱

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

分箱的起始值和结束值以其所代表指标的值类型给出。例如，First Contentful Paint 以毫秒为单位进行测量，并以 int 形式公开，因此其指标分箱将使用 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 控制台中查看此限制和当前用量。这一慷慨的配额应该足以满足绝大多数应用场景的需求，并且无法通过付费来增加配额。