CrUX API

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

Попробовать

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

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

Ключ CrUX API

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

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

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

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

Ключ 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_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 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, данные по определенным процентилям (например, p75) или помеченные доли.

{
  "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. Этого должно быть достаточно для большинства случаев. Увеличить квоту за плату нельзя.