Эта страница переведена с помощью Cloud Translation API.

Разрабатывайте приложения для тренировок с использованием API Google Health.

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

Разберитесь, как читать, записывать и структурировать тренировки в вашем приложении, чтобы обеспечить наилучший пользовательский опыт.

Поддерживаемые типы данных

API поддерживает следующие типы данных для отслеживания тренировок и сеансов активности:

*Таблица: Типы данных о тренировках в Google Health API*
Тип данных `dataType` параметр `filter`	Записывать тип	Доступный операции	Объем	Вебхук поддерживать	Истинные нули поддерживать
Упражнение `exercise` `exercise`	Сессия	список, получить, согласовать, создать, обновить, пакетное удаление	активность_и_фитнес

Связанные типы телеметрических данных

В то время как данные о тренировках используются в качестве контейнера для информации exercise , обычные фитнес-трекеры записывают и считывают подробные высокочастотные телеметрические данные во время тренировки. Эти измерения (такие как частота сердечных сокращений или количество шагов) должны считываться или записываться с использованием соответствующих типов данных.

В следующей таблице показано соответствие полей объекта metricsSummary типа данных exercise соответствующим типам необработанных телеметрических данных API Google Health:

Поле сводки ( `metricsSummary` )	Название типа данных внутридневной телеметрии	Тип данных телеметрии API ID
`caloriesKcal`	Сожженная активная энергия	`active-energy-burned`
`distanceMillimeters`	Расстояние	`distance`
`steps`	Шаги	`steps`
`averageHeartRateBeatsPerMinute`	Частота сердечных сокращений	`heart-rate`
`activeZoneMinutes`	Минуты активной зоны	`active-zone-minutes`

В следующих разделах представлены технические подробности о типе данных exercise , включая примеры представления в REST-формате, обработку маршрутов GPS и рекомендации по интеграции.

Тренировочные сессии

Записывайте ежедневные данные о тренировках или занятиях в виде exercise точек данных. Каждая точка данных описывает всю тренировку в целом, подробно описывает интервалы событий (например, пауза и возобновление) и предоставляет сводные показатели (например, общее расстояние, количество шагов и средняя частота сердечных сокращений).

Атрибуты сессии

При структурировании данных об упражнении необходимо проверить следующие основные компоненты:

Время сессии ( interval ) : время начала и окончания всей тренировочной сессии, а также смещение часовых поясов, действующее в эти моменты времени.
Тип активности ( exerciseType ) : Категория выполняемой активности (например, RUNNING , WALKING , BIKING или AEROBIC_WORKOUT ). Укажите точный тип физической тренировки.
Отображаемое имя ( displayName ) : Удобное для пользователя название для тренировочной сессии (например, "Дневной бег по пересеченной местности").
Активная продолжительность ( activeDuration ) : фактическое время активной тренировки, за исключением интервалов паузы. Стандартный формат использует формат Duration (например, "1800s" ).

Сводные показатели

Вложенный объект 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 точек данных.

Пример представления 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"
  },
  "exercise": {
    "interval": {
      "startTime": "2026-04-20T08:00:00Z",
      "startUtcOffset": "0s",
      "endTime": "2026-04-20T08:35:00Z",
      "endUtcOffset": "0s"
    },
    "exerciseType": "RUNNING",
    "displayName": "Morning Trail Run",
    "activeDuration": "1800s",
    "metricsSummary": {
      "caloriesKcal": 380.0,
      "distanceMillimeters": 5000000.0,
      "steps": "6200",
      "averageSpeedMillimetersPerSecond": 2777.78,
      "averagePaceSecondsPerMeter": 360.0,
      "averageHeartRateBeatsPerMinute": "148",
      "activeZoneMinutes": "30"
    },
    "exerciseMetadata": {
      "hasGps": true
    },
    "exerciseEvents": [
      {
        "eventTime": "2026-04-20T08:15:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "PAUSE"
      },
      {
        "eventTime": "2026-04-20T08:20:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "RESUME"
      }
    ],
    "splitSummaries": [
      {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:15:00Z",
        "endUtcOffset": "0s",
        "splitType": "DISTANCE",
        "metricsSummary": {
          "distanceMillimeters": 2500000.0,
          "caloriesKcal": 190.0
        }
      }
    ]
  }
}

Ответ

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
    "name": "users/me/dataTypes/exercise/dataPoints/morning-trail-run-123456",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "application": {
        "packageName": "com.example.workoutapp"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "exercise": {
      "interval": {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:35:00Z",
        "endUtcOffset": "0s"
      },
      "exerciseType": "RUNNING",
      "displayName": "Morning Trail Run",
      "activeDuration": "1800s",
      "metricsSummary": {
        "caloriesKcal": 380.0,
        "distanceMillimeters": 5000000.0,
        "steps": "6200",
        "averageSpeedMillimetersPerSecond": 2777.78,
        "averagePaceSecondsPerMeter": 360.0,
        "averageHeartRateBeatsPerMinute": "148",
        "activeZoneMinutes": "30"
      },
      "exerciseMetadata": {
        "hasGps": true
      },
      "exerciseEvents": [
        {
          "eventTime": "2026-04-20T08:15:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "PAUSE"
        },
        {
          "eventTime": "2026-04-20T08:20:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "RESUME"
        }
      ],
      "splitSummaries": [
        {
          "startTime": "2026-04-20T08:00:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-04-20T08:15:00Z",
          "endUtcOffset": "0s",
          "activeDuration": "900s",
          "splitType": "DISTANCE",
          "metricsSummary": {
            "distanceMillimeters": 2500000.0,
            "caloriesKcal": 190.0
          }
        }
      ]
    }
  }
}

Отслеживание маршрутов и местоположения с помощью 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

Если в заголовках авторизации отсутствует необходимая область действия, API Google Health возвращает ошибку авторизации.

Руководящие принципы

При интеграции функции отслеживания тренировок в ваше приложение следуйте этим рекомендациям по проектированию и внедрению.

Активная продолжительность против общей продолжительности

Для расчета показателей скорости или темпа всегда используйте activeDuration , а не разницу между startTime и endTime . Это предотвратит искажение показателей из-за пауз во время тренировок.

Например, если пользователь начинает тренировку в 08:00 и заканчивает в 08:35, общая продолжительность тренировки составляет 2100 секунд. Если пользователь приостановил тренировку на 5 минут (300 секунд), установите activeDuration равным "1800s" (2100 - 300). API использует activeDuration для расчета средних значений, деля общее расстояние на 1800 секунд вместо 2100.

Уточните местоположение заранее.

Если ваше приложение прокладывает маршруты для тренировок, запросите разрешения на определение местоположения и доступ location Google Health в дополнение к разрешению на отслеживание активности и фитнеса. Объясните пользователям, почему вашему приложению требуется доступ к данным о местоположении, при обзоре тренировок с использованием GPS.

Когда ваше приложение запрашивает доступ к местоположению ( https://www.googleapis.com/auth/googlehealth.location.readonly ), Google OAuth отображает пользователю запрос на подтверждение. Объясните пользователям, что это разрешение необходимо для отображения маршрутных наложений и экспорта файлов GPS-треков (TCX). Если пользователь предоставляет доступ к активности, но отказывает в доступе к местоположению, exportExerciseTcx возвращает ошибку авторизации, хотя вы по-прежнему можете получить доступ к сводным данным сессии в metricsSummary .

Синхронизация в реальном времени с использованием веб-хуков.

Подпишитесь на тип данных exercise , чтобы с помощью веб-хуков уведомлять вашу бэкэнд-систему о появлении новых данных о тренировках. Это позволит вам запускать действия после тренировки в режиме реального времени.

Когда ваш сервер получает уведомление через веб-перехватчик, оно содержит healthUserId и конкретный физический временной интервал тренировки. Ваш сервер должен обработать уведомление асинхронно, а затем запросить новую точку данных exercise у конечной точки /users/me/dataTypes/exercise/dataPoints . Подробную информацию о настройке подписок см. в разделе «Подписки на веб-перехватчики» .

Поддерживайте согласованные показатели.

Для обеспечения полноценной тренировки ваше приложение должно синхронизировать высокочастотные телеметрические данные с общей exercise . Это гарантирует полную согласованность ежедневных показателей пользователя, исторических тенденций и подробных графиков.

Синхронизация телеметрии и сессий (путь записи)

При импорте или записи завершенной тренировки в API Google Health используйте многоэтапный шаблон записи:

Запись сессии : Сводная информация о событии формируется путем отправки точки данных по адресу POST /users/me/dataTypes/exercise/dataPoints .
Запись временных рядов : Одновременно записывайте подробные данные, регистрируемые во время тренировки (например, количество шагов поминутно или интервалы сжигания калорий), в соответствующие коллекции:
- POST /users/me/dataTypes/steps/dataPoints
- POST /users/me/dataTypes/active-energy-burned/dataPoints
- POST /users/me/dataTypes/heart-rate/dataPoints

Запрос подробных данных для диаграмм (путь чтения)

При построении панелей мониторинга истории тренировок или графиков производительности для конкретной тренировочной сессии, запросите подробные телеметрические данные, используя временной интервал сессии:

Запрос сводных данных сессии : вызовите /users/me/dataTypes/exercise/dataPoints чтобы получить общие сведения о тренировке и итоговые metricsSummary .
Получение метрик графика : проверьте interval.startTime и interval.endTime тренировки. Выполните дополнительные GET запросы к коллекциям телеметрии для этого конкретного временного интервала:
- GET /users/me/dataTypes/heart-rate/dataPoints?startTime=2026-04-20T08:00:00Z&endTime=2026-04-20T08:35:00Z
Получение GPS-маршрутов : Если метаданные сессии указывают на наличие GPS-данных ( exerciseMetadata.hasGps равно true ), вызовите вспомогательный метод exportExerciseTcx для загрузки координат маршрута.

Калории и энергия