Interfejs Google Health API śledzi sesje treningowe i historię ćwiczeń użytkownika, korzystając z typu danych sesji exercise. Sesja działa jak kontener, który grupuje metadane aktywności, zdarzenia wstrzymania i wznowienia, okrążenia lub odcinki oraz dane podsumowujące.
Dowiedz się, jak odczytywać, zapisywać i strukturyzować treningi w aplikacji, aby zapewnić użytkownikom jak najlepsze wrażenia.
Obsługiwane typy danych
Interfejs API obsługuje ten typ danych do śledzenia treningów i sesji aktywności:
| Typ danych | Dostępne operacje |
Zakres |
|---|---|---|
|
Ćwiczenia
dataType:
exercisefilter parameter: exercise
Typ rekordu: sesja
Zgodne urządzenia
|
list, get, reconcile, create, update, batchDelete | .activity_and_fitness.readonly.activity_and_fitness.writeonly |
Powiązane typy danych telemetrycznych
Sesje treningowe używają typu danych exercise jako kontenera, ale urządzenia do noszenia rejestrują też podczas sesji szczegółowe dane telemetryczne o wysokiej częstotliwości. W interfejsie Google Health API te szczegółowe typy danych telemetrycznych z całego dnia są tylko do odczytu i nie można ich tworzyć ani modyfikować bezpośrednio za pomocą ich własnych punktów końcowych REST.
Podczas zapisywania sesji treningowej za pomocą interfejsu REST API przekazuj zbiorcze dane treningowe w obiekcie metricsSummary punktu danych exercise.
W tabeli poniżej znajdziesz mapowanie pól podsumowania w exercise.metricsSummary na odpowiadające im dane telemetryczne z danego dnia, które są tylko do odczytu i które możesz wyszukiwać w przedziale czasu danego treningu:
Pole podsumowania (metricsSummary) |
Nazwa typu danych telemetrycznych zbieranych w ciągu dnia | Identyfikator typu danych telemetrycznych interfejsu API (tylko do odczytu) | Pole filtra (?filter=) |
Wymagany zakres protokołu OAuth do odczytu |
|---|---|---|---|---|
caloriesKcal |
Kalorie spalone aktywnie | active-energy-burned |
active_energy_burned.interval.start_time |
activity_and_fitness.readonly |
distanceMillimeters |
Odległość | distance |
distance.interval.start_time |
activity_and_fitness.readonly |
steps |
Kroki | steps |
steps.interval.start_time |
activity_and_fitness.readonly |
averageHeartRateBeatsPerMinute |
tętno | heart-rate |
heart_rate.sample_time.physical_time |
health_metrics_and_measurements.readonly |
activeZoneMinutes |
Aktywne minuty w strefie | active-zone-minutes |
active_zone_minutes.interval.start_time |
activity_and_fitness.readonly |
W poniższych sekcjach znajdziesz szczegóły techniczne dotyczące typu danych exercise, w tym przykłady reprezentacji REST, obsługę tras GPS i wytyczne dotyczące integracji.
Sesje treningowe
Zapisuj codzienne aktywności lub treningi jako punkty danych sesji exercise. Każdy punkt danych opisuje całą sesję, zawiera szczegółowe informacje o interwałach zdarzeń (takich jak wstrzymanie i wznowienie) oraz podaje dane podsumowujące (takie jak łączny dystans, liczba kroków i średnie tętno).
Atrybuty sesji
Podczas tworzenia punktu danych dotyczących ćwiczeń sprawdź te podstawowe komponenty:
- Czas sesji (
interval): czas rozpoczęcia i zakończenia całej sesji treningowej wraz z przesunięciami strefy czasowej aktywnymi w tych momentach. - Typ aktywności (
exerciseType): kategoria wykonywanej aktywności (np.RUNNING,WALKING,BIKINGlubAEROBIC_WORKOUT). Określ dokładny typ treningu fizycznego. - Wyświetlana nazwa (
displayName): przyjazna dla użytkownika nazwa sesji treningowej. Gdy utworzysz go za pomocą interfejsu API REST, serwer wypełni zlokalizowaną wyświetlaną nazwę dlaexerciseType, np."Run"dlaRUNNING. - Czas aktywności (
activeDuration): rzeczywisty czas aktywności podczas treningu, z wyłączeniem wstrzymanych interwałów. Standardowe formatowanie używa formatuDuration(np."1800s"). Na serwerzeactiveDurationjest obliczany na podstawieintervalsesji pomniejszonego o interwałyPAUSE/RESUMElubAUTO_PAUSE/AUTO_RESUMEwexerciseEvents.
Wskaźniki podsumowujące
Zagnieżdżony obiekt metricsSummary zawiera dane sumaryczne i średnie obliczone dla całego czasu trwania sesji ćwiczeń:
caloriesKcal: łączna liczba aktywnych spalonych kalorii podczas treningu, mierzona w kilokaloriach (kcal).distanceMillimeters: łączny pokonany dystans mierzony w milimetrach, aby zachować wysoką precyzję we wszystkich jednostkach.steps: łączna liczba kroków zrobionych podczas ćwiczenia.averageHeartRateBeatsPerMinute: średnie tętno użytkownika podczas aktywnych minut sesji.activeZoneMinutes: łączne aktywne minuty w strefie zdobyte podczas treningu.averageSpeedMillimetersPerSecond: średnia szybkość ruchu w milimetrach na sekundę.averagePaceSecondsPerMeter: średnie tempo podczas aktywnych minut sesji, mierzone w sekundach na metr.elevationGainMillimeters: łączne przebyte przewyższenie podczas sesji.
Etapy i odcinki
W przypadku treningów obejmujących okrążenia (takich jak bieganie na bieżni czy pływanie w basenie) zsynchronizowanych z obsługiwanych urządzeń splitSummaries dzieli sesję na okrążenia lub odcinki.
Każdy podział zawiera:
- Określony
startTimeiendTime. activeDurationreprezentujący rzeczywisty czas okrążenia.metricsSummary, którego zakres jest ograniczony tylko do tego segmentu.splitType, aby określić granice podziału (np.DISTANCE,DURATIONlubMANUAL).
ćwiczenia,
Aby dokładnie obliczyć czas aktywności, śledź zmiany stanu (np. zdarzenia ręcznego lub automatycznego wstrzymania) za pomocą exerciseEvents.
Każde zdarzenie zawiera sygnaturę czasową (eventTime) i typ:
START/STOP: wskazuje sygnatury czasowe rozpoczęcia lub zakończenia nagrywania przez użytkownika.PAUSE/RESUME: wskazuje, kiedy sesja została ręcznie wstrzymana lub wznowiona.AUTO_PAUSE/AUTO_RESUME: wskazuje automatyczne wstrzymanie/wznowienie na podstawie danych z czujników.
Zapisywanie sesji treningowej
Aby utworzyć, zaktualizować lub zaimportować sesję treningową, zapisz punkt danych w kolekcji typu danych exercise. Użyj punktu końcowego create dataPoints.
Przykład reprezentacji REST
Poniższy przykład pokazuje, jak zapisać sesję treningową za pomocą metody POST:
Żądanie
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"
}
]
}
}Odpowiedź
{
"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"
}
}
}Trasy GPS i śledzenie lokalizacji
Interfejs API zapisuje podstawowe podsumowania sesji bezpośrednio w punkcie danych exercise, ale szczegółową historię lokalizacji i współrzędne trasy GPS obsługuje jako osobny strumień.
Aby pobrać szczegółowe dane o trasie sesji na świeżym powietrzu, wywołaj metodę niestandardową exportExerciseTcx. Ten punkt końcowy zwraca trasę w standardowym formacie Training Center XML (TCX).
Eksportowanie trasy GPS
Żądanie
GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints/exercise-data-point-id:exportExerciseTcx?alt=media Authorization: Bearer access-token
Odpowiedź
Ładunek HTTP z Content-Type: application/tcx+xml i nagłówkami, które instruują przeglądarkę, aby zapisała plik.
<?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>Wymagane zakresy i lokalizacja
Aby korzystać z funkcji śledzenia tras GPS i lokalizacji, aplikacja musi prosić o te zakresy OAuth:
- Odczyt:
https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly - Zapis:
https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly - Odczyt:
https://www.googleapis.com/auth/googlehealth.location.readonly
Wytyczne
Podczas integrowania śledzenia treningów z aplikacją postępuj zgodnie z tymi wytycznymi dotyczącymi projektowania i wdrażania.
Czas aktywności a łączny czas trwania
Aby obliczyć dane dotyczące szybkości lub tempa, zawsze używaj activeDuration, a nie różnicy między startTime i endTime. Zapobiega to zniekształcaniu danych
przez wstrzymane interwały.
Jeśli na przykład użytkownik rozpocznie trening o 8:00 i zakończy go o 8:35, łączny czas trwania treningu wyniesie 2100 sekund. Jeśli użytkownik wstrzymał trening na 5 minut (300 sekund), a w exerciseEvents uwzględnisz zdarzenia PAUSE i RESUME, czas aktywności wyniesie "1800s" (2100 – 300). Interfejs API używa aktywnego czasu trwania do obliczania średnich, dzieląc łączny dystans przez 1800 sekund zamiast przez 2100.
Obliczanie prędkości i tempa
Interfejs Google Health API oblicza prędkość i tempo za pomocą standardowych wzorów:
- Prędkość =
distance / time(hour) - Tempo =
time(seconds) / distance
Nagłówek Accept-Language określony w żądaniu określa jednostkę odległości.
Wcześniejsze wysyłanie prośby o dostęp do lokalizacji
Jeśli Twoja aplikacja mapuje trasy treningowe, poproś o uprawnienia dostępu do lokalizacji i zakres Google Health location oprócz zakresu aktywności i kondycji. Wyjaśnij użytkownikom, dlaczego Twoja aplikacja wymaga zakresu lokalizacji podczas sprawdzania ćwiczeń z GPS-em.
Gdy aplikacja prosi o zakres lokalizacji (https://www.googleapis.com/auth/googlehealth.location.readonly), Google OAuth wyświetla użytkownikowi prośbę o zgodę. Wyjaśnij użytkownikom, że to uprawnienie jest niezbędne do renderowania nakładek tras i eksportowania plików śledzenia GPS (TCX). Jeśli użytkownik przyzna uprawnienia do aktywności, ale odmówi dostępu do lokalizacji, exportExerciseTcx zwróci błąd autoryzacji, ale nadal będziesz mieć dostęp do danych zbiorczych sesji w metricsSummary.
Synchronizacja za pomocą webhooków
Zasubskrybuj typ danych exercise, aby powiadamiać backend za pomocą webhooków, gdy pojawią się nowe dane dotyczące treningu. Dzięki temu możesz automatycznie
wywoływać działania po treningu.
Gdy serwer otrzyma powiadomienie webhooka, zawiera ono identyfikator healthUserId i przedział czasu cywilnego (civilIso8601TimeInterval) zaktualizowanego treningu. Serwer powinien natychmiast potwierdzić powiadomienie za pomocą 204 No Content, przetworzyć ładunek asynchronicznie i wysłać zapytanie do uzgodnionego punktu końcowego exercise za pomocą filtra exercise.interval.civil_start_time (pamiętaj, że exercise obsługuje tylko filtrowanie według 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"
Szczegółowe informacje o konfigurowaniu subskrypcji znajdziesz w artykule Subskrypcje webhooków.
Utrzymywanie spójnych danych
Aby zapewnić pełne informacje o treningu, podczas zapisywania sesji exercise uwzględniaj dane podsumowujące, a podczas renderowania wykresów szczegółowych wysyłaj zapytania do punktów końcowych telemetrii tylko do odczytu, używając filtrów zakresu czasu.
Zapisywanie danych podsumowania treningu (ścieżka zapisu)
Podczas importowania lub zapisywania ukończonego treningu w interfejsie Google Health API uwzględnij zbiorcze dane telemetryczne treningu (steps, caloriesKcal, distanceMillimeters, averageHeartRateBeatsPerMinute i averagePaceSecondsPerMeter) w obiekcie metricsSummary punktu danych exercise:
POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
wykonywanie zapytań o szczegółowe dane na potrzeby wykresów (ścieżka odczytu),
Aby utworzyć panele lub wykresy treningu dla konkretnej sesji, wyślij zapytanie do uzgodnionych punktów końcowych telemetrii w przedziale czasu tego treningu:
Pobierz sesję treningową z punktu końcowego
exercise, używając filtracivil_start_time, aby uzyskać wartościintervalimetricsSummary: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"
Użyj wartości
interval.startTimeiinterval.endTimesesji, aby wysłać zapytanie do punktów końcowych telemetrii w tym przedziale czasu.Jeśli
exerciseMetadata.hasGpstotrue, wywołajexportExerciseTcx, aby pobrać współrzędne trasy.