Endpoint

Halaman ini memberikan ringkasan konvensi REST API, beserta indeks tugas umum Google Health API dan contoh masing-masing tugas.

Konvensi REST API

Google Health API mengikuti standar Proposal Peningkatan Kualitas API Google (AIP), khususnya AIP-127 (Transcoding HTTP dan gRPC) serta AIP-131 hingga AIP-135 (Metode Standar). Standar ini menentukan cara data dipetakan dari pesan proto ke permintaan HTTP.

Parameter kueri

Parameter kueri digunakan saat data adalah bagian dari URL. Ini terutama untuk permintaan GET (mengambil resource) atau permintaan LIST (pemfilteran/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. Isinya biasanya berupa 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 menjadi 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"
}

Perbedaan utama secara sekilas

Fitur Parameter Kueri Isi Permintaan
Panduan AIP Digunakan untuk operasi penelusuran, pemfilteran, dan baca. Digunakan untuk operasi tulis.
Visibilitas Terlihat di histori browser dan log server. Tersembunyi dari URL.
Kompleksitas Terbatas pada struktur datar atau berulang. Mendukung objek JSON bertingkat dalam.
Encoding Harus dienkode ke 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 dalam standar ISO-8601 atau epoch lainnya

Header

Untuk mengeksekusi 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 umum Google Health API dan contoh setiap tugas.

Mendapatkan ID pengguna Fitbit atau Google

Setelah pengguna memberikan izin melalui Google OAuth 2.0, respons token tidak berisi ID pengguna Fitbit atau Google. Untuk mendapatkan ID pengguna, panggil endpoint getIdentity. getIdentity mengembalikan 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 intrahari atau mendetail yang dikumpulkan sepanjang hari

Gunakan endpoint list untuk jenis data tertentu guna mendapatkan data intraday atau mendetail 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"
}

Mendapatkan tampilan data interval yang disesuaikan

Untuk mengambil data interval tanpa tumpang-tindih atau konflik multi-perangkat, panggil endpoint reconcile. Endpoint rekonsiliasi secara otomatis menghapus duplikat interval yang tumpang-tindih di seluruh batch sinkronisasi dan beberapa perangkat perekam, yang menampilkan aliran berkelanjutan dan kredibel yang cocok untuk merender linimasa aktivitas dan menghitung durasi.

Untuk mengetahui latar belakang alasan perangkat terhubung menghasilkan interval yang tumpang-tindih dan perbandingan operasional antara list dan reconcile, lihat Panduan pengelolaan data.

Contoh berikut membandingkan respons list (yang menampilkan kedua data yang tumpang-tindih) dengan reconcile (yang menyelesaikan konflik dengan menampilkan data resmi) untuk pengguna dengan dua sesi latihan fisik yang tumpang-tindih:

Daftar mentah

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer access-token
Accept: application/json
 
{
  "dataPoints": [
    {
      "name": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:20:00Z",
          "endTime": "2026-09-03T11:50:00Z"
        },
        "exerciseType": "RUNNING"
      }
    },
    {
      "name": "users/111111256096816351/dataTypes/exercise/dataPoints/4389052750481144696",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:00:00Z",
          "endTime": "2026-09-03T11:30:00Z"
        },
        "exerciseType": "RUNNING"
      }
    }
  ]
}

Direkonsiliasi

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints:reconcile
Authorization: Bearer access-token
Accept: application/json
 
{
  "dataPoints": [
    {
      "dataPointName": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:20:00Z",
          "endTime": "2026-09-03T11:50:00Z"
        },
        "exerciseType": "RUNNING"
      }
    }
  ]
}

Rekonsiliasi menyelesaikan sesi yang bertentangan dengan menghapus duplikat dan memilih catatan resmi, bukan menyintesis gabungan waktu buatan (seperti 11:00:00Z hingga 11:50:00Z). Respons yang direkonsiliasi menampilkan titik data yang menang (7797422996486764704) dengan interval yang direkam aslinya (11:20:00Z hingga 11:50:00Z), sehingga mempertahankan integritas telemetri dan metrik yang diukur dalam sesi tersebut.

Memfilter data

Untuk mengambil subkumpulan spesifik dari rekaman titik data yang cocok dengan kriteria seperti interval waktu, tanggal, atau waktu pengamatan, gunakan endpoint list atau reconcile dengan parameter filter.

Untuk mengetahui panduan mendetail, aturan pemformatan, error validasi, dan contoh kueri, lihat Panduan memfilter data.

Memfilter menurut grup sumber data

Untuk mengisolasi atau menggabungkan data dari jenis sumber tertentu (misalnya, perangkat wearable fisik versus entri manual), gunakan parameter dataSourceFamily.

Untuk mengetahui panduan mendetail, grup yang didukung, serta contoh permintaan dan respons untuk reconcile, rollUp, dan dailyRollUp, lihat Memfilter menurut grup sumber data dalam panduan Memfilter data.

Memfilter data menurut waktu mulai senja sipil interval

Gunakan endpoint list dengan parameter filter untuk memfilter data menurut 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 menurut waktu fisik pengamatan sampel

Gunakan endpoint list dengan parameter filter untuk memfilter data menurut 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/123456789/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 dan menggabungkan menurut famili sumber data

Grup sumber data adalah pengelompokan logis sumber data (seperti smartwatch, aplikasi seluler, atau entri manual). Hal ini memungkinkan Anda mengisolasi atau menggabungkan data dari jenis sumber tertentu (misalnya, perangkat wearable fisik versus entri manual).

Endpoint reconcile, rollUp, dan dailyRollUp semuanya mendukung parameter dataSourceFamily. Mekanisme penerusan bergantung pada endpoint:

Endpoint (metode HTTP) Mekanisme
reconcile (GET) Teruskan dataSourceFamily sebagai parameter kueri URL.
rollUp (POST) Teruskan dataSourceFamily sebagai kolom di isi permintaan JSON.
dailyRollUp (POST) Teruskan dataSourceFamily sebagai kolom di isi permintaan JSON.

Grup Sumber Data yang Didukung

Tabel berikut menjelaskan nilai dataSourceFamily yang didukung:

Opsi Deskripsi
users/me/dataSourceFamilies/all-sources Nilai default. Menampilkan titik data yang disesuaikan di semua sumber data pihak pertama (1P) dan pihak ketiga (3P) yang terdaftar. Data aplikasi pihak ketiga akan ditampilkan dengan opsi ini (seperti langkah smartwatch + langkah aplikasi pihak ketiga + langkah ponsel + langkah manual).
users/me/dataSourceFamilies/google-wearables Mencakup data yang direkam oleh perangkat pelacak Google dan Fitbit (seperti pelacak wearable Fitbit dan Pixel Watch). Mengecualikan data yang dicatat secara manual dan data yang diperkirakan oleh ponsel. Gunakan opsi ini jika integrasi Anda memerlukan telemetri sensor mentah yang direkam langsung oleh hardware perangkat wearable.
users/me/dataSourceFamilies/google-sources Mencakup sumber pihak pertama Google dan Fitbit. Data ini mencakup catatan perangkat pelacak fisik, data dari Health Connect, dan entri manual yang dicatat melalui aplikasi pihak pertama (seperti aplikasi Fitbit atau Google Fit).

Untuk mendapatkan aliran data yang disesuaikan dari family sumber data tertentu, panggil endpoint reconcile dengan parameter kueri dataSourceFamily.

Misalnya, permintaan GET berikut mengambil data tidur yang direkam oleh pelacak untuk hari setelah 03-03-2026:

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": ""
}

Untuk menggabungkan titik data selama ukuran periode tertentu yang dibatasi untuk keluarga sumber data tertentu, panggil endpoint rollUp dan teruskan kolom dataSourceFamily dalam isi permintaan JSON.

Permintaan POST berikut mengkueri jumlah langkah kaki intrahari dalam interval per jam (3600s), yang dikumpulkan secara eksklusif dari perangkat wearable:

Permintaan

POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:rollUp
Authorization: Bearer access-token
Accept: application/json

{
  "range": {
    "startTime": "2026-07-29T00:00:00Z",
    "endTime": "2026-07-29T23:59:59Z"
  },
  "windowSize": "3600s",
  "dataSourceFamily": "users/me/dataSourceFamilies/google-wearables"
}

Respons

{
  "rollupDataPoints": [
    {
      "startTime": "2026-07-29T08:00:00Z",
      "endTime": "2026-07-29T09:00:00Z",
      "steps": {
        "countSum": "1200"
      }
    },
    {
      "startTime": "2026-07-29T09:00:00Z",
      "endTime": "2026-07-29T10:00:00Z",
      "steps": {
        "countSum": "3450"
      }
    }
  ]
}

Untuk menggabungkan titik data harian untuk family sumber tertentu, panggil endpoint dailyRollUp dan teruskan kolom dataSourceFamily dalam isi permintaan.

Misalnya, permintaan berikut menghitung ringkasan harian untuk langkah-langkah pengguna, termasuk semua sumber Google dan Fitbit pihak pertama (perangkat wearable + entri manual):

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": 7,
        "day": 28
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    },
    "end": {
      "date": {
        "year": 2026,
        "month": 7,
        "day": 30
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    }
  },
  "windowSizeDays": 1,
  "dataSourceFamily": "users/me/dataSourceFamilies/google-sources"
}

Respons

{
  "rollupDataPoints": [
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "8430"
      }
    },
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "11245"
      }
    }
  ]
}

Menggabungkan titik data selama rentang waktu

Gunakan endpoint rollUp untuk menampilkan agregat titik data berdasarkan jendela dalam detik, selama rentang datetime berdasarkan waktu fisik pengguna (dalam UTC).

Saat memanggil endpoint rollUp, berikan isi permintaan yang merepresentasikan rentang waktu yang diperlukan dan windowSize. Perhatikan persyaratan berikut untuk windowSize:

  • Ukuran jendela minimum: Durasi windowSize harus minimal 1 detik ("1s"). Durasi di bawah satu detik, nol, atau negatif akan ditolak dengan 400 Bad Request (INVALID_ROLLUP_WINDOW).
  • Penyelarasan resolusi penyimpanan: Untuk menghindari distribusi data gabungan yang tidak merata di seluruh sub-bucket, pilih windowSize yang sama dengan atau lebih besar dari resolusi penyimpanan pokok jenis data (seperti "60s" untuk interval langkah 1 menit). Untuk mengetahui detailnya, lihat Ukuran jendela penggabungan dan resolusi penyimpanan pokok.

Misalnya, untuk menggabungkan jumlah langkah dalam interval 1 menit (60s):

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": "60s"
}

Respons

{
  "rollupDataPoints": [
    {
      "startTime": "2026-02-17T17:55:00Z",
      "endTime": "2026-02-17T17:56:00Z",
      "steps": {
        "countSum": "72"
      }
    },
    {
      "startTime": "2026-02-17T17:54:00Z",
      "endTime": "2026-02-17T17:55:00Z",
      "steps": {
        "countSum": "85"
      }
    },
...
  ]
}

Menggabungkan data selama satu hari atau beberapa hari

Endpoint dailyRollUp harus digunakan saat Anda ingin menggabungkan data di satu hari atau beberapa hari, yang dikenal sebagai windowSize. Berikan rentang waktu sipil tutup-buka untuk interval yang diperlukan di isi permintaan. Bergantung pada jenis data, Anda akan menerima jumlah atau rata-rata selama interval.

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

Pengelompokan saat rentang bukan kelipatan ukuran jendela

Jika rentang yang diminta bukan kelipatan windowSize (atau windowSizeDays) yang tepat, bucket akhir secara kronologis akan dipangkas di endpoint atas rentang dan akan mencakup durasi yang lebih pendek daripada ukuran jendela. API menerima permintaan Anda tanpa modifikasi, dan tidak melakukan pembulatan, perubahan waktu, atau interpolasi data.

Untuk mencakup seluruh rentang yang diminta, API menggunakan pembagian ceiling untuk menghitung jumlah total jendela agregasi:

Number of windows = ceiling(Range duration / Window size)

Setiap bucket dimulai secara berurutan dari awal rentang Anda. Jika penambahan jendela berukuran penuh lainnya akan melampaui waktu berakhir yang Anda minta, jendela terakhir akan dipangkas (dibatasi) pada waktu berakhir rentang.

Cara kerja pengelompokan

Saat meminta ringkasan dengan rentang yang tidak dapat dibagi, API menerapkan aturan berikut:

  • Pengelompokan dimulai di awal rentang yang Anda minta (range.startTime atau range.start) dan berlanjut ke depan berdasarkan ukuran jendela (windowSize atau windowSizeDays).
  • Bucket kronologis terakhir diklem di akhir rentang yang Anda minta (range.endTime atau range.end), yang berarti bucket tersebut mencakup durasi yang lebih singkat daripada ukuran jendela yang diminta.
  • Objek RollupDataPoint atau DailyRollupDataPoint yang ditampilkan secara eksplisit menentukan stempel waktu mulai dan akhir sendiri, yang dapat Anda gunakan untuk memeriksa durasi sebenarnya dari bucket yang dipangkas.
  • Karena API menampilkan data gabungan dalam urutan kronologis terbalik (yang terbaru terlebih dahulu), bucket kronologis akhir (yang dipangkas) muncul sebagai elemen pertama (index 0) dalam daftar yang ditampilkan.

Skenario: Rentang 12 menit dengan periode 5 menit

Misalkan klien meminta penggabungan selama rentang 12 menit dengan windowSize 5 menit:

  • range.startTime: 10:00:00
  • range.endTime: 10:12:00 (Durasi total: 12 menit)
  • windowSize: 5 minutes

Karena 12 menit bukan kelipatan 5 menit (12 = 5 * 2 + 2), API menerima permintaan dan menghitung jumlah periode sebagai ceiling(12 / 5) = 3.

Hal ini akan menghasilkan tiga bucket kronologis berikut:

  1. Bucket 1: [10:00:00, 10:05:00) — Durasi: 5 menit (jendela penuh)
  2. Bucket 2: [10:05:00, 10:10:00) — Durasi: 5 menit (jendela penuh)
  3. Bucket 3 (Terpotong): [10:10:00, 10:12:00) — Durasi: 2 menit (terpotong pada range.endTime)

Dampak pada nilai gabungan

Karena durasi periode akhir lebih singkat, metrik aditif (seperti jumlah atau hitungan langkah) akan lebih rendah dalam bucket yang dipangkas hanya karena jalur waktu yang lebih singkat.

Jika pengguna berjalan dengan kecepatan stabil 100 langkah per menit selama rentang 12 menit ini:

  • Bucket 1 (10.00–10.05): 500 langkah (5 menit × 100 langkah/menit)
  • Bucket 2 (10.05–10.10): 500 langkah (5 menit × 100 langkah/menit)
  • Bucket 3 (10.10–10.12): 200 langkah (2 menit × 100 langkah/menit)

Contoh respons API yang menampilkan pengurutan

Karena API menampilkan hasil dalam urutan kronologis terbalik, bucket yang dipangkas muncul sebagai elemen pertama dalam daftar yang ditampilkan:

{
  "rollupDataPoints": [
    {
      "startTime": "2026-08-20T10:10:00Z",
      "endTime": "2026-08-20T10:12:00Z",
      "steps": {
        "countSum": "200"
      }
    },
    {
      "startTime": "2026-08-20T10:05:00Z",
      "endTime": "2026-08-20T10:10:00Z",
      "steps": {
        "countSum": "500"
      }
    },
    {
      "startTime": "2026-08-20T10:00:00Z",
      "endTime": "2026-08-20T10:05:00Z",
      "steps": {
        "countSum": "500"
      }
    }
  ]
}

Ukuran jendela penggabungan dan resolusi penyimpanan pokok

Meskipun endpoint rollUp menerima windowSize 1 detik atau lebih besar, berbagai jenis data mencatat dan mempertahankan pengukuran pada frekuensi pengambilan sampel atau durasi interval yang berbeda dalam penyimpanan pokok. Misalnya, metrik aktivitas fisik perangkat wearable seperti steps, distance, active-minutes, dan active-energy-burned biasanya direkam dalam interval 1 menit (60s).

Saat menggabungkan jenis data interval, endpoint rollUp menempatkan setiap titik data yang direkam ke dalam bucket yang berisi startTime titik data. API tidak mengelompokkan, menginterpolasi, atau mendistribusikan data interval di seluruh bucket sub-interval.

Jika Anda menentukan windowSize yang lebih kecil daripada interval penyimpanan data pokok (misalnya, meminta periode 10 detik untuk steps yang disimpan pada interval 1 menit):

  1. Sub-bucket pertama yang cocok dengan startTime interval (misalnya, 10:00:00 hingga 10:00:10) menerima jumlah kumulatif seluruh menit (misalnya, semua 100 langkah yang direkam untuk menit tersebut).
  2. Sub-bucket yang tersisa dalam menit yang sama (10:00:10 hingga 10:00:20, 10:00:20 hingga 10:00:30, dan seterusnya) tidak menerima titik data, karena tidak ada interval yang dimulai dalam jangka waktu tersebut.

Hal ini menghasilkan data "berpuncak" di mana nilai seluruh interval terkonsentrasi di sub-window pertama.

Untuk mendapatkan agregat yang terdistribusi secara merata dan bermakna, selalu tetapkan windowSize ke durasi yang sama dengan atau lebih besar dari resolusi penyimpanan yang mendasar dari jenis data target (misalnya, 60s atau lebih besar untuk steps). Untuk resolusi penyimpanan dan jendela penggabungan minimum yang direkomendasikan untuk setiap jenis data, lihat referensi Jenis data Google Health API.

Memperbarui data kesehatan pengguna

Gunakan endpoint patch untuk memperbarui data kesehatan pengguna.

Endpoint patch memperbarui data yang ada berdasarkan ID yang ditentukan di URL permintaan. Berikan ID titik data yang sebelumnya dimasukkan. API akan menimpa data yang ada.

Stempel waktu interval titik data (startTime dan endTime) juga dapat diperbarui oleh pemilik data atau disebarkan dari platform upstream seperti Health Connect. Untuk mengetahui detail tentang mutabilitas stempel waktu, lihat Panduan pengelolaan data. Untuk contoh memperbarui stempel waktu interval, lihat Memperbarui stempel waktu interval untuk data yang ada.

Kapan harus menggunakan ID titik data

ID titik data sangat penting dalam skenario berikut:

  • Pembaruan bertarget: Untuk memperbarui pengukuran tertentu, berikan ID-nya dalam permintaan patch.
  • Penghapusan: Mempertahankan ID memungkinkan aplikasi Anda menghapus rekaman nanti menggunakan endpoint batchDelete.

Berikut contoh saat pengguna memperbarui pembacaan lemak tubuhnya pada timbangan bernama "HumanScale" dari perusahaan "Scales R Us". Pembacaan lemak tubuh baru pengguna adalah 20% untuk tanggal 10-03-2026:

Permintaan

PATCH https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints/1234567890
Authorization: Bearer access-token
Content-Type: application/json

{
  "name": "users/me/dataTypes/body-fat/dataPoints/1234567890",
  "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/123456789/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
    }
  }
}

Memperbarui stempel waktu interval untuk data yang ada

Untuk memperbarui startTime atau endTime titik data interval yang ada, kirim permintaan PATCH ke URI resource titik data. Hanya pembuat atau pemilik asli suatu rekaman yang dapat mengubah kolomnya. Aplikasi tidak dapat mengedit titik data yang tidak dibuatnya.

Untuk mengetahui latar belakang tentang mutabilitas stempel waktu, update upstream dari Health Connect, dan implikasi penyiapan cache, lihat Panduan pengelolaan data.

Contoh berikut menunjukkan aplikasi pemilik yang memperbarui stempel waktu interval log hidrasi yang ada menggunakan endpoint patch:

Permintaan

PATCH https://health.googleapis.com/v4/users/me/dataTypes/hydration-log/dataPoints/4093039283164890826
Authorization: Bearer access-token
Content-Type: application/json

{
  "hydrationLog": {
    "interval": {
      "startTime": "2026-09-03T10:05:00Z",
      "endTime": "2026-09-03T10:19:59Z"
    },
    "amountConsumed": {
      "milliliters": 350
    }
  }
}

Respons

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/111111256096816351/dataTypes/hydration-log/dataPoints/4093039283164890826",
    "hydrationLog": {
      "interval": {
        "startTime": "2026-09-03T10:05:00Z",
        "endTime": "2026-09-03T10:19:59Z",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 10,
            "minutes": 5
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 10,
            "minutes": 19,
            "seconds": 59
          }
        }
      },
      "amountConsumed": {
        "milliliters": 350
      }
    }
  }
}

Mencatat item makanan

Untuk mencatat item makanan, kirim permintaan POST ke endpoint nutrition-log dataPoints. Isi permintaan berisi DataPoint dengan objek nutritionLog. Untuk 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/123456789/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 metode batchDeleteuntuk menghapus array data aplikasi Fitbit pengguna.

Berikut contoh saat pengguna sebelumnya mencatat lemak tubuhnya di 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/123456789/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

Respons

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
  }
}

Menemukan informasi perangkat

Gunakan endpoint list untuk mengambil daftar perangkat yang disambungkan ke akun pengguna. Hal ini mencakup informasi model perangkat (deviceVersion) dan terakhir kali perangkat disinkronkan dengan aplikasi seluler Google Health (lastSyncTime).

Konfigurasi daftar dan informasi sinkronisasi 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"
      ]
    }
  ]
}

Mengkueri 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 apa pun pada jumlah data historis yang dapat digunakan aplikasi Anda.

Namun, kueri data historis tetap diatur oleh batas frekuensi standar. Untuk mengelola stabilitas sistem dan mencegah payload yang berlebihan, Google Health API menggunakan penomoran halaman otomatis dengan ukuran halaman khusus endpoint. Perhatikan batas dan perilaku berikut:

  • Penomoran halaman otomatis: Jika Anda membuat kueri rentang data yang panjang, API hanya akan menampilkan halaman pertama hasil hingga batas ukuran halaman untuk endpoint tersebut, beserta nextPageToken. Anda harus menggunakan nextPageToken untuk meminta halaman berikutnya.
  • Ukuran halaman variabel: Batas pembatasan bergantung pada endpoint dan jenis data. Untuk sebagian besar jenis data, ukuran halaman dibatasi hingga maksimum 10.000. Namun, untuk jenis data tertentu seperti exercise dan sleep, ukuran halaman default dan maksimum dibatasi hingga 25. Misalnya, jika klien meminta semua data tidur selama 10 tahun terakhir, API tetap hanya akan menampilkan 25 sesi tidur di halaman pertama.
  • Batasan rentang tanggal rollup: Untuk endpoint penggabungan dan rollup data (seperti rollUp dan dailyRollUp), rentang tanggal kueri dibatasi berdasarkan jenis data:
    • Rentang maksimum 14 hari untuk calories-in-heart-rate-zone, heart-rate, active-minutes, dan total-calories.
    • Rentang maksimum 90 hari untuk semua jenis data gabungan lainnya.

Bergantung pada volume data historis yang dibutuhkan aplikasi Anda, pengambilan seluruh set data akan memerlukan penomoran halaman secara berurutan. Perhatikan hal ini saat mendesain proses sinkronisasi data aplikasi Anda.

Untuk memastikan performa yang optimal dan menghindari error API, ikuti panduan berikut saat mengirimkan kueri data historis:

Sinkronisasi data bertahap (pemuatan aktif versus pasif)

  • Pemuatan "hot" 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 "dingin" di latar belakang: Mendelegasikan pengambilan data historis lama ke proses latar belakang atau antrean asinkron dengan prioritas lebih rendah setelah UI utama dirender.

Pengelompokan kueri untuk agregasi

  • Karena endpoint rollup dan rollup harian menerapkan batas rentang tanggal maksimum (14 atau 90 hari, bergantung pada jenis data), Anda harus memecah kueri agregasi historis yang besar menjadi interval yang lebih kecil dan berurutan dalam batas ini.
  • Kelompokkan atau urutkan sub-kueri ini dengan aman untuk mematuhi batas konkurensi dan mempertahankan indikator progres UI yang stabil.

Memanfaatkan penggabungan yang sudah diagregasi

Menyusun ulang dasbor ringkasan dan diagram tren untuk menggunakan endpoint ringkasan yang telah diagregasi sebelumnya (seperti DailyRollUpDataPoints). Hal ini akan mengurangi overhead komputasi secara drastis di backend dan waktu transfer jaringan ke klien.

Penanganan error yang tangguh (percobaan ulang cerdas)

  • Terapkan penanganan backoff eksponensial yang ketat saat mengalami batas kecepatan (429 Too Many Requests) dan waktu tunggu gateway server (504 Gateway Timeout). Jangan pernah mencoba lagi payload besar yang gagal segera. Percobaan ulang instan melipatgandakan kemacetan backend dan memperparah penurunan kualitas sistem.