Спецификации 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 этот показатель можно рассчитать, добавив уровень основного обмена к типу данных 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 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 (POST .../dataPoints:dailyRollUp) с помощью windowSizeDays: 1
GET (Intraday) – для запроса подробных данных. list способ
GET (временной ряд) по дате или интервалу Метод rollUp или dailyRollUp с диапазоном дат
GET (список журналов) list способ
Журналы создания и обновления patch способ
Журналы DELETE 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 – список всех подписок;