Halaman ini memberikan ringkasan konvensi REST API, beserta indeks tugas dan contoh Google Health API umum.
Konvensi REST API
Google Health API mengikuti standar Google API Improvement Proposals (AIP), khususnya AIP-127 (HTTP and gRPC Transcoding) dan AIP-131 hingga AIP-135 (Standard Methods). Standar ini menentukan cara data dipetakan dari pesan proto ke permintaan HTTP.
Parameter kueri
Parameter kueri digunakan saat data adalah bagian dari URL. Parameter ini terutama untuk permintaan GET (mengambil resource) atau permintaan LIST (memfilter/penomoran halaman), tetapi juga digunakan untuk operasi DELETE.
- Penempatan: Ditambahkan ke URL setelah
?. - Sintaksis: Pasangan nilai kunci yang dipisahkan oleh
&. - Pemetaan: Setiap kolom dalam pesan permintaan yang bukan bagian dari template jalur URL dipetakan ke parameter kueri.
- Paling Cocok Untuk: Jenis sederhana (string, int, enum) dan kolom berulang.
Contoh sintaksis:
GET https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints?page_size=10&filter=data_type.interval.start_time >= "2025-10-01T00:00:00Z"
Isi permintaan
Isi permintaan digunakan saat data mengubah status resource atau terlalu besar untuk URL. Isi biasanya merupakan representasi JSON dari resource itu sendiri. Biasanya digunakan untuk operasi POST, PATCH, dan PUT.
- Penempatan: Di dalam payload HTTP (tidak terlihat di URL).
- Sintaksis: Diformat sebagai objek JSON.
- Pemetaan: Ditentukan dalam anotasi
google.api.http.body: "*"berarti seluruh pesan adalah isi.body: "resource_name"berarti hanya kolom tertentu dalam proto yang merupakan isi.
- Paling Cocok Untuk: Objek kompleks, pesan bertingkat, dan data sensitif.
Contoh sintaksis:
POST https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints:rollUp
Content-Type: application/json
{
"range": {
"startTime": "2025-11-05T00:00:00Z",
"endTime": "2025-11-13T00:00:00Z"
},
"windowSize": "3600s"
}Kasus hybrid
Dalam metode Update yang sesuai dengan AIP-134, atau operasi PATCH, keduanya digunakan.
URL berisi nama resource, isi berisi data resource yang diperbarui, dan parameter kueri (biasanya update_mask) menentukan kolom mana yang akan diubah.
PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id
Content-Type: application/json
{
"endpointUri": "https://myapp.com/new-webhooks/health"
}
Sekilas tentang perbedaan utama
| Fitur | Parameter Kueri | Isi Permintaan |
|---|---|---|
| Panduan AIP | Digunakan untuk operasi penelusuran, pemfilteran, dan baca. | Digunakan untuk operasi tulis. |
| Visibilitas | Terlihat dalam histori browser dan log server. | Disembunyikan dari URL. |
| Kompleksitas | Terbatas pada struktur datar atau berulang. | Mendukung objek JSON bertingkat. |
| Encoding | Harus dienkode URL (misalnya, spasi menjadi %20). |
Encoding JSON standar. |
Tanggal
Semua tanggal di Google Health API ditampilkan dalam format YYYY-MM-DD. Nutrition API mendukung standar ISO-8601 untuk nilai tanggal dengan kondisi berikut:
- Tahun 4 digit
YYYY - Nilai tahun dalam rentang 0000-9999
- Tidak ada penerapan batasan tanggal mulai yang tersirat oleh standar ISO-8601 atau epoch lainnya
Header
Untuk menjalankan endpoint Google Health API, Anda harus menggunakan header dan token akses yang sesuai. Header berikut direkomendasikan untuk permintaan GET dan POST:
Authorization: Bearer access-token Accept: application/json
Indeks tugas API
Bagian ini menyediakan indeks tugas Google Health API umum dan contoh setiap tugas.
Mendapatkan ID pengguna Fitbit atau Google
Setelah pengguna memberikan izin melalui Google OAuth 2.0, respons token tidak akan berisi ID pengguna Fitbit atau Google. Untuk mendapatkan ID pengguna, panggil the
getIdentity endpoint. getIdentity
menampilkan ID pengguna lama Fitbit dan ID pengguna Google.
Sebaiknya segera setelah pengguna baru memberikan izin melalui OAuth, Anda memanggil endpoint getIdentity dan menyimpan kedua ID pengguna. Hal ini memberikan kompatibilitas mundur dan maju dalam integrasi Anda.
Contoh:
Permintaan
GET https://health.googleapis.com/v4/users/me/identity Authorization: Bearer access-token Accept: application/json
Respons
{
"name": "users/me/identity",
"legacyUserId": "A1B2C3",
"healthUserId": "111111256096816351"
}Mendapatkan data intraday atau detail yang dikumpulkan sepanjang hari
Gunakan list
endpoint untuk jenis
data tertentu guna mendapatkan data intraday atau detail yang dikumpulkan sepanjang hari dalam
interval yang didukung untuk jenis data tersebut.
Contoh:
Permintaan
GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints Authorization: Bearer access-token Accept: application/json
Respons
{
"dataPoints": [
{
"dataSource": {
"recordingMethod": "PASSIVELY_MEASURED",
"device": {
"manufacturer": "",
"displayName": "Charge 6"
},
"platform": "FITBIT"
},
"steps": {
"interval": {
"startTime": "2026-03-04T07:05:00Z",
"startUtcOffset": "0s",
"endTime": "2026-03-04T07:06:00Z",
"endUtcOffset": "0s",
"civilStartTime": {
"date": {
"year": 2026,
"month": 3,
"day": 4
},
"time": {
"hours": 7,
"minutes": 5
}
},
"civilEndTime": {
"date": {
"year": 2026,
"month": 3,
"day": 4
},
"time": {
"hours": 7,
"minutes": 6
}
}
},
"count": "40"
}
},
...
],
"nextPageToken": "Xm5h-6L0viZxIlRuWjx5bmvy98zj85uG34tuMn16mu2pntsnZI32iqhq"
}Memfilter data berdasarkan waktu mulai sipil interval
Gunakan endpoint list dengan parameter filter untuk memfilter data berdasarkan waktu sipil atau interval.
Contoh:
Permintaan
GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints?filter=steps.interval.civil_start_time >= "2026-03-04T00:00:00" Authorization: Bearer access-token Accept: application/json
Respons
{
"dataPoints": [
{
"dataSource": {
"recordingMethod": "PASSIVELY_MEASURED",
"device": {
"manufacturer": "",
"displayName": "Charge 6"
},
"platform": "FITBIT"
},
"steps": {
"interval": {
"startTime": "2026-03-04T07:05:00Z",
"startUtcOffset": "0s",
"endTime": "2026-03-04T07:06:00Z",
"endUtcOffset": "0s",
"civilStartTime": {
"date": {
"year": 2026,
"month": 3,
"day": 4
},
"time": {
"hours": 7,
"minutes": 5
}
},
"civilEndTime": {
"date": {
"year": 2026,
"month": 3,
"day": 4
},
"time": {
"hours": 7,
"minutes": 6
}
}
},
"count": "40"
}
...
],
"nextPageToken": "Xm5h-6L0viZxIlRuQjp5bml1bZ4ve2dhNmZvMnt4Yn7qIGQhbHN3YQ"
}Memfilter data berdasarkan waktu fisik pengamatan sampel
Gunakan endpoint list dengan parameter filter untuk memfilter data berdasarkan waktu fisik pengamatan sampel.
Contoh:
Permintaan
GET https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints?filter=body_fat.sample_time.physical_time >= "2026-03-01T00:00:00Z" Authorization: Bearer access-token Accept: application/json
Respons
{
"dataPoints": [
{
"name": "users/2515055256096816351/dataTypes/body-fat/dataPoints/1234567890",
"dataSource": {
"recordingMethod": "UNKNOWN",
"application": {
"packageName": "",
"webClientId": "",
"googleWebClientId": "google-web-client-id"
},
"platform": "GOOGLE_WEB_API"
},
"-->bodyFat<--": {
"sampleTime": {
"physicalTime": "2026-03-10T10:00:00Z",
"utcOffset": "0s",
"civilTime": {
"date": {
"year": 2026,
"month": 3,
"day": 10
},
"time": {
"hours": 10
}
}
},
"percentage": 20
}
}
"nextPageToken": ""
}Memfilter data berdasarkan sumber data seperti perangkat wearable
Gunakan reconcile
endpoint untuk mendapatkan
data untuk "keluarga sumber data" tertentu. Untuk melakukannya, tentukan parameter dataSourceFamily sebagai parameter kueri.
Tabel berikut menjelaskan opsi dataSourceFamily yang didukung:
| Opsi | Deskripsi |
|---|---|
users/me/dataSourceFamilies/all-sources |
Nilai default. Mencakup data dari semua sumber data yang tersedia. |
users/me/dataSourceFamilies/google-wearables |
Mencakup data dari perangkat pelacak Google dan Fitbit (seperti pelacak Fitbit dan Pixel Watch). Tidak termasuk data yang dicatat secara manual. |
users/me/dataSourceFamilies/google-sources |
Mencakup data Google pihak pertama, seperti data dari perangkat pelacak dan data yang dicatat secara manual. |
Berikut contoh pemfilteran hanya tidur yang direkam pelacak untuk hari setelah 2026-03-03:
Permintaan
GET https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints:reconcile?dataSourceFamily=users/me/dataSourceFamilies/google-wearables&filter=sleep.interval.civil_end_time >= "2026-03-03" Authorization: Bearer access-token Accept: application/json
Respons
{
"dataPoints": [
{
"name": "users/2515055256096816351/dataTypes/sleep/dataPoints/2724123844716220216",
"dataSource": {
"recordingMethod": "DERIVED",
"device": {
"displayName": "Charge 6"
},
"platform": "FITBIT"
},
"sleep": {
"interval": {
"startTime": "2026-03-03T20:57:30Z",
"startUtcOffset": "0s",
"endTime": "2026-03-04T04:41:30Z",
"endUtcOffset": "0s"
},
"type": "STAGES",
"stages": [
{
"startTime": "2026-03-03T20:57:30Z",
"startUtcOffset": "0s",
"endTime": "2026-03-03T20:59:30Z",
"endUtcOffset": "0s",
"type": "AWAKE",
"createTime": "2026-03-04T04:43:40.937183Z",
"updateTime": "2026-03-04T04:43:40.937183Z"
},
…
{
"startTime": "2026-03-04T04:07:30Z",
"startUtcOffset": "0s",
"endTime": "2026-03-04T04:41:30Z",
"endUtcOffset": "0s",
"type": "AWAKE",
"createTime": "2026-03-04T04:43:40.937183Z",
"updateTime": "2026-03-04T04:43:40.937183Z"
}
],
"metadata": {
"stagesStatus": "SUCCEEDED",
"processed": true,
"main": true
},
"summary": {
"minutesInSleepPeriod": "464",
"minutesAfterWakeUp": "0",
"minutesToFallAsleep": "0",
"minutesAsleep": "407",
"minutesAwake": "57",
"stagesSummary": [
{
"type": "AWAKE",
"minutes": "56",
"count": "12"
},
{
"type": "LIGHT",
"minutes": "198",
"count": "19"
},
{
"type": "DEEP",
"minutes": "114",
"count": "10"
},
{
"type": "REM",
"minutes": "94",
"count": "4"
}
]
},
"createTime": "2026-03-04T04:43:40.337983Z",
"updateTime": "2026-03-04T04:43:40.937183Z"
}
}
],
"nextPageToken": ""
}Menggabungkan titik data dalam rentang waktu
Gunakan rollUp
endpoint untuk menampilkan
gabungan titik data berdasarkan periode dalam detik, dalam rentang datetime
berdasarkan waktu fisik pengguna (dalam UTC).
Saat memanggil endpoint rollUp, Anda harus memberikan isi permintaan yang mewakili rentang tanggal yang diperlukan dalam waktu sipil pengguna. Contoh:
Permintaan
POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:rollUp
Authorization: Bearer access-token
Accept: application/json
{
"range": {
"startTime": "2026-02-17T17:00:00Z",
"endTime": "2026-02-17T17:59:59Z"
},
"windowSize": "30s"
}Respons
{
"rollupDataPoints": [
{
"startTime": "2026-02-17T17:55:00Z",
"endTime": "2026-02-17T17:55:30Z",
"steps": {
"countSum": "41"
}
},
{
"startTime": "2026-02-17T17:54:00Z",
"endTime": "2026-02-17T17:54:30Z",
"steps": {
"countSum": "31"
}
},
...
]
}Menggabungkan data dalam satu hari atau beberapa hari
Endpoint dailyRollUp
harus digunakan jika Anda ingin menggabungkan data dalam
satu hari atau beberapa hari, yang dikenal sebagai windowSize. Berikan rentang waktu sipil tertutup-terbuka untuk interval yang diperlukan dalam isi permintaan. Bergantung pada jenis data, Anda akan menerima jumlah atau rata-rata selama interval tersebut.
Contoh:
Permintaan
POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:dailyRollUp
Authorization: Bearer access-token
Accept: application/json
{
"range": {
"start": {
"date": {
"year": 2026,
"month": 2,
"day": 26
},
"time": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"nanos": 0
}
},
"end": {
"date": {
"year": 2026,
"month": 2,
"day": 26
},
"time": {
"hours": 23,
"minutes": 59,
"seconds": 59,
"nanos": 0
}
}
},
"windowSizeDays": 1
}Respons
{
"rollupDataPoints": [
{
"civilStartTime": {
"date": {
"year": 2026,
"month": 2,
"day": 26
},
"time": {}
},
"civilEndTime": {
"date": {
"year": 2026,
"month": 2,
"day": 26
},
"time": {
"hours": 23,
"minutes": 59,
"seconds": 59
}
},
"steps": {
"countSum": "3822"
}
}
]
}Menyisipkan atau memperbarui data kesehatan pengguna
Gunakan patch
endpoint untuk menyisipkan atau
memperbarui data aplikasi Fitbit pengguna.
Berikut contoh saat pengguna mencatat lemak tubuhnya pada timbangan yang disebut "HumanScale" dari perusahaan "Scales R Us". Pembacaan lemak tubuh baru pengguna adalah 20% untuk tanggal 2026-03-10.
Permintaan
PATCH https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints/1234567890
Authorization: Bearer access-token
content-length: 329
{
"name": "bodyFatName",
"dataSource": {
"recordingMethod": "ACTIVELY_MEASURED",
"device": {
"formFactor": "SCALE",
"manufacturer": "Scales R Us",
"displayName": "HumanScale"
}
},
"bodyFat": {
"sampleTime": {
"physicalTime": "2026-03-10T10:00:00Z"
},
"percentage": 20
}
}Respons
{
"done": true,
"response": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
"name": "users/2515055256096816351/dataTypes/body-fat/dataPoints/1234567890",
"dataSource": {
"recordingMethod": "ACTIVELY_MEASURED",
"device": {
"formFactor": "SCALE",
"manufacturer": "Scales R Us",
"displayName": "HumanScale"
},
"application": {
"googleWebClientId": "618308034039.apps.googleusercontent.com"
},
"platform": "GOOGLE_WEB_API"
},
"bodyFat": {
"sampleTime": {
"physicalTime": "2026-03-10T10:00:00Z"
},
"percentage": 20
}
}
}Mencatat item makanan
Untuk mencatat item makanan, kirim permintaan POST ke endpoint titik data nutrition-log. Isi permintaan berisi DataPoint dengan objek nutritionLog.
Untuk mengetahui informasi selengkapnya, lihat panduan Nutrisi.
Contoh:
Permintaan
POST https://health.googleapis.com/v4/users/me/dataTypes/nutrition-log/dataPoints
Authorization: Bearer access-token
Content-Type: application/json
{
"nutritionLog": {
"interval": {
"startTime": "2026-06-16T12:00:00Z",
"endTime": "2026-06-16T12:30:00Z"
},
"foodDisplayName": "Banana",
"mealType": "LUNCH",
"energy": {
"kcal": 105
},
"totalCarbohydrate": {
"grams": 27
},
"totalFat": {
"grams": 0.3
}
}
}Respons
{
"done": true,
"response": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
"name": "users/2515055256096816351/dataTypes/nutrition-log/dataPoints/567890",
"dataSource": {
"recordingMethod": "ACTIVELY_MEASURED",
"platform": "GOOGLE_WEB_API"
},
"nutritionLog": {
"interval": {
"startTime": "2026-06-16T12:00:00Z",
"startUtcOffset": "0s",
"endTime": "2026-06-16T12:30:00Z",
"endUtcOffset": "0s"
},
"energy": {
"kcal": 105
},
"totalCarbohydrate": {
"grams": 27
},
"totalFat": {
"grams": 0.3
},
"mealType": "LUNCH",
"foodDisplayName": "Banana"
}
}
}Menghapus data kesehatan pengguna
Gunakan batchDelete
endpoint untuk menghapus
array data aplikasi Fitbit pengguna.
Berikut contoh saat pengguna sebelumnya mencatat lemak tubuhnya pada timbangan, tetapi dia ingin menghapus catatan tersebut. Menggunakan user-id dan data-point-id dari tindakan penyisipan asli:
Permintaan
POST https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints:batchDelete
Authorization: Bearer access-token
Accept: application/json
content-length: 93
{
"names": [
"users/2515055256096816351/dataTypes/body-fat/dataPoints/1234567890"
]
}Respons
{
"done": true,
"response": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
}
}Menemukan informasi perangkat
Gunakan list endpoint untuk
mengambil daftar perangkat yang dipasangkan ke akun pengguna. Hal ini mencakup informasi model perangkat (deviceVersion) dan terakhir kali perangkat disinkronkan dengan aplikasi seluler Google Health (lastSyncTime).
Informasi konfigurasi dan sinkronisasi daftar berguna untuk memecahkan masalah sinkronisasi atau mengambil data historis sejak waktu sinkronisasi terakhir.
Contoh:
Permintaan
GET https://health.googleapis.com/v4/users/me/pairedDevices Authorization: Bearer access-token Accept: application/json
Respons
{
"pairedDevices": [
{
"name": "users/me/pairedDevices/123456",
"deviceType": "TRACKER",
"batteryStatus": "High",
"batteryLevel": 88,
"lastSyncTime": "2026-03-04T07:05:00Z",
"deviceVersion": "Charge 6",
"macAddress": "00:11:22:33:44:55",
"features": [
"STEPS",
"HEART_RATE"
]
}
]
}Membuat kueri data historis
Salah satu manfaat utama Google Health API adalah kemampuan untuk melacak performa pengguna dan memantau data vital kesehatannya dalam jangka waktu yang lama. Anda dapat membuat kueri data pengguna sejak data tersebut dicatat; API tidak memberlakukan batasan atau pembatasan pada jumlah data historis yang dapat digunakan aplikasi Anda.
Namun, kueri data historis masih diatur oleh batas kapasitas standar standar. Untuk mengurangi jumlah panggilan API relatif terhadap batas ini, Google Health API mendukung kueri data di seluruh rentang tanggal. Perhatikan batas penomoran halaman dan permintaan berikut:
- Setiap endpoint menampilkan ukuran halaman maksimum 10.000 titik data per halaman.
- Rentang tanggal kueri dibatasi antara 14 dan 90 hari per permintaan.
Bergantung pada volume data historis yang dibutuhkan aplikasi Anda, pengambilan seluruh set data mungkin memerlukan beberapa permintaan berurutan dan memerlukan waktu tambahan. Perhatikan hal ini saat mendesain proses sinkronisasi data aplikasi Anda.
Untuk memastikan performa optimal dan menghindari error API, ikuti panduan berikut saat membuat kueri data historis:
Sinkronisasi data bertahap (pemuatan aktif versus pasif)
- Pemuatan "aktif" awal: Ambil dan render hanya data 7–14 hari terakhir selama urutan pemuatan utama. Hal ini memastikan pengguna melihat data secara langsung tanpa menunggu kueri yang berjalan lama.
- Pemuatan "pasif" latar belakang: Delegasikan pengambilan data historis yang lebih lama ke proses latar belakang atau antrean asinkron dengan prioritas lebih rendah setelah UI utama dirender.
Pengelompokan kueri berbasis waktu
- Jangan meminta rentang multi-tahun atau multi-bulan dalam satu panggilan API. Bagi kueri historis yang besar menjadi interval berurutan yang lebih kecil (misalnya, 1 minggu per permintaan).
- Batch atau urutkan sub-kueri ini dengan aman untuk mematuhi batas serentak dan mempertahankan indikator progres UI yang stabil.
Memanfaatkan gabungan yang telah diagregasi
Susun ulang dasbor ringkasan dan diagram tren untuk menggunakan endpoint ringkasan yang telah diagregasi (seperti DailyRollUpDataPoints). Hal ini akan mengurangi overhead komputasi secara drastis di backend dan waktu transfer jaringan ke klien.
Penanganan error yang tangguh (coba ulang cerdas)
- Terapkan penanganan backoff eksponensial yang ketat saat mengalami batas kapasitas (
429 Too Many Requests) dan waktu tunggu gateway server (504 Gateway Timeout). Jangan pernah mencoba ulang payload besar yang gagal secara langsung. Percobaan ulang instan akan memperbanyak kemacetan backend dan memperburuk penurunan kualitas sistem. - Jika kueri berulang kali mengalami waktu tunggu, otomatis kembali ke jangka waktu yang lebih kecil (misalnya, kurangi bagian 1 minggu menjadi 3 hari).