Спецификации API

В разделе "Спецификация API" подробно описаны технические компоненты, необходимые для интеграции с платформой, включая области авторизации, определения типов данных и структуры конечных точек. Этот API представляет собой стратегическую эволюцию устаревшего Fitbit Web API, перестроенного на современной инфраструктуре для обеспечения более стабильной и согласованной работы разработчиков.

Области действия

Вам нужно обновить запрос на авторизацию, чтобы использовать области действия Google Health API. Области действия определяют, поддерживает ли ваше приложение операции чтения или записи. Следуйте инструкциям по реализации областей действия, в которых указано, что запрашивать нужно только необходимые области действия, настраивать доступ на запись – только при отправке данных, а также корректно обрабатывать частичное согласие.

Области действия Google Health API – это URL с протоколом HTTP, начинающиеся с https://www.googleapis.com/auth/googlehealth.{scope}. Пример: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly.

Сопоставления областей действия

Ниже показано, как области действия Fitbit Web API сопоставляются с областями действия Google Health API.

Таблица. Сопоставление областей действия Fitbit Web API и Google Health API
Области действия Fitbit Web API Области действия Google Health API
действия .activity_and_fitness.readonly
.activity_and_fitness.writeonly
blood_glucose .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
cardio_fitness .activity_and_fitness.readonly
.activity_and_fitness.writeonly
электрокардиограмма .ecg.readonly
пульс .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
irregular_rhythm_notifications .irn.readonly
местоположение .location.readonly
питание .nutrition.readonly
.nutrition.writeonly
oxygen_saturation .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
профиль .profile.readonly
.profile.writeonly
respiratory_rate .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
настройки .settings.readonly
.settings.writeonly
сон .sleep.readonly
.sleep.writeonly
температура .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
вес .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly

Типы данных

Ниже приведен список типов данных Google Health API и их сопоставление с Fitbit Web API.

Таблица. Сопоставление типов данных Fitbit Web API и Google Health API
Тип данных Fitbit Web API Тип данных Google Health API
  dataType		 Описание
Калории за активность Активный расход энергии
  active-energy-burned 		Представляет сожженные калории в периоды активности, включая сожженные калории в состоянии покоя за эти периоды. В Google Health API это значение можно получить, добавив BMR к типу данных active-energy-burned, который отслеживает только калории, сожженные во время активности.
Минуты в зоне активности Минуты в зоне активности
  active-zone-minutes
Содержит изменения в уровнях активности пользователя. Уровень активности
  activity-level 		Регистрирует уровень активности пользователя (например, сидячий или активный) за определенный период времени.
Высота Высота
  altitude
Действие caloriesBMR Расход энергии в состоянии покоя
  basal-energy-burned 		Количество калорий, сожженных за определенный период времени в результате основного обмена веществ.
Уровень глюкозы в крови Уровень глюкозы в крови
  blood-glucose
жировая ткань; Жировая ткань
  body-fat
caloriesOut в каждой зоне пульса Калории в пульсовой зоне
  calories-in-heart-rate-zone
Температура (тела) Внутренняя температура тела
  core-body-temperature
Сводка по ВСР Вариабельность сердечного ритма за день
  daily-heart-rate-variability
Сводка по SpO2 Ежедневный уровень кислорода в крови
  daily-oxygen-saturation 		Ежедневная сводка статистики насыщения крови кислородом (SpO2), рассчитанная на основе подтвержденных измерений во время сна.
частота сердечных сокращений в покое. Частота сердечных сокращений в покое за день
  daily-resting-heart-rate
температура кожи; Ежедневные отклонения температуры во время сна
  daily-sleep-temperature-derivations
Расстояние Расстояние
  distance
Электрокардиограмма (ЭКГ) Электрокардиограмма (ЭКГ)
  electrocardiogram
Записанная активность Тренировка
  exercise 		Записанные тренировки или занятия, включая время начала и окончания, типы активности и показатели сеанса.
Этажи Этажи
  floors
Еда Еда
  food
Единица измерения количества еды Единица измерения количества еды
  food-measurement-unit
частота сердечных сокращений Пульс
  heart-rate
ВСР в течение дня Вариабельность сердечного ритма
  heart-rate-variability
Уведомления о нарушении сердечного ритма Уведомление о нарушении сердечного ритма
  irregular-rhythm-notification
Журнал питания Журнал питания
  nutrition-log
SpO2 в течение дня Уровень кислорода в крови
  oxygen-saturation 		Возвращает только подтвержденные поминутные измерения SpO2 и исключает показания, помеченные как недействительные из-за артефактов движения или низкой достоверности датчика. Поскольку Fitbit Web API исключал только контрольное значение 50 %, Google Health API возвращает меньше элементов за тот же диапазон дат. Подробнее о фильтрации уровня кислорода в крови…
Значение МПК во время бега Бег: МПК
  run-vo2-max
Временной ряд активности: минуты без движения Период малоподвижности
  sedentary-period
Сон Сон
  sleep
Шаги Шаги
  steps
Временной ряд гребков во время плавания Данные о дорожках бассейна
  swim-lengths-data
Действие caloriesOut Общее количество калорий
  total-calories 		Общее количество сожженных калорий пользователем за определенный период времени, включая скорость метаболизма (BMR) и расход энергии.
Значение МПК МПК
  vo2-max
Вес Вес
  weight

Расчеты

Сопоставления и правила в Google Health API отличаются от Fitbit Web API.

Фильтрация по уровню кислорода в крови

При запросе данных о насыщении крови кислородом (oxygen-saturation) с детализацией по минутам Google Health API применяет более строгие фильтры для проверки данных, чем устаревший Fitbit Web API.

  • Устаревший Fitbit Web API (версий 1 и 3) исключал только образцы SpO2 с контрольным значением 50%.
  • Google Health API (версия 4) исключает все образцы SpO2, помеченные алгоритмом проверки как недействительные. Минута считается недействительной, если движение руки или неплотное прилегание к запястью делает сигнал оптического датчика ненадежным, когда показатель достоверности падает ниже 50%, в течение 3 минут непосредственно до и после недействительного считывания или когда действительный отрезок длится менее 4 минут подряд.

Поскольку Google Health API удаляет все недействительные измерения, а не только контрольное значение 50 %, он возвращает меньше элементов данных oxygen-saturation, чем Fitbit Web API, за тот же диапазон дат, и в поминутном охвате могут быть пробелы. Возвращенные поминутные показания соответствуют подтвержденным элементам данных, используемым для расчета отчета о сне пользователя daily-oxygen-saturation. Дополнительную информацию см. в разделе Фильтрация и достоверность данных SpO2 на уровне минут.

Уровень активности, метаболический эквивалент и пороговые значения шагов

В Google Health API поминутный уровень активности пользователя определяется на основе метаболического эквивалента нагрузки (MET) и количества шагов.

Уровень активности Устройства для измерения пульса Устройства без пульсометра
Сидячий образ жизни ≤ 1,5 МЕТ ≤ 1,5 МЕТ
Малоактивный > 1,5 MET и ≤ 4,2 MET > 1,5 MET и ≤ 3,5 MET
Умеренная активность > 4,2 MET и < 6,0 MET
(если не выполняются условия для очень высокой активности)		 > 3,5 MET и < 6,0 MET
(если не выполняются условия для высокой активности)
Очень активный ≥ 6,0 MET или ≥ 5,0 MET с частотой шагов 150 шагов в минуту или более ≥ 6,0 MET или ≥ 5,0 MET с частотой шагов 150 шагов в минуту или более

Количество минут активности состоит из MODERATELY_ACTIVE и VERY_ACTIVE минут. Однако минута высокой активности засчитывается, только если она происходит в течение непрерывного периода продолжительностью не менее 10 минут, при этом допускаются перерывы в активности продолжительностью не более 2 минут.

Минуты без движения и сон

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

Sedentary Minutes = 1440 - Sleep Minutes - Lightly Active Minutes - Moderately Active Minutes - Very Active Minutes

Индекс массы тела (ИМТ)

Поскольку в Google Health API нет встроенного типа данных для ИМТ, приложения должны рассчитывать индекс массы тела на клиентской стороне, используя записи о росте и весе:

  1. Получите вес пользователя в граммах из поля weightGrams в типе данных Вес. Переведите это значение в килограммы (разделите на 1000) или фунты (разделите на 453,59237).
  2. Получите рост пользователя в миллиметрах из поля heightMillimeters в типе данных Рост. Переведите это значение в метры (разделите на 1000) или дюймы (разделите на 25,4).
  3. ИМТ можно рассчитать по одной из следующих формул:
    • Формула показателя: BMI = weight (kg) / [height (m)]^2
    • Формула для имперской системы мер: BMI = (weight (lbs) / [height (in)]^2) * 703

Полученные значения ИМТ соответствуют следующим категориям:

Весовая категория Диапазон ИМТ
Недостаточный вес Менее 18,5
Здоровый вес 18,5–24,9
Избыточный вес От 25 до 29,9
Ожирение 30 или выше

Скорость метаболизма (BMR)

Скорость метаболизма (BMR) – это минимальное количество калорий, необходимое для поддержания основных функций организма в состоянии покоя. Поскольку в Google Health API нет встроенного типа данных для основного обмена, приложения должны рассчитывать его на стороне клиента по формуле Харриса – Бенедикта. Подробнее об этом можно узнать из статьи Уравнение Харриса – Бенедикта в Википедии.

Чтобы выполнить этот расчет:

  1. Получите вес пользователя в граммах из поля weightGrams в типе данных Вес и преобразуйте его в килограммы (разделите на 1000). Чтобы перевести фунты в килограммы, разделите на 2,2.
  2. Получите рост пользователя в миллиметрах из поля heightMillimeters типа данных Рост и преобразуйте его в сантиметры (разделите на 10). Чтобы перевести дюймы в сантиметры, умножьте на 2,54.
  3. Получите возраст пользователя в годах из поля age в ресурсе Profile.
  4. Получите биологический пол независимо (например, запросив его у пользователя или сохранив в собственной базе данных), поскольку Google Health API не предоставляет это поле.
  5. Используйте одну из следующих формул в зависимости от биологического пола пользователя:
    • Мужчины: BMR = 66 + (13.7 x weight_kg) + (5 x height_cm) - (6.8 x age_years)
    • Женщины: BMR = 655 + (9.6 x weight_kg) + (1.8 x height_cm) - (4.7 x age_years)

Общий суточный расход энергии (TDEE)

Общий суточный расход энергии (TDEE) – это оценка общего количества калорий, которые человек сжигает за день, с учетом как BMR, так и физической активности. Чтобы рассчитать суточный расход энергии, умножьте значение BMR на коэффициент активности, соответствующий образу жизни пользователя:

Уровень активности Описание Множитель
Сидячий образ жизни Мало или нет физических упражнений. BMR x 1.2
Низкая активность 1–3 дня тренировок в неделю. BMR x 1.375
Умеренная активность 3–5 дней тренировок в неделю. BMR x 1.55
Очень активный 6–7 дней тренировок в неделю. BMR x 1.725
Крайне высокая активность Очень тяжелые тренировки или физическая работа. BMR x 1.9

Конечные точки

Конечные точки REST используют согласованный синтаксис для всех типов данных.

  • Конечная точка сервиса. Базовый URL с протоколом HTTP меняется на https://health.googleapis.com.
  • Синтаксис конечных точек. Google Health API поддерживает ограниченное количество конечных точек, которые можно использовать для большинства поддерживаемых типов данных. Это обеспечивает согласованный синтаксис для всех типов данных и упрощает использование конечных точек.
  • Идентификатор пользователя. В синтаксисе конечной точки необходимо указать либо идентификатор пользователя, либо me. При использовании me идентификатор пользователя определяется по токену доступа.

Пример. Ниже показано, как вызвать конечную точку GET Profile с помощью Google Health API.

GET https://health.googleapis.com/v4/users/me/profile

Сопоставления конечных точек

Список доступных типов данных и поддерживаемых ими методов API приведен в таблице Типы данных Google Health API.

Тип конечной точки Fitbit Web API Google Health API
GET (Log | Summary | Daily Summary), когда вы запрашиваете данные за один день. dailyRollup, где windowSize – 1 день
GET (Intraday) – для запроса подробных данных. list способ
GET (временной ряд) по дате или интервалу Метод rollUp или dailyRollUp с диапазоном дат
GET (Log List) list способ
Журналы создания и обновления patch способ
DELETE Logs batchDelete способ
GET Profile users.getProfile возвращает информацию о пользователе.
users.getSettings возвращает единицы измерения и часовые пояса пользователя.
Обновить профиль users.updateProfile изменяет информацию о пользователе
users.updateSettings изменяет единицы измерения и часовые пояса пользователя
Получить идентификатор пользователя users.getIdentity возвращает устаревший идентификатор пользователя Fitbit и идентификатор пользователя Google.
Получить устройства users.pairedDevices возвращает список подключенных устройств.
Создание подписок projects.subscribers.subscriptions.create вручную создает подписку
Удалить подписки projects.subscribers.subscriptions.delete удаление подписки
Получить список подписок projects.subscribers.subscriptions.list – список всех подписок;