Spesifikasi API

Bagian Spesifikasi API memberikan ringkasan mendetail tentang komponen teknis yang penting untuk diintegrasikan dengan platform, termasuk cakupan otorisasi, definisi jenis data, dan struktur endpoint. API ini mewakili evolusi strategis Fitbit Web API lama, yang dibangun kembali di infrastruktur modern untuk memastikan pengalaman developer yang lebih stabil dan konsisten.

Cakupan

Anda harus memperbarui permintaan otorisasi untuk menggunakan cakupan Google Health API. Cakupan menentukan apakah aplikasi Anda mendukung operasi baca atau tulis. Ikuti petunjuk penerapan cakupan, yang menentukan hanya meminta cakupan yang diperlukan, mengonfigurasi akses tulis hanya saat mengirim data, dan menangani izin parsial dengan baik.

Cakupan Google Health API adalah URL HTTP yang diawali dengan https://www.googleapis.com/auth/googlehealth.{scope}. Misalnya, https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly.

Pemetaan cakupan

Berikut cara cakupan Fitbit Web API dipetakan ke cakupan Google Health API:

Tabel: Pemetaan cakupan Fitbit Web API ke Google Health API
Cakupan Fitbit Web API Cakupan Google Health API
aktivitas .activity_and_fitness.readonly
.activity_and_fitness.writeonly
blood_glucose .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
cardio_fitness .activity_and_fitness.readonly
.activity_and_fitness.writeonly
elektrokardiogram .ecg.readonly
detak jantung .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
irregular_rhythm_notifications .irn.readonly
lokasi .location.readonly
gizi .nutrition.readonly
.nutrition.writeonly
oxygen_saturation .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
profil .profile.readonly
.profile.writeonly
respiratory_rate .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
setelan .settings.readonly
.settings.writeonly
sleep .sleep.readonly
.sleep.writeonly
suhu .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
bobot .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly

Jenis data

Berikut daftar jenis data Google Health API dan cara pemetaannya ke Fitbit Web API.

Tabel: Pemetaan jenis data Fitbit Web API ke Google Health API
Jenis Data Fitbit Web API Jenis Data Google Health API
  dataType		 Deskripsi
Kalori Aktivitas Energi Aktif yang Terbakar
  active-energy-burned 		Menunjukkan kalori terbakar selama periode aktif, termasuk BMR untuk periode tersebut. Di Google Health API, hal ini dapat direkonstruksi dengan menambahkan BMR ke jenis data active-energy-burned (yang melacak pembakaran khusus aktivitas, tidak termasuk laju basal).
Menit Zona Aktif Menit Zona Aktif
  active-zone-minutes
Berisi perubahan pada tingkat aktivitas pengguna Tingkat Aktivitas
  activity-level 		Merekam tingkat aktivitas pengguna (seperti tidak banyak bergerak atau aktif) selama jangka waktu tertentu.
Elevasi Ketinggian
  altitude
Aktivitas caloriesBMR Energi Basal yang Terbakar
  basal-energy-burned 		Kalori yang terbakar karena Laju Metabolisme Basal (BMR) selama jangka waktu tertentu.
Gula Darah Glukosa Darah
  blood-glucose
Lemak tubuh Lemak Tubuh
  body-fat
caloriesOut di setiap zona detak jantung Kalori dalam Zona Detak Jantung
  calories-in-heart-rate-zone
Suhu (Inti) Suhu Tubuh Inti
  core-body-temperature
Ringkasan HRV Variabilitas Detak Jantung Harian
  daily-heart-rate-variability
Ringkasan SpO2 Saturasi Oksigen Harian
  daily-oxygen-saturation 		Ringkasan harian statistik saturasi oksigen dalam darah (SpO2) yang dihitung dari pengukuran tidur yang divalidasi.
Detak jantung saat istirahat Detak Jantung Saat Istirahat Harian
  daily-resting-heart-rate
Suhu kulit Deviasi Suhu Tidur Harian
  daily-sleep-temperature-derivations
Jarak Jarak
  distance
Elektrokardiogram (EKG) Elektrokardiogram (EKG)
  electrocardiogram
Aktivitas yang direkam Latihan
  exercise 		Sesi olahraga atau latihan yang direkam, yang mencakup waktu mulai/berakhir, jenis aktivitas, dan metrik sesi.
Lantai Lantai
  floors
Makanan Makanan
  food
Unit Pengukuran Makanan Unit Pengukuran Makanan
  food-measurement-unit
Detak Jantung Detak Jantung
  heart-rate
HRV Intrahari Variabilitas Detak Jantung
  heart-rate-variability
Notifikasi Irama Tidak Teratur (IRN) Notifikasi Irama Tidak Teratur
  irregular-rhythm-notification
Catatan Makanan Log Nutrisi
  nutrition-log
SpO2 Intrahari Saturasi Oksigen
  oxygen-saturation 		Hanya menampilkan pengukuran SpO2 tingkat menit yang divalidasi dan mengecualikan pembacaan yang ditandai sebagai tidak valid karena artefak gerakan atau keyakinan sensor yang rendah. Karena Fitbit Web API hanya mengecualikan nilai sentinel 50%, Google Health API menampilkan lebih sedikit titik data untuk rentang waktu yang sama. Untuk mengetahui detailnya, lihat Pemfilteran saturasi oksigen.
Nilai VO2 Maks saat pengguna berlari VO2 Maks Lari
  run-vo2-max
Menit tidak bergerak dalam deret waktu aktivitas Periode Tidak Aktif
  sedentary-period
Tidur Tidur
  sleep
Langkah Langkah
  steps
Deret waktu aktivitas gaya renang Data Panjang Lintasan Renang
  swim-lengths-data
Aktivitas caloriesOut Total Kalori
  total-calories 		Jumlah total kalori yang dibakar oleh pengguna selama jangka waktu tertentu, termasuk laju metabolisme basal dan energi aktif yang dibakar.
Nilai VO2 Maks VO2 Maks
  vo2-max
Berat Berat
  weight

Penghitungan

Pemetaan dan aturan di Google Health API berbeda dengan Fitbit Web API.

Pemfilteran saturasi oksigen

Saat membuat kueri saturasi oksigen dalam darah (oxygen-saturation) tingkat menit, Google Health API menerapkan pemfilteran validitas data yang lebih ketat daripada Fitbit Web API lama:

  • Fitbit Web API lama (v1 dan v3) hanya mengecualikan sampel SpO2 dengan nilai sentinel 50%.
  • Google Health API (v4) mengecualikan semua sampel SpO2 yang ditandai sebagai tidak valid oleh algoritma validasi. Satu menit ditandai sebagai tidak valid jika gerakan lengan atau pemasangan yang longgar di pergelangan tangan membuat sinyal sensor optik tidak dapat diandalkan, jika skor keyakinan turun di bawah 50%, selama 3 menit sebelum dan sesudah pembacaan yang tidak valid, atau jika rentang yang valid berlangsung kurang dari 4 menit berturut-turut.

Karena Google Health API menghapus semua pengukuran yang tidak valid, bukan hanya nilai sentinel 50%, API ini menampilkan lebih sedikit titik data oxygen-saturation daripada Fitbit Web API untuk rentang waktu yang sama, dan diperkirakan akan ada kesenjangan dalam cakupan menit demi menit. Pembacaan tingkat menit yang ditampilkan selaras dengan titik data tervalidasi yang digunakan untuk menghitung ringkasan data tidur daily-oxygen-saturation pengguna. Untuk mengetahui informasi selengkapnya, lihat Pemfilteran SpO2 tingkat menit dan validitas data.

Tingkat aktivitas, MET, dan batas langkah

Di Google Health API, tingkat aktivitas pengguna dari menit ke menit diperoleh dari Metabolic Equivalent of Task (MET) dan jumlah langkahnya.

Tingkat aktivitas Perangkat detak jantung Perangkat tanpa detak jantung
Sedentari ≤ 1,5 MET ≤ 1,5 MET
Aktif Ringan > 1,5 MET dan ≤ 4,2 MET > 1,5 MET dan ≤ 3,5 MET
Cukup Aktif > 4,2 MET dan < 6,0 MET
(kecuali jika kondisi untuk Sangat Aktif terpenuhi)		 > 3,5 MET dan < 6,0 MET
(kecuali jika kondisi untuk Sangat Aktif terpenuhi)
Sangat Aktif ≥ 6,0 MET, atau ≥ 5,0 MET dengan kecepatan langkah 150 langkah per menit atau lebih ≥ 6,0 MET, atau ≥ 5,0 MET dengan kecepatan langkah 150 langkah per menit atau lebih

Menit aktif terdiri dari gabungan menit MODERATELY_ACTIVE dan VERY_ACTIVE. Namun, menit sangat aktif hanya dikreditkan jika terjadi selama streak berkelanjutan minimal 10 menit, dengan jeda aktivitas yang lebih rendah maksimal 2 menit.

Menit tidak bergerak dan tidur

Menit tidak aktif tidak termasuk waktu tidur. Dalam penggabungan harian, menit tidak aktif dihitung dengan mengurangi menit tidur dan menit aktif (sedikit aktif, cukup aktif, dan sangat aktif) dari total menit dalam sehari (1.440 menit):

Sedentary Minutes = 1440 - Sleep Minutes - Lightly Active Minutes - Moderately Active Minutes - Very Active Minutes

Indeks Massa Tubuh (BMI)

Karena Google Health API tidak mengekspos jenis data BMI bawaan, aplikasi harus menghitung Indeks Massa Tubuh di sisi klien menggunakan data tinggi dan berat badan:

  1. Ambil berat pengguna dalam gram dari kolom weightGrams dalam jenis data Berat. Konversikan ke kilogram (bagi dengan 1.000) atau pound (bagi dengan 453,59237).
  2. Ambil tinggi pengguna dalam milimeter dari kolom heightMillimeters dalam jenis data Tinggi. Konversikan nilai ini ke meter (bagi dengan 1.000) atau inci (bagi dengan 25,4).
  3. Gunakan salah satu formula berikut untuk menghitung nilai BMI:
    • Formula metrik: BMI = weight (kg) / [height (m)]^2
    • Formula imperial: BMI = (weight (lbs) / [height (in)]^2) * 703

Nilai BMI yang dihasilkan sesuai dengan kategori berikut:

Kategori berat badan Rentang BMI
Kurang berat Di bawah 18,5
Berat badan sehat 18,5 hingga 24,9
Kelebihan berat badan 25 hingga 29,9
Obesitas 30 atau lebih tinggi

Laju Metabolisme Basal (BMR)

Laju Metabolisme Basal (BMR) adalah jumlah kalori minimum yang diperlukan untuk fungsi dasar tubuh saat istirahat. Karena Google Health API tidak mengekspos jenis data BMR bawaan, aplikasi harus menghitungnya di sisi klien menggunakan formula Harris-Benedict. Lihat artikel persamaan Harris–Benedict di Wikipedia untuk mempelajari lebih lanjut.

Untuk melakukan penghitungan ini:

  1. Ambil berat pengguna dalam gram dari kolom weightGrams dalam jenis data Berat dan konversikan ke kilogram (bagi dengan 1.000). Untuk mengonversi pound ke kilogram, bagi dengan 2,2.
  2. Ambil tinggi pengguna dalam milimeter dari kolom heightMillimeters dalam jenis data Tinggi dan konversikan ke sentimeter (bagi dengan 10). Untuk mengonversi inci ke sentimeter, kalikan dengan 2,54.
  3. Ambil usia pengguna dalam satuan tahun dari kolom age di resource Profile.
  4. Ambil jenis kelamin biologis secara independen (misalnya, dengan meminta pengguna atau menyimpannya di database Anda sendiri), karena Google Health API tidak mengekspos kolom ini.
  5. Gunakan salah satu formula berikut berdasarkan jenis kelamin biologis pengguna:
    • Pria: BMR = 66 + (13.7 x weight_kg) + (5 x height_cm) - (6.8 x age_years)
    • Perempuan: BMR = 655 + (9.6 x weight_kg) + (1.8 x height_cm) - (4.7 x age_years)

Total Pengeluaran Energi Harian (TDEE)

Total Pengeluaran Energi Harian (TDEE) adalah estimasi jumlah total kalori yang dibakar seseorang dalam sehari, yang memperhitungkan BMR dan aktivitas fisik. Untuk memperkirakan TDEE pengguna, kalikan nilai BMR dengan faktor aktivitas yang sesuai dengan gaya hidup mereka:

Tingkat aktivitas Deskripsi Pengganda
Sedentari Sedikit atau tidak berolahraga. BMR x 1.2
Sedikit aktif Latihan 1–3 hari per minggu. BMR x 1.375
Cukup aktif 3–5 hari latihan per minggu. BMR x 1.55
Sangat aktif 6–7 hari latihan per minggu. BMR x 1.725
Sangat aktif Latihan atau pekerjaan fisik yang sangat berat. BMR x 1.9

Endpoint

Endpoint REST mengadopsi sintaksis yang konsisten untuk semua jenis data.

  • Endpoint Layanan: URL HTTP dasar berubah menjadi https://health.googleapis.com.
  • Sintaksis Endpoint: Google Health API mendukung sejumlah endpoint terbatas, yang dapat digunakan oleh sebagian besar jenis data yang didukung. Hal ini memberikan sintaksis yang konsisten untuk semua jenis data dan membuat endpoint lebih mudah digunakan.
  • ID Pengguna: ID pengguna atau me harus ditentukan dalam sintaksis endpoint. Saat menggunakan me, ID pengguna disimpulkan dari token akses.

Contoh: Berikut contoh endpoint GET Profile yang dipanggil menggunakan Google Health API

GET https://health.googleapis.com/v4/users/me/profile

Pemetaan endpoint

Lihat tabel jenis data Google Health API untuk mengetahui daftar jenis data yang tersedia dan metode API yang didukung.

Jenis Endpoint Fitbit Web API Google Health API
GET (Log | Ringkasan | Ringkasan Harian) tempat Anda meminta data satu hari Metode dailyRollup dengan windowSize = 1 hari
GET (Intraday) tempat Anda meminta data terperinci Metode list
GET (Deret Waktu) menurut Tanggal atau Interval Metode rollUp atau dailyRollUp yang menyertakan rentang tanggal
GET (Daftar Log) Metode list
Log CREATE & UPDATE Metode patch
HAPUS Log Metode batchDelete
GET Profile users.getProfile menampilkan informasi spesifik pengguna
users.getSettings menampilkan unit dan zona waktu pengguna
Memperbarui Profil users.updateProfile mengubah informasi spesifik pengguna
users.updateSettings mengubah unit dan zona waktu pengguna
Mendapatkan ID Pengguna users.getIdentity menampilkan ID pengguna Google dan Fitbit lama pengguna.
Mendapatkan Perangkat users.pairedDevices menampilkan daftar perangkat yang disambungkan
Membuat Langganan projects.subscribers.subscriptions.create membuat langganan secara manual
Menghapus Langganan projects.subscribers.subscriptions.delete menghapus langganan
Mendapatkan Daftar Langganan projects.subscribers.subscriptions.list mencantumkan semua langganan