Google Health API отслеживает тренировки и историю упражнений пользователя с помощью типа данных exercise. Сеанс выступает в качестве контейнера, который объединяет метаданные активности, события приостановки и возобновления, круги или отрезки, а также сводные показатели.
Узнайте, как читать, записывать и структурировать тренировки в приложении, чтобы сделать его максимально удобным для пользователей.
Поддерживаемые типы данных
Для отслеживания тренировок и сеансов активности API поддерживает следующий тип данных:
| Тип данных | Доступные операции |
Область действия |
|---|---|---|
|
Тренировка
dataType:
exercisefilter parameter: exercise
Тип записи: сеанс.
Совместимые устройства
|
list, get, reconcile, create, update, batchDelete | .activity_and_fitness.readonly.activity_and_fitness.writeonly |
Типы данных телеметрии
Хотя тренировки используют тип данных exercise в качестве контейнера, носимые устройства также записывают подробную высокочастотную телеметрию во время тренировки. В Google Health API эти подробные типы данных телеметрии за день доступны только для чтения. Их нельзя создавать или изменять напрямую через конечные точки REST.
При записи тренировки через REST API передавайте агрегированные показатели тренировки в объекте metricsSummary элемента данных exercise.
В таблице ниже показано, как сводные поля в exercise.metricsSummary сопоставляются с соответствующими типами данных телеметрии за день, доступными только для чтения, которые можно запрашивать для временного окна тренировки.
Поле сводки (metricsSummary) |
Название типа данных телеметрии в течение дня | Идентификатор типа данных телеметрии API (только для чтения) | Поле фильтра (?filter=) |
Требуемая область действия OAuth для чтения |
|---|---|---|---|---|
caloriesKcal |
Активный расход энергии | active-energy-burned |
active_energy_burned.interval.start_time |
activity_and_fitness.readonly |
distanceMillimeters |
Расстояние | distance |
distance.interval.start_time |
activity_and_fitness.readonly |
steps |
Шаги | steps |
steps.interval.start_time |
activity_and_fitness.readonly |
averageHeartRateBeatsPerMinute |
частота сердечных сокращений | heart-rate |
heart_rate.sample_time.physical_time |
health_metrics_and_measurements.readonly |
activeZoneMinutes |
Минуты в зоне активности | active-zone-minutes |
active_zone_minutes.interval.start_time |
activity_and_fitness.readonly |
В следующих разделах приведены технические сведения о типе данных exercise, в том числе примеры представления REST, обработка маршрутов GPS и рекомендации по интеграции.
Тренировки
Записывать данные о ежедневной активности или тренировках в виде элементов сеансов exercise. Каждый элемент описывает сеанс в целом, содержит подробные сведения об интервалах между событиями (например, о паузах и возобновлениях) и предоставляет сводные показатели (например, общее расстояние, количество шагов и средний пульс).
Атрибуты сеанса
При структурировании элемента данных о тренировке проверьте следующие основные компоненты:
- Время тренировки (
interval). Время начала и окончания тренировки, а также часовые пояса, в которых она проходила. - Тип активности (
exerciseType). Категория активности, напримерRUNNING,WALKING,BIKINGилиAEROBIC_WORKOUT. Укажите точный тип физической тренировки. - Отображаемое название (
displayName): Удобное название тренировки. При создании через REST API сервер заполняет локализованное отображаемое название дляexerciseType, например"Run"дляRUNNING. - Продолжительность активности (
activeDuration). Фактическое время тренировки без учета пауз. Стандартный формат –Duration(например,"1800s"). На сервере значениеactiveDurationрассчитывается как разница междуintervalсеанса и интерваламиPAUSE/RESUMEилиAUTO_PAUSE/AUTO_RESUMEвexerciseEvents.
Сводные показатели
Вложенный объект metricsSummary содержит общие и средние показатели, рассчитанные за все время тренировки:
caloriesKcal– общее количество активных калорий, сожженных во время тренировки, в килокалориях (kcal).distanceMillimeters– общее пройденное расстояние в миллиметрах (для высокой точности).steps– общее количество шагов, сделанных во время тренировки.averageHeartRateBeatsPerMinute– средний пульс пользователя за минуты активности в течение сеанса.activeZoneMinutes– общее количество минут в зоне активности, заработанных во время тренировки.averageSpeedMillimetersPerSecond– средняя скорость движения в миллиметрах в секунду.averagePaceSecondsPerMeter– средний темп во время минут активности в рамках тренировки, измеряется в секундах на метр.elevationGainMillimeters– общий набор высоты за тренировку.
Круги и отрезки
Для тренировок, включающих круги (например, бег по дорожке или плавание в бассейне), синхронизированных с поддерживаемых устройств, splitSummaries сегментирует занятие по кругам или отрезкам.
Каждая часть содержит:
- Определенный
startTimeиendTime. activeDuration, представляющий фактическое время круга.metricsSummary, относящаяся только к этому сегменту.splitTypeдля определения границ раздела (например,DISTANCE,DURATIONилиMANUAL).
Сведения о тренировках
Чтобы точно рассчитать активную продолжительность, отслеживайте переходы между состояниями (например, события ручной или автоматической паузы) с помощью exerciseEvents.
Каждое событие содержит временную метку (eventTime) и тип:
START/STOP– временные метки, указывающие, когда пользователь начал или остановил запись.PAUSE/RESUME– указывает, когда тренировка была приостановлена или возобновлена вручную.AUTO_PAUSE/AUTO_RESUME– автоматическая приостановка и возобновление тренировки на основе данных датчиков.
Запись данных о тренировках
Чтобы создать, обновить или импортировать тренировку, запишите элемент данных в коллекцию типа данных exercise. Используйте конечную точку create dataPoints.
Пример представления REST
В примере ниже показано, как записать тренировку с помощью метода POST.
Запрос
POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer access-token
Content-Type: application/json
{
"dataSource": {
"recordingMethod": "ACTIVELY_MEASURED",
"platform": "GOOGLE_WEB_API"
},
"exercise": {
"interval": {
"startTime": "2026-04-20T08:00:00Z",
"startUtcOffset": "0s",
"endTime": "2026-04-20T08:35:00Z",
"endUtcOffset": "0s"
},
"exerciseType": "RUNNING",
"activeDuration": "1800s",
"metricsSummary": {
"caloriesKcal": 380.0,
"distanceMillimeters": 5000000.0,
"steps": "6200",
"averageHeartRateBeatsPerMinute": "148",
"averagePaceSecondsPerMeter": 0.36
},
"exerciseEvents": [
{
"eventTime": "2026-04-20T08:15:00Z",
"eventUtcOffset": "0s",
"exerciseEventType": "PAUSE"
},
{
"eventTime": "2026-04-20T08:20:00Z",
"eventUtcOffset": "0s",
"exerciseEventType": "RESUME"
}
]
}
}Ответ
{
"done": true,
"response": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
"name": "users/999298779973222220/dataTypes/exercise/dataPoints/3054085373369111216",
"dataSource": {
"recordingMethod": "ACTIVELY_MEASURED",
"application": {
"googleWebClientId": "438076457939-example.apps.googleusercontent.com"
},
"platform": "GOOGLE_WEB_API"
},
"exercise": {
"interval": {
"startTime": "2026-04-20T08:00:00Z",
"startUtcOffset": "0s",
"endTime": "2026-04-20T08:35:00Z",
"endUtcOffset": "0s"
},
"exerciseType": "RUNNING",
"metricsSummary": {
"caloriesKcal": 380,
"distanceMillimeters": 5000000,
"steps": "6200",
"averagePaceSecondsPerMeter": 0.36,
"averageHeartRateBeatsPerMinute": "148"
},
"exerciseMetadata": {},
"displayName": "Run",
"activeDuration": "1800s",
"exerciseEvents": [
{
"eventTime": "2026-04-20T08:15:00Z",
"eventUtcOffset": "0s",
"exerciseEventType": "PAUSE"
},
{
"eventTime": "2026-04-20T08:20:00Z",
"eventUtcOffset": "0s",
"exerciseEventType": "RESUME"
}
],
"updateTime": "2026-04-20T08:35:10.123456Z",
"createTime": "2026-04-20T08:35:10.123456Z"
}
}
}Маршруты GPS и отслеживание местоположения
API сохраняет базовые сводки сеансов непосредственно в элементе данных exercise, но обрабатывает подробную историю местоположений и координаты маршрута GPS как отдельный поток.
Чтобы скачать подробные данные о маршруте для тренировки на улице, вызовите пользовательский метод exportExerciseTcx. Эта конечная точка возвращает маршрут в стандартном отраслевом формате Training Center XML (TCX).
Экспортировать GPS-маршрут
Запрос
GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints/exercise-data-point-id:exportExerciseTcx?alt=media Authorization: Bearer access-token
Ответ
Полезная нагрузка HTTP с Content-Type: application/tcx+xml и заголовками, которые указывают браузеру сохранить файл.
<?xml version="1.0" encoding="UTF-8"?>
<TrainingCenterDatabase xmlns="http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2">
<Activities>
<Activity Sport="Running">
<Id>2026-04-20T08:00:00Z</Id>
<Lap StartTime="2026-04-20T08:00:00Z">
<TotalTimeSeconds>1800</TotalTimeSeconds>
<DistanceMeters>5000</DistanceMeters>
<Calories>380</Calories>
<Intensity>Active</Intensity>
<TriggerMethod>Manual</TriggerMethod>
<Track>
<Trackpoint>
<Time>2026-04-20T08:00:00Z</Time>
<Position>
<LatitudeDegrees>37.7749</LatitudeDegrees>
<LongitudeDegrees>-122.4194</LongitudeDegrees>
</Position>
<AltitudeMeters>15.0</AltitudeMeters>
<DistanceMeters>0.0</DistanceMeters>
</Trackpoint>
</Track>
</Lap>
</Activity>
</Activities>
</TrainingCenterDatabase>Необходимые области действия и местоположение
Чтобы использовать функцию GPS-маршруты и отслеживание местоположения, ваше приложение должно запрашивать следующие области действия OAuth:
- Прочитано:
https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly - Запись:
https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly. - Прочитано:
https://www.googleapis.com/auth/googlehealth.location.readonly
Правила
При интеграции отслеживания тренировок в приложение следуйте этим рекомендациям по проектированию и реализации.
Активное и общее время
Чтобы рассчитать скорость или темп, всегда используйте activeDuration, а не разницу между startTime и endTime. Это предотвращает искажение
ваших показателей из-за пауз.
Например, если пользователь начал тренировку в 08:00 и закончил в 08:35, ее общая продолжительность составит 2100 секунд. Если пользователь приостановил тренировку на 5 минут (300 секунд) и вы включили события PAUSE и RESUME в exerciseEvents, то активная продолжительность составит "1800s" (2100 – 300). API использует активную продолжительность для расчета средних значений, деля общее расстояние на 1800 секунд вместо 2100.
Расчет скорости и темпа
Google Health API использует стандартные формулы для расчета скорости и темпа:
- Скорость =
distance / time(hour) - Темп:
time(seconds) / distance
Единица измерения расстояния определяется заголовком Accept-Language, указанным в запросе.
Запрашивайте доступ к данным о местоположении заранее
Если ваше приложение составляет маршруты тренировок, запросите разрешение на доступ к данным о местоположении и область действия location Google Health в дополнение к области действия для активности и фитнеса. Объясните пользователям, зачем приложению нужна область действия, связанная с местоположением, при просмотре тренировок с GPS.
Когда приложение запрашивает доступ к области действия, связанной с местоположением (https://www.googleapis.com/auth/googlehealth.location.readonly), Google OAuth показывает пользователю запрос на согласие. Объясните пользователям, что это разрешение необходимо для отрисовки наложений маршрутов и экспорта файлов отслеживания с помощью GPS (TCX). Если пользователь разрешит доступ к данным о физической активности, но запретит доступ к данным о местоположении, exportExerciseTcx вернет ошибку авторизации, но вы по-прежнему сможете получать доступ к агрегированным данным о сеансах в metricsSummary.
Синхронизация с помощью вебхуков
Подпишитесь на тип данных exercise, чтобы получать уведомления о новых данных тренировок с помощью вебхуков. Это позволяет автоматически запускать
действия после тренировки.
Когда ваш сервер получает уведомление вебхука, оно содержит healthUserId и интервал гражданского времени (civilIso8601TimeInterval) обновленной тренировки. Ваш сервер должен немедленно подтвердить получение уведомления, отправив код 204 No Content, асинхронно обработать полезную нагрузку и запросить конечную точку exercise, используя фильтр exercise.interval.civil_start_time (обратите внимание, что exercise поддерживает фильтрацию только по civil_start_time):
GET https://health.googleapis.com/v4/users/healthUserId/dataTypes/exercise/dataPoints:reconcile?filter=exercise.interval.civil_start_time >= "2026-04-20T08:00:00" AND exercise.interval.civil_start_time < "2026-04-20T10:00:00"
Подробнее о том, как настроить подписки на вебхуки…
Поддерживайте стабильные показатели
Чтобы предоставить пользователям полную информацию о тренировке, при записи сеансов exercise включайте сводные показатели и запрашивайте конечные точки телеметрии, доступные только для чтения, используя фильтры диапазона дат при отрисовке подробных диаграмм.
Запись сводных показателей тренировки (путь записи)
При импорте или записи завершенной тренировки в Google Health API включите агрегированные показатели телеметрии тренировки (steps, caloriesKcal, distanceMillimeters, averageHeartRateBeatsPerMinute и averagePaceSecondsPerMeter) в объект metricsSummary элемента данных exercise:
POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Запрос подробных данных для диаграмм (путь чтения)
Чтобы создать панели мониторинга или диаграммы тренировок для определенного занятия, запросите конечные точки согласованной телеметрии для временного окна этой тренировки:
Получите данные о тренировке из конечной точки
exercise, используя фильтрcivil_start_time, чтобы узнать ееintervalиmetricsSummary:GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints:reconcile?filter=exercise.interval.civil_start_time >= "2026-04-20T00:00:00" AND exercise.interval.civil_start_time < "2026-04-21T00:00:00"
Используйте
interval.startTimeиinterval.endTimeсеанса, чтобы запросить конечные точки телеметрии для этого физического временного окна.Если
exerciseMetadata.hasGpsимеет значениеtrue, вызовитеexportExerciseTcx, чтобы скачать координаты маршрута.