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

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

Области применения

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

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

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

Вот как области действия веб-API Fitbit соотносятся с областями действия API Google Health:

Таблица: Сопоставление областей действия веб-API Fitbit и API Google Health.
Области действия веб-API Fitbit Области действия API Google Health
активность .activity_and_fitness.readonly
.activity_and_fitness.writeonly
уровень глюкозы в крови .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
кардио_фитнес .activity_and_fitness.readonly
.activity_and_fitness.writeonly
ЭКГ .ecg.readonly
частота сердечных сокращений .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
нерегулярные_ритм_уведомления .irn.readonly
расположение .location.readonly
питание .nutrition.readonly
.nutrition.writeonly
насыщение кислородом .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
профиль .profile.readonly
.profile.writeonly
частота дыхания .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

Типы данных

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

Для получения дополнительной информации о том, как отображаются данные этих типов, см. руководство «Наличие данных и истинные нули» . В этом руководстве содержится подробная информация о неактивности и фильтрации данных на запястье.

Таблица: Сопоставление типов данных между веб-API Fitbit и API Google Health.
Тип данных веб-API Fitbit Тип данных API Google Health
dataType		 Описание
Калории, связанные с физической активностью Сожженная активная энергия
active-energy-burned		 Отражает количество калорий, сожженных в периоды активности, включая базальный метаболизм (БМР) за эти периоды. В API Google Health это можно восстановить, добавив БМР к типу данных 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
Частота сердечных сокращений в состоянии покоя Ежедневная частота сердечных сокращений в состоянии покоя
daily-resting-heart-rate
Температура кожи Ежедневные измерения температуры во время сна
daily-sleep-temperature-derivations
Расстояние Расстояние
distance
Электрокардиограмма (ЭКГ) Электрокардиограмма (ЭКГ)
electrocardiogram
Зарегистрированная активность Упражнение
exercise		 Записанные тренировки или занятия, включающие время начала/окончания, виды активности и показатели занятия.
Полы Полы
floors
Еда Еда
food
Измерительный прибор для пищевых продуктов Измерительный прибор для пищевых продуктов
food-measurement-unit
Частота сердечных сокращений Частота сердечных сокращений
heart-rate
Вариабельность сердечного ритма внутри дня Вариабельность сердечного ритма
heart-rate-variability
Уведомления о нерегулярном ритме (IRN) Уведомление о нарушении ритма
irregular-rhythm-notification
Журнал учета продуктов питания Журнал учета пищевых продуктов
nutrition-log
Внутридневная сатурация кислорода (SpO2) Насыщение кислородом
oxygen-saturation
Значение VO2 Max во время бега пользователя Бег VO2 Max
run-vo2-max
Последовательность активности во времени, минуты сидячего образа жизни Сидячий период
sedentary-period
Спать Спать
sleep
Шаги Шаги
steps
Последовательность движений во времени при плавании Данные о длине заплывов
swim-lengths-data
caloriesOut на активность Общее количество калорий
total-calories		 Общее количество калорий, сожженных пользователем за определенный период времени, включая базовую и активную энергию.
Значение VO2 Max VO2 Max
vo2-max
Масса Масса
weight

Расчеты

Сопоставление данных и правила в API Google Health отличаются от правил веб-API Fitbit.

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

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

Уровень активности Устройства для измерения частоты сердечных сокращений Устройства, не измеряющие частоту сердечных сокращений
Сидячий образ жизни ≤ 1,5 METs ≤ 1,5 METs
Слабоактивный > 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

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

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

  1. Получите вес пользователя в граммах из поля weightGrams в типе данных Weight . Преобразуйте его в килограммы (разделите на 1000) или фунты (разделите на 453,59237).
  2. Получите рост пользователя в миллиметрах из поля heightMillimeters в типе данных Height . Преобразуйте его в метры (разделите на 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 или выше

Базальный метаболизм (БМР)

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

Для выполнения этого расчета:

  1. Получите вес пользователя в граммах из поля weightGrams в типе данных Weight и переведите его в килограммы (разделите на 1000). Для перевода фунтов в килограммы разделите на 2,2.
  2. Получите рост пользователя в миллиметрах из поля heightMillimeters в типе данных Height и переведите его в сантиметры (разделите на 10). Для перевода дюймов в сантиметры умножьте на 2,54.
  3. Получите возраст пользователя в годах из поля age в ресурсе «Профиль» .
  4. Получить биологический пол можно самостоятельно (например, запросив его у пользователя или сохранив в собственной базе данных), поскольку API Google Health не предоставляет доступ к этому полю.
  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) — это оценка общего количества калорий, сжигаемых человеком за день, с учетом как базального метаболизма (BMR), так и физической активности. Для оценки 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-интерфейсы используют единый синтаксис для всех типов данных.

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

Пример : Вот пример вызова конечной точки GET Profile с использованием API Google Health.

ПОЛУЧИТЬ https://health.googleapis.com/v4/users/me/profile

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

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

Тип конечной точки веб-API Fitbit API Google Health
Запрос GET (Log | Summary | Daily Summary), в котором запрашиваются данные за один день. Метод dailyRollup с windowSize = 1 день
GET (внутридневная торговля), где запрашиваются детализированные данные. метод list
Получение данных (временного ряда) по дате или интервалу. Метод rollUp или dailyRollUp , включающий диапазон дат.
GET (Список логов) метод list
СОЗДАНИЕ И ОБНОВЛЕНИЕ ЖУРНАЛОВ метод patch
Удалить журналы метод batchDelete
Получить профиль 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 отображает все подписки