API истории CruX

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

Попробуйте!

Общий случай использования

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

History API имеет ту же структуру, что и ежедневный CrUX API, за исключением того, что значения задаются в массиве, а ключи помечены именами во множественном числе (например, histogramTimeseries вместо histogram или p75s вместо p75 ).

Ключ API CruX

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

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

Или создайте его на странице «Учетные данные» .

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

Ключ API можно безопасно встраивать в URL-адреса; ему не нужна никакая кодировка.

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

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

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

Записывать

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

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

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

Источник

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

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

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

URL-адреса

Если идентификатором является URL-адрес, будут возвращены только данные для этого конкретного URL-адреса. Снова взглянем на исходную карту сайта 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 указывает на то, что запись содержит информацию о нагрузках, произошедших на мобильном устройстве.

API истории CrUX доступен только в совокупности по измерениям форм-фактора. Это общий класс устройств, разделенный на PHONE , TABLET и DESKTOP .

Метрика

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

Гистограммы

Когда метрики выражаются в виде массива гистограмм, каждая запись временного ряда представляет собой процент загрузок страниц, для которых метрика попала в интервал, пропорционально всем. Точки данных представлены в порядке дат периода сбора данных, также возвращаемых API, причем первая точка представляет собой самый ранний период, а конечная точка — самый последний период сбора данных.

Гистограмма с тремя интервалами для примера метрики выглядит следующим образом:

{
  "histogramTimeseries": [
    {
      "start": 0,
      "end": 2500,
      "densities": [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]
    },
    {
      "start": 2500,
      "end": 4000,
      "densities": [0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527]
    },
    {
      "start": 4000,
      "densities": [0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285]
    }
  ],
}

Эти данные показывают, что для 91,90% загрузок страниц значение метрики примера составляло от 0 мс до 2500 мс для первого периода сбора в истории, за ним следуют 92,03%, 91,94%... Единицы метрики не содержатся в этой гистограмме. в данном случае мы будем считать миллисекунды.

Кроме того, в 5,21% загрузок страниц значение показателя примера составляло от 2500 до 4000 мс в первый период сбора в истории, а в 2,88% загрузок страниц наблюдалось значение, превышающее 4000 мс в первый период сбора в истории.

процентили

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

Точки данных представлены в порядке дат периода сбора данных, также возвращаемых API, причем первая точка представляет собой самый ранний период, а конечная точка — самый последний период сбора данных.

{
  "percentilesTimeseries": {
    "p75s": [1362, 1352, 1344, 1356, 1366, 1377]
  },
}

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

Фракции

Метрики могут быть выражены как временные ряды помеченных фракций; каждая метка определенным образом описывает загрузку страницы. Точки данных представлены в порядке дат периода сбора данных, также возвращаемых API, причем первая точка представляет собой самый ранний период, а конечная точка — самый последний период сбора данных.

Пример:

{    
  "fractionTimeseries": {
    "desktop": {"fractions": [0.3195, 0.2115, 0.1421]},
    "phone": {"fractions": [0.6295, 0.7544, 0.8288]},
    "tablet": {"fractions": [0.051, 0.0341, 0.029]}
  }
}

В этом примере самые последние данные показывают, что 14,21% загрузок страниц приходилось на настольные компьютеры, а 82,88% — на телефоны.

Типы значений метрик

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

Соответствие метрике

В зависимости от критериев приемлемости источник или URL-адрес могут иметь право только на некоторые периоды сбора данных, охватываемые API истории CrUX. В этих случаях API истории CrUX вернет "NaN" для плотностей histogramTimeseries и null для percentilesTimeseries для периодов сбора, по которым нет подходящих данных. Причина различия в том, что плотности гистограмм всегда представляют собой числа, а процентили могут быть числами или строками (CLS использует строки, даже если они выглядят как числа).

Например, если во втором периоде не было подходящих данных, это будет выглядеть так:

{
  "histogramTimeseries": [
    {
      "start": 0,
      "end": 2500,
      "densities": [0.9190, "NaN", 0.9194, 0.9195, 0.9183, 0.9187]
    },
    {
      "start": 2500,
      "end": 4000,
      "densities": [0.0521, "NaN", 0.0518, 0.0518, 0.0526, 0.0527]
    },
    {
      "start": 4000,
      "densities": [0.0288, "NaN", 0.0286, 0.0285, 0.0290, 0.0285]
    }
  ],
  "percentilesTimeseries": {
    "p75s": [1362, null, 1344, 1356, 1366, 1377]
  },
}

Для URL-адресов или источников, которые с течением времени попадают в список допустимых, вы можете заметить множество пропущенных записей.

Периоды сбора

API истории CrUX содержит объект collectionPeriods с массивом полей firstDate и endDate , представляющих даты начала и окончания каждого окна агрегации. Например:

    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }
    ]

Эти периоды сбора расположены в порядке возрастания и представляют собой диапазон дат каждой точки данных в других разделах ответа.

API истории обновляется каждый понедельник и содержит данные до предыдущей субботы (согласно стандартной двухдневной задержке). Он содержит данные за предыдущие 25 недель — один период сбора в неделю.

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

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

Запросы отправляются как объекты JSON с использованием запроса POST к https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]" с данными запроса в виде объекта JSON в теле POST.

Обратите внимание на использование queryHistoryRecord вместо queryRecord ежедневного API CrUX.

Пример тела:

{
  "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:queryHistoryRecord?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
• round_trip_time
• form_factors (сообщается только в том случае, если в запросе не указан formFactor )

Если значение formFactor не указано, значения будут агрегированы по всем форм-факторам.

Дополнительные примеры запросов см. в руководстве «Использование API истории CrUX» .

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

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

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

Данные в отчете Chrome UX представляют собой 28-дневное скользящее среднее агрегированных показателей. Это означает, что данные, представленные в отчете Chrome UX в любой момент времени, на самом деле представляют собой совокупные данные за последние 28 дней.

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

Еженедельные обновления

API истории обновляется каждый понедельник около 04:00 UTC и содержит данные до предыдущей субботы (в соответствии со стандартной двухдневной задержкой). Он содержит данные за предыдущие 25 недель (приблизительно 6 месяцев), один период сбора в неделю.

Для времени обновления не существует соглашения об уровне обслуживания; он выполняется каждый день с максимальной отдачей.

Схема

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

HTTP-запрос

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

URL-адрес использует синтаксис транскодирования gRPC .

Тело запроса

API истории CrUX использует те же тела запросов, что и ежедневный API CrUX .

Например, чтобы запросить значения наибольшего содержимого рабочего стола для домашней страницы web.dev:

{
  "origin": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

Тело ответа

Успешные запросы возвращают ответы с объектом record и urlNormalizationDetails в следующей структуре:

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

Например, ответ на тело запроса в предыдущем запросе может быть таким:

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogramTimeseries": [{
            "start": 0, "end": 2500, "densities": [
              0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187, ...
            ]
          }, {
            "start": 2500, "end": 4000, "densities": [
              0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527, ...
            ]
          },  {
            "start": 4000, "densities": [
              0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285, ...
            ]
          }
        ],
        "percentilesTimeseries": {
          "p75s": [
            1362, 1352, 1344, 1356, 1366, 1377, ...
          ]
        }
      }
    },
    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }, {
        ...
      }
    ]
  }
}

Ключ

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 .

{
  "histogramTimeseries": [
    {
      object (Bin)
    }
  ],
  "percentilesTimeseries": {
    object (Percentiles)
  }
}

или

"fractionTimeseries": {
  object (Fractions)
}

Бин

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

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

{
  "start": value,
  "end": value,
  "densities": [number, number, number...etc.]
}

процентили

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

{
  "P75": value
}

Фракции

Fractions содержат временные ряды помеченных дробей, сумма которых составляет ~1 на каждую запись. Каждая метка каким-то образом описывает загрузку страницы, поэтому метрики, представленные таким образом, можно рассматривать как производящие отдельные значения вместо числовых значений, а дроби выражают, как часто измерялось конкретное отдельное значение.

{
  "label_1": { "fractions": array[fraction]},
  "label_1": { "fractions": array[fraction]},
  ...
  "label_n": { "fractions": array[fraction]}
}

Подобно значениям плотности в интервалах гистограммы, каждая fraction представляет собой число 0.0 <= value <= 1.0 , и в сумме они дают ~1,0. Если метрика недоступна для определенного периода сбора, то соответствующая запись будет «NaN» во всех массивах дробей.

Нормализация URL

Объект, представляющий действия по нормализации, предпринятые для нормализации URL-адреса, чтобы повысить вероятность успешного поиска. Это простые автоматические изменения, которые вносятся в случае, если поиск по предоставленному url_pattern , как известно, не удался. Сложные действия, такие как следующие перенаправления, не обрабатываются.

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

Ограничения ставок

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