Data gabungan

Google Health API menyediakan endpoint agregasi khusus yang mengelompokkan dan merangkum catatan kesehatan ke dalam periode waktu. Daripada mengambil dan menjumlahkan data mentah individual di klien, gunakan endpoint agregasi untuk menghitung metrik (seperti total, rata-rata, minimum, dan maksimum) melalui aliran data yang direkonsiliasi:

  • Endpoint rollUp menggabungkan titik data selama interval waktu fisik dalam UTC menggunakan durasi periode yang dapat dikonfigurasi dalam detik (windowSize).
  • Endpoint dailyRollUp menggabungkan titik data di satu atau beberapa hari kalender (windowSizeDays) menggunakan waktu sipil yang relatif terhadap jam lokal pengguna.

Kedua endpoint otomatis merekonsiliasi titik data yang tumpang-tindih di seluruh perangkat yang terhubung dan mengecualikan periode saat perangkat tidak dipakai di pergelangan tangan untuk jenis data perangkat wearable yang mendukung deteksi pemakaian di pergelangan tangan.

Membandingkan endpoint agregasi

Pilih endpoint agregasi yang sesuai dengan cara aplikasi Anda mengelompokkan dan menampilkan metrik kesehatan deret waktu:

Fitur rollUp endpoint dailyRollUp endpoint
Permintaan HTTP POST https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints:rollUp POST https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints:dailyRollUp
Representasi waktu Waktu fisik dalam UTC (startTime dan endTime dalam format RFC 3339). Waktu sipil (start dan end sebagai objek CivilDateTime).
Parameter periode windowSize (durasi string yang diperlukan dalam detik, minimum "1s"). windowSizeDays (jumlah hari bilangan bulat opsional, default-nya ditetapkan ke 1).
Objek respons RollupDataPoint DailyRollupDataPoint
Pengurutan respons Urutan kronologis terbalik (jendela terbaru terlebih dahulu). Urutan kronologis terbalik (jendela terbaru terlebih dahulu).
Paling cocok untuk Diagram intrahari, histogram tingkat jam atau menit, dan analisis UTC berdurasi tetap. Dasbor harian, tren multi-hari, dan ringkasan yang memperhitungkan perjalanan zona waktu atau Waktu Musim Panas.

Kedua endpoint menerapkan batas rentang kueri maksimum berdasarkan jenis data:

  • Rentang kueri maksimum 14 hari berlaku untuk calories-in-heart-rate-zone, heart-rate, active-minutes, dan total-calories.
  • Rentang kueri maksimum 90 hari berlaku untuk semua jenis data lain yang didukung.

Untuk memeriksa jenis data yang mendukung rollup dan dailyRollup, lihat referensi jenis data Google Health API.

Menggabungkan selama interval waktu fisik

Gunakan endpoint rollUp untuk menggabungkan titik data selama waktu fisik range (dalam UTC) yang dikelompokkan menurut durasi periode dalam detik (windowSize).

Saat memanggil endpoint rollUp, berikan isi permintaan JSON yang berisi range tertutup-terbuka (startTime inklusif, endTime eksklusif) dan windowSize. Perhatikan persyaratan windowSize berikut:

  • Durasi windowSize harus minimal 1 detik ("1s"). API menolak durasi di bawah satu detik, nol, atau negatif dengan error 400 Bad Request (INVALID_ROLLUP_WINDOW).
  • Untuk menghindari distribusi data gabungan yang tidak merata di seluruh sub-bucket, pilih windowSize yang sama dengan atau lebih besar dari resolusi penyimpanan yang mendasari jenis data (seperti "60s" untuk interval langkah 1 menit). Untuk mengetahui detailnya, lihat Periode rollup dan resolusi penyimpanan.

Misalnya, permintaan berikut 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 di seluruh hari kalender

Gunakan endpoint dailyRollUp untuk menggabungkan data dalam satu hari kalender atau beberapa hari (windowSizeDays). Berikan waktu sipil tertutup-terbuka range (start dan end) dalam isi permintaan. Bergantung pada jenis data, endpoint menampilkan nilai gabungan seperti jumlah atau rata-rata di setiap jendela sipil.

Karena dailyRollUp beroperasi pada waktu sipil menggunakan offset UTC yang dicatat dengan setiap titik data, secara otomatis merekonsiliasi panjang hari variabel yang disebabkan oleh transisi Waktu Musim Panas atau perjalanan melintasi zona waktu.

Misalnya, permintaan berikut menggabungkan jumlah langkah selama satu hari sipil (windowSizeDays: 1):

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

Menggabungkan menurut kelompok sumber data

rollUp dan dailyRollUp menerima kolom dataSourceFamily opsional dalam isi permintaan JSON untuk membatasi agregasi ke grup sumber tertentu:

  • Opsi users/me/dataSourceFamilies/all-sources (default) menggabungkan data yang direkonsiliasi di semua sumber pihak pertama dan pihak ketiga yang terdaftar.
  • Opsi users/me/dataSourceFamilies/google-wearables menggabungkan data yang dicatat oleh perangkat pelacak wearable Google dan Fitbit, tidak termasuk data yang dicatat secara manual dan data yang diperkirakan ponsel.
  • Opsi users/me/dataSourceFamilies/google-sources menggabungkan data dari sumber pihak pertama Google dan Fitbit, termasuk pelacak perangkat wearable, Health Connect, dan entri manual di aplikasi pihak pertama.

Untuk mengetahui persyaratan parameter lengkap serta contoh permintaan dan respons, lihat Memfilter menurut kelompok sumber data dalam panduan Memfilter data.

Periode rollup dan resolusi penyimpanan

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

Tabel berikut mencantumkan resolusi penyimpanan pokok dan nilai windowSize minimum yang direkomendasikan untuk jenis data umum:

Resolusi penyimpanan Spesifikasi minimum yang direkomendasikan windowSize Jenis data
1 detik (1s) "1s" heart-rate
1 menit (60s) "60s" active-energy-burned, active-minutes, active-zone-minutes, altitude, calories-in-heart-rate-zone, distance, floors, steps, time-in-heart-rate-zone, total-calories

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

Jika Anda menentukan windowSize yang lebih kecil dari interval penyimpanan data yang mendasarinya (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 akumulasi seluruh menit (misalnya, semua 100 langkah yang dicatat 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 jendela tersebut.

Hal ini menghasilkan data yang tidak stabil, dengan nilai seluruh interval terkonsentrasi di sub-jendela pertama, seperti yang ditunjukkan pada Gambar 1.

Bucketing rollup sub-interval dibandingkan dengan resolusi penyimpanan
Gambar 1: Bucketing rollup sub-interval dengan interval 1 menit ditetapkan ke sub-bucket 10 detik pertama berdasarkan startTime

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

Bucketing saat rentang bukan kelipatan ukuran jendela

Jika rentang yang diminta bukan kelipatan persis dari windowSize (atau windowSizeDays), bucket kronologis akhir akan dipotong di endpoint atas rentang dan mencakup durasi yang lebih pendek dari ukuran periode. API menerima permintaan Anda tanpa modifikasi dan tidak melakukan pembulatan, pergeseran 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 melampaui waktu akhir yang Anda minta, jendela terakhir akan dipotong (dibatasi) pada waktu akhir rentang.

Cara kerja pengelompokan

Saat Anda meminta rollup dengan rentang yang tidak dapat dibagi, API akan menerapkan aturan berikut:

  • Bucketing dimulai pada awal rentang yang Anda minta (range.startTime atau range.start) dan berlanjut ke depan berdasarkan ukuran jendela (windowSize atau windowSizeDays).
  • Bucket kronologis akhir dijepit di akhir rentang yang Anda minta (range.endTime atau range.end), yang mencakup durasi yang lebih singkat daripada ukuran periode yang diminta.
  • Objek RollupDataPoint atau DailyRollupDataPoint yang ditampilkan menyertakan stempel waktu mulai dan akhir eksplisitnya sendiri, yang dapat Anda gunakan untuk memeriksa durasi sebenarnya dari bucket yang dipotong.
  • Karena API menampilkan data rollup dalam urutan kronologis terbalik (terbaru terlebih dahulu), bucket kronologis akhir (bucket yang dipotong) muncul sebagai elemen pertama (index 0) dalam daftar yang ditampilkan.

Gambar 2 mengilustrasikan cara API mengelompokkan rentang yang tidak dapat dibagi ke depan dari range.startTime, mengunci bucket akhir di range.endTime, dan menampilkan bucket yang dihasilkan dalam urutan kronologis terbalik.

Pengelompokan, pemotongan, dan pengurutan respons rollup
Gambar 2: Pengelompokan rollup, pemotongan akhir rentang, dan pengurutan respons kronologis terbalik

Contoh rentang 12 menit dengan periode 5 menit

Misalkan klien meminta rollup dalam rentang 12 menit dengan windowSize ("300s") 5 menit:

  • Nilai range.startTime adalah 10:00:00Z.
  • Nilai range.endTime adalah 10:12:00Z, dengan total durasi 12 menit.
  • Nilai windowSize adalah "300s" (5 menit).

Karena 12 menit bukan kelipatan persis dari 5 menit (12 = 5 * 2 + 2), API menghitung jumlah jendela sebagai ceiling(12 / 5) = 3. Tindakan ini menghasilkan tiga bucket kronologis:

Bucket Interval Durasi Status periode
Bucket 1 [10:00:00Z, 10:05:00Z) 5 menit Jendela penuh
Bucket 2 [10:05:00Z, 10:10:00Z) 5 menit Jendela penuh
Bucket 3 [10:10:00Z, 10:12:00Z) 2 menit Dipotong pada range.endTime

Dampak pada nilai gabungan

Karena periode kronologis akhir memiliki durasi yang lebih singkat, metrik aditif (seperti jumlah atau hitungan langkah) lebih rendah dalam bucket yang dipotong karena rentang waktu yang lebih singkat.

Jika pengguna berjalan dengan kecepatan stabil 100 langkah per menit selama seluruh rentang 12 menit ini, bucket akan berisi total berikut:

  • Bucket 1 (10:00:00Z hingga 10:05:00Z) mencatat 500 langkah (5 menit dengan 100 langkah per menit).
  • Bucket 2 (10:05:00Z hingga 10:10:00Z) mencatat 500 langkah (5 menit dengan 100 langkah per menit).
  • Bucket 3 (10:10:00Z hingga 10:12:00Z) mencatat 200 langkah (2 menit dengan 100 langkah per menit).

Jumlah langkah yang lebih rendah, yaitu 200 langkah di Bucket 3, disebabkan oleh durasi jendela yang dipotong selama 2 menit, bukan penurunan aktivitas pengguna. Saat membuat plot atau menganalisis data ini, normalisasi jumlahnya menggunakan durasi eksplisit setiap bucket untuk menghindari penurunan aktivitas pengguna yang menyesatkan.

Gambar 3 membandingkan total langkah aditif mentah (countSum) dengan tingkat yang dinormalisasi durasi di tiga bucket.

Perbandingan total langkah bucket mentah dan rasio langkah yang dinormalisasi
Gambar 3: Total aditif mentah dibandingkan dengan rasio yang dinormalisasi durasi untuk bucket rollup yang dipotong

Contoh respons API yang menampilkan pengurutan

Karena API menampilkan hasil dalam urutan kronologis terbalik, bucket yang dipotong akan 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"
      }
    }
  ]
}
Sebelumnya
Filter
Berikutnya
Batas kapasitas