Mengembangkan Pengalaman Latihan Fisik dengan Google Health API

Google Health API melacak sesi latihan fisik dan histori olahraga pengguna menggunakan jenis data sesi exercise. Sesi berfungsi sebagai penampung yang menggabungkan metadata aktivitas, peristiwa jeda dan lanjutkan, putaran atau pemisahan, serta metrik ringkasan.

Pahami cara membaca, menulis, dan menyusun olahraga di aplikasi Anda untuk memberikan pengalaman terbaik bagi pengguna.

Jenis data yang didukung

API ini mendukung jenis data berikut untuk melacak sesi olahraga dan aktivitas:

Tabel: Jenis data olahraga Google Health API
Jenis data
  dataType
  filter parameter		 Jenis rekaman
 Operasi yang tersedia
 Cakupan Dukungan
Webhook		 Dukungan nol sebenarnya
Olahraga
  exercise
  exercise 		Sesi list, get, reconcile, create, update, batchDelete activity_and_fitness

Meskipun sesi latihan fisik menggunakan jenis data exercise sebagai penampung, pelacak latihan fisik umum menulis dan membaca telemetri mendetail dan berfrekuensi tinggi selama sesi. Pengukuran ini (seperti detak jantung atau jumlah langkah) harus dibaca atau ditulis menggunakan jenis data masing-masing.

Tabel berikut memetakan kolom di dalam objek metricsSummary dari jenis data exercise ke jenis data telemetri mentah yang sesuai dari Google Health API:

Kolom ringkasan (metricsSummary) Nama jenis data telemetri intraday ID jenis data telemetri API
caloriesKcal Energi Aktif yang Dibakar active-energy-burned
distanceMillimeters Jarak distance
steps Langkah steps
averageHeartRateBeatsPerMinute Detak Jantung heart-rate
activeZoneMinutes Menit Zona Aktif active-zone-minutes

Bagian berikut memberikan detail teknis untuk jenis data exercise, termasuk contoh representasi REST, penanganan rute GPS, dan panduan integrasi.

Sesi latihan fisik

Tulis aktivitas atau olahraga harian sebagai titik data sesi exercise. Setiap titik data menjelaskan sesi keseluruhan, detail interval peristiwa (seperti tindakan jeda dan lanjutkan), serta menyediakan metrik ringkasan (seperti jarak keseluruhan, langkah, dan detak jantung rata-rata).

Atribut sesi

Saat menyusun titik data olahraga, verifikasi komponen inti berikut:

  • Waktu Sesi (interval): Waktu mulai dan waktu berakhir sesi latihan fisik keseluruhan, beserta offset zona waktu yang aktif pada titik tersebut.
  • Jenis Aktivitas (exerciseType): Kategori aktivitas yang dilakukan (seperti RUNNING, WALKING, BIKING, atau AEROBIC_WORKOUT). Tentukan jenis latihan fisik yang tepat.
  • Nama Tampilan (displayName): Nama yang mudah digunakan untuk sesi olahraga (misalnya, "Lari Trail Sore").
  • Durasi Aktif (activeDuration): Waktu aktif sebenarnya dari olahraga, tidak termasuk interval yang dijeda. Pemformatan standar menggunakan format Duration (misalnya, "1800s").

Metrik ringkasan

Objek bertingkat metricsSummary berisi metrik total dan rata-rata yang dihitung selama durasi sesi olahraga:

  • caloriesKcal: Total kalori aktif yang dibakar selama olahraga, diukur dalam kilokalori (kcal).
  • distanceMillimeters: Total jarak yang ditempuh, diukur dalam milimeter untuk mempertahankan presisi tinggi di seluruh unit.
  • steps: Total langkah yang diambil selama olahraga.
  • averageHeartRateBeatsPerMinute: Detak jantung rata-rata pengguna selama menit aktif sesi.
  • activeZoneMinutes: Menit zona aktif kumulatif yang diperoleh selama olahraga.
  • averageSpeedMillimetersPerSecond: Kecepatan gerakan rata-rata dalam milimeter per detik.
  • averagePaceSecondsPerMeter: Pace rata-rata selama menit aktif sesi, diukur dalam detik per meter.
  • elevationGainMillimeters: Total elevasi naik selama sesi.

Putaran dan pemisahan

Untuk olahraga yang melibatkan putaran (seperti lari di lintasan atau berenang di kolam), gunakan splitSummaries.

Setiap pemisahan berisi:

  • startTime dan endTime tertentu.
  • activeDuration yang mewakili waktu putaran sebenarnya.
  • metricsSummary yang hanya dicakup ke segmen tersebut.
  • splitType untuk menentukan batas pemisahan (seperti DISTANCE, DURATION, atau MANUAL).

Peristiwa olahraga

Untuk menghitung durasi aktif secara akurat, lacak transisi status (seperti peristiwa jeda manual atau otomatis) menggunakan exerciseEvents.

Setiap peristiwa berisi stempel waktu (eventTime) dan jenis:

  • START / STOP: Menunjukkan stempel waktu batas saat pengguna secara eksplisit memulai atau menghentikan rekaman.
  • PAUSE / RESUME: Menunjukkan kapan sesi dijeda atau dilanjutkan secara manual.
  • AUTO_PAUSE / AUTO_RESUME: Menunjukkan jeda/lanjut otomatis yang didorong sensor.

Tulis sesi latihan fisik

Untuk membuat, memperbarui, atau mengimpor sesi latihan fisik, tulis titik data ke koleksi jenis data exercise. Gunakan endpoint titik data create.

Contoh representasi REST

Contoh berikut menunjukkan cara menulis sesi olahraga menggunakan metode POST:

Permintaan

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
        }
      }
    ]
  }
}

Respons

{
  "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
          }
        }
      ]
    }
  }
}

Rute GPS dan pelacakan lokasi

API menyimpan ringkasan sesi dasar langsung dalam titik data exercise, tetapi menangani histori lokasi mendetail dan koordinat rute GPS sebagai aliran terpisah.

Untuk mendownload data rute mendetail untuk sesi di luar ruangan, panggil metode kustom exportExerciseTcx. Endpoint ini menampilkan rute dalam format Training Center XML (TCX) standar industri.

Mengekspor rute GPS

Permintaan

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints/exercise-data-point-id:exportExerciseTcx?alt=media
Authorization: Bearer access-token

Respons

Payload HTTP dengan Content-Type: application/tcx+xml dan header yang menginstruksikan browser untuk menyimpan file.

<?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>

Cakupan dan lokasi yang diperlukan

Untuk membaca atau menulis data untuk rute GPS dan pelacakan lokasi, minta cakupan OAuth berikut dalam token akses aplikasi Anda:

  • Akses baca: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • Akses tulis: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
  • Akses baca: https://www.googleapis.com/auth/googlehealth.location.readonly

Jika cakupan yang diperlukan tidak ada di header otorisasi, Google Health API akan menampilkan error otorisasi.

Panduan

Saat mengintegrasikan pelacakan latihan fisik ke dalam aplikasi, ikuti panduan desain dan implementasi ini.

Durasi aktif versus total

Untuk menghitung metrik kecepatan atau pace, selalu gunakan activeDuration, bukan selisih antara startTime dan endTime. Hal ini mencegah interval yang dijeda memiringkan metrik Anda.

Misalnya, jika pengguna memulai latihan fisik pada pukul 08.00 dan selesai pada pukul 08.35, latihan fisik tersebut memiliki total durasi yang berlalu selama 2.100 detik. Jika pengguna menjeda olahraga selama 5 menit (300 detik), tetapkan activeDuration ke "1800s" (2.100 - 300). API menggunakan durasi aktif untuk menghitung rata-rata, membagi total jarak dengan 1.800 detik, bukan 2.100.

Meminta lokasi lebih awal

Jika aplikasi Anda memetakan rute latihan fisik, minta izin akses lokasi dan cakupan location Google Health selain cakupan aktivitas dan kebugaran. Jelaskan kepada pengguna alasan aplikasi Anda memerlukan cakupan lokasi saat meninjau olahraga GPS.

Saat aplikasi Anda meminta cakupan lokasi (https://www.googleapis.com/auth/googlehealth.location.readonly), Google OAuth akan menampilkan perintah izin kepada pengguna. Jelaskan kepada pengguna bahwa izin ini diperlukan untuk merender overlay rute dan mengekspor file trek GPS (TCX). Jika pengguna memberikan cakupan aktivitas, tetapi menolak izin akses lokasi, exportExerciseTcx akan menampilkan error otorisasi, meskipun Anda masih dapat mengakses agregat sesi di metricsSummary.

Sinkronisasi real-time menggunakan webhook

Berlangganan jenis data exercise untuk memberi tahu backend Anda menggunakan webhook saat data olahraga baru tersedia. Hal ini memungkinkan Anda memicu pengalaman pasca-olahraga secara real-time.

Saat server Anda menerima notifikasi webhook, notifikasi tersebut berisi healthUserId dan interval waktu fisik tertentu dari olahraga. Server Anda harus memproses notifikasi secara asinkron, lalu meminta titik data exercise baru dari /users/me/dataTypes/exercise/dataPoints endpoint. Untuk mengetahui detail tentang cara menyiapkan langganan, lihat Langganan webhook.

Mempertahankan metrik yang konsisten

Untuk memberikan pengalaman olahraga yang lengkap, aplikasi Anda harus menyinkronkan titik data telemetri berfrekuensi tinggi bersama dengan sesi exercise keseluruhan. Hal ini memastikan total harian pengguna, tren historis, dan diagram detail tetap sepenuhnya selaras.

Menyinkronkan telemetri dan sesi (jalur tulis)

Saat mengimpor atau menulis latihan fisik yang telah selesai ke Google Health API, terapkan pola tulis multi-langkah:

  1. Menulis sesi: Ajukan peristiwa ringkasan dengan memposting titik data ke POST /users/me/dataTypes/exercise/dataPoints.
  2. Menulis interval deret waktu: Tulis titik data terperinci yang dicatat selama latihan fisik secara serentak (misalnya, langkah per menit atau interval pembakaran kalori) ke koleksi masing-masing:
    • POST /users/me/dataTypes/steps/dataPoints
    • POST /users/me/dataTypes/active-energy-burned/dataPoints
    • POST /users/me/dataTypes/heart-rate/dataPoints

Mengkueri data mendetail untuk diagram (jalur baca)

Saat merender dasbor olahraga historis atau grafik performa untuk sesi olahraga tertentu, kueri telemetri terperinci menggunakan jendela waktu sesi:

  1. Mengkueri ringkasan sesi: Panggil /users/me/dataTypes/exercise/dataPoints untuk mengambil detail latihan fisik keseluruhan dan metricsSummary akhir.
  2. Mengambil metrik diagram: Periksa interval.startTime dan interval.endTime olahraga. Lakukan panggilan GET sekunder ke koleksi telemetri untuk jendela waktu tertentu tersebut:
    • GET /users/me/dataTypes/heart-rate/dataPoints?startTime=2026-04-20T08:00:00Z&endTime=2026-04-20T08:35:00Z
  3. Mengambil rute GPS: Jika metadata sesi menunjukkan bahwa data GPS ada (exerciseMetadata.hasGps adalah true), panggil metode helper exportExerciseTcx untuk mendownload koordinat rute.
Sebelumnya
Kalori dan energi