CrUX API

API CrUX обеспечивает доступ с низкой задержкой к агрегированным данным о взаимодействии реальных пользователей с сайтом на уровне страниц и источников.

Попробовать

Примеры использования

CrUX API позволяет запрашивать показатели пользовательского опыта для определенного URI, например "Получить показатели для источника https://example.com".

Ключ API CrUX

Чтобы использовать CrUX API, нужен ключ Google Cloud API, подготовленный для использования Chrome UX Report API.

Получение и использование ключа API

Ключ также можно создать на странице Учетные данные.

Если у вас есть ключ, вы можете добавлять ко всем запросам из своего приложения параметр key=yourAPIKey.

Ключ API можно встраивать в URL в исходном виде (без кодирования).

Примеры запросов

Модель данных

В этом разделе описана структура данных в запросах и ответах.

Запись

Отдельный фрагмент информации о странице или сайте. Запись может содержать данные, относящиеся к определенному идентификатору и определенной комбинации параметров. Запись может содержать данные для одного или нескольких показателей.

Идентификаторы

Идентификаторы указывают, какие записи нужно найти. В CrUX это веб-страницы и сайты.

Происхождение

Если идентификатором является источник, то все данные, представленные для всех страниц в этом источнике, агрегируются вместе. Например, предположим, что у источника http://www.example.com есть страницы, указанные в этом файле Sitemap:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Это означает, что при запросе к Chrome UX Report с источником http://www.example.com будут возвращены агрегированные данные для http://www.example.com/, http://www.example.com/foo.html и http://www.example.com/bar.html, поскольку все эти страницы относятся к одному источнику.

URL

Если идентификатор – это URL, будут возвращены данные только для этого URL. Посмотрим ещё раз на исходный файл Sitemap http://www.example.com:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Если в качестве идентификатора задан URL со значением http://www.example.com/foo.html, будут возвращены данные только для этой страницы.

Размеры

Параметры определяют группу данных, по которой агрегируется запись. Например, тип устройства PHONE указывает, что запись содержит информацию о загрузках, которые произошли на мобильном устройстве. У каждого параметра будет определенное количество значений. Если параметр не указан, это означает, что он агрегирован по всем значениям. Например, если тип устройства не указан, то запись содержит информацию о загрузках на устройствах всех типов.

Тип устройства

Класс устройства, с помощью которого конечный пользователь перешел на страницу. Это общий класс устройств, который делится на PHONE, TABLET и DESKTOP.

Показатель

Отчетные показатели представлены в виде статистических агрегаций, гистограмм, процентилей и долей.

Значения с плавающей запятой округляются до четырех знаков после запятой (обратите внимание, что показатели cumulative_layout_shift представляют собой числа двойной точности, закодированные в виде строк, поэтому не считаются числами с плавающей запятой и указываются с двумя знаками после запятой).

Гистограмма

На гистограмме показано, какой процент загрузок страниц попадает в определенные диапазоны для этого показателя.

Пример гистограммы с тремя интервалами для определенного показателя:

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

Эти данные показывают, что в 38,18% случаев загрузки страниц значение показателя находилось в диапазоне от 0 до 1000 мс. Единицы измерения показателя не содержатся в этой гистограмме, в данном случае мы будем предполагать, что это миллисекунды.

Кроме того, в 49,91% случаев загрузки страницы значение показателя находилось в диапазоне от 1000 до 3000 мс, а в 11,92 % случаев – превышало 3000 мс.

Процентили

Показатели также могут содержать процентили, которые могут быть полезны для дополнительного анализа. Мы сообщаем значения показателей для определенного процентиля. Они рассчитываются на основе полного набора доступных данных, а не конечных данных, разбитых по интервалам, поэтому могут не совпадать с интерполированным процентилем, рассчитанным на основе конечной гистограммы с интервалами.

{
  "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 г. 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 дней назад). 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"]}'

Данные на уровне страницы можно получить через 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
• 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 UX Report API.

Конвейер данных

Прежде чем стать доступным через API, набор данных CrUX проходит через конвейер, где данные консолидируются, агрегируются и фильтруются.

Скользящее среднее

В отчете Chrome UX Report представлены агрегированные показатели за 28 дней (скользящее среднее). Это означает, что в любой момент времени в Chrome UX Report представлены агрегированные данные за последние 28 дней.

Это похоже на то, как набор данных CrUX в BigQuery агрегирует ежемесячные отчеты.

Обновляется ежедневно

Данные обновляются ежедневно примерно в 04:00 по всемирному координированному времени (UTC). Соглашение об уровне обслуживания для времени обновления отсутствует. Обновление выполняется ежедневно при наличии ресурсов и возможностей.

Схема

У CrUX API одна конечная точка, которая принимает HTTP-запросы POST. API возвращает объект record, который содержит один или несколько объектов metrics, соответствующих данным о производительности для запрошенного источника или страницы.

HTTP-запрос

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

URL имеет синтаксис gRPC Transcoding.

Тело запроса

Ниже приведена структура данных в теле запроса.

{
  "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, используйте следующий код:

{
  "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 – это набор агрегированных данных об удобстве использования для одного показателя эффективности сайта, например первой отрисовки контента. Он может содержать сводную гистограмму реального использования Chrome в виде серии символов bins, данные о конкретных процентилях (например, 75-м процентиле) или помеченные доли.

{
  "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, которые были выполнены, чтобы повысить вероятность успешного поиска. Это базовые автоматические изменения, которые вносятся, когда поиск по указанному значению url_pattern заведомо не даст результатов. Сложные действия, такие как переадресация, не выполняются.

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

Ограничение частоты запросов

Для CrUX API действует ограничение в 150 запросов в минуту на облачный проект Google Cloud. Этот сервис предоставляется бесплатно. Этот лимит и текущее использование можно посмотреть в консоли Google Cloud. Этого должно быть достаточно для большинства случаев. Увеличить квоту за плату нельзя.