Endpoint

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

Konvensi REST API

Google Health API mengikuti standar Proposal Peningkatan Google API (AIP), khususnya AIP-127 (Transcoding HTTP dan gRPC) dan 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 merupakan bagian dari URL. Hal ini terutama ditujukan 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.

Untuk mengetahui daftar mendetail format filter, referensi kolom, aturan validasi, dan contoh, lihat Panduan memfilter data.

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.

Untuk panduan mendetail tentang ukuran periode penggabungan, aturan pengelompokan, dan contoh agregasi, lihat Panduan data gabungan.

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 mematuhi 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 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 pembacaan.	Digunakan untuk operasi tulis.
Visibilitas	Terlihat di histori penjelajahan dan log server.	Disembunyikan dari URL.
Kompleksitas	Terbatas pada struktur datar atau berulang.	Mendukung objek JSON bertingkat dalam.
Encoding	Harus berenkode 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 ketentuan 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

Menjalankan endpoint API Google Health memerlukan penggunaan 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 contohnya masing-masing.

Mendapatkan ID pengguna Fitbit atau Google

Setelah pengguna memberikan izin melalui Google OAuth 2.0, respons token tidak berisi ID pengguna Fitbit atau Google. Panggil endpoint getIdentity segera setelah menukarkan kode otorisasi untuk mengambil legacyUserId dan healthUserId serta memverifikasi bahwa Akun Google pengguna ditautkan ke Google Health. Jika akun belum ditautkan, getIdentity akan menampilkan 400 Bad Request dengan alasan ACCOUNT_NOT_LINKED (lihat Menangani Akun Google yang tidak ditautkan).

Contoh:

Permintaan

GET https://health.googleapis.com/v4/users/me/identity
Authorization: Bearer access-token
Accept: application/json

Respons (200 OK)

{
  "name": "users/me/identity",
  "legacyUserId": "A1B2C3",
  "healthUserId": "111111256096816351"
}

Respons (400 ACCOUNT_NOT_LINKED)

{
  "error": {
    "code": 400,
    "message": "The account is not linked to Google Health.",
    "status": "FAILED_PRECONDITION",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "ACCOUNT_NOT_LINKED",
        "domain": "health.googleapis.com",
        "metadata": {
          "redirect_uri": "https://fitbit.google.com/auth/signup"
        }
      }
    ]
  }
}

Mendapatkan data intrahari atau data 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.

Catatan: Saat perangkat terhubung disinkronkan, algoritma di perangkat dapat mengelompokkan ulang telemetri dan mengupload data baru dengan batas yang tumpang-tindih. Untuk mengambil tampilan data interval yang telah direkonsiliasi dan dideduplikasi, lihat Mendapatkan tampilan data interval yang telah direkonsiliasi. Untuk mengetahui latar belakang sinkronisasi perangkat terhubung dan perbandingan operasional antara list dan reconcile, lihat Panduan pengelolaan data.

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 direkonsiliasi

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

Untuk mengetahui latar belakang mengapa perangkat yang 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) versus reconcile (yang menyelesaikan konflik dengan menampilkan data yang otoritatif) untuk pengguna dengan dua sesi latihan 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 data yang otoritatif, bukan menyintesis gabungan waktu buatan (seperti 11:00:00Z hingga 11:50:00Z). Respons yang direkonsiliasi menampilkan titik data pemenang (7797422996486764704) dengan interval asli yang dicatat (11:20:00Z hingga 11:50:00Z), sehingga menjaga integritas telemetri dan metrik yang diukur sesi tersebut.

Memfilter data

Untuk mengambil subset tertentu dari data 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 kelompok 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, kelompok yang didukung, serta contoh permintaan dan respons untuk reconcile, rollUp, dan dailyRollUp, lihat Memfilter menurut kelompok sumber data dalam panduan Memfilter data.

Memfilter data berdasarkan interval waktu mulai sipil

Gunakan endpoint list dengan parameter filter untuk memfilter data berdasarkan waktu sipil atau interval.

Penting: Format ID jenis data berbeda jika jenis data memiliki lebih dari satu kata. Di endpoint, nama jenis data harus dalam format kebab case, seperti body-fat. Namun, dalam parameter filter, nama jenis data harus dalam snake case, seperti body_fat.

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.

Penting: Format ID jenis data berbeda jika jenis data memiliki lebih dari satu kata. Di endpoint, nama jenis data harus dalam format kebab case, seperti body-fat. Namun, dalam parameter filter, nama jenis data harus dalam snake case, seperti body_fat.

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 kelompok sumber data

Kelompok sumber data adalah grup 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 dalam isi permintaan JSON.
dailyRollUp (POST)	Teruskan dataSourceFamily sebagai kolom dalam isi permintaan JSON.

Kelompok Sumber Data yang Didukung

Tabel berikut menjelaskan nilai dataSourceFamily yang didukung:

Opsi	Deskripsi
users/me/dataSourceFamilies/all-sources	Nilai default. Menampilkan titik data yang direkonsiliasi 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 dicatat oleh perangkat pelacak Google dan Fitbit (seperti pelacak perangkat wearable Fitbit dan Pixel Watch). Tidak termasuk data yang dicatat secara manual dan data yang diperkirakan ponsel. Gunakan opsi ini jika integrasi Anda memerlukan telemetri sensor mentah yang direkam langsung oleh hardware wearable.
users/me/dataSourceFamilies/google-sources	Mencakup sumber pihak pertama Google dan Fitbit. Data ini mencakup data perangkat pelacak fisik, data dari Health Connect, dan entri manual yang dicatat melalui aplikasi pihak pertama (seperti aplikasi Fitbit atau Google Fit).

Penting: Anda harus menentukan parameter dataSourceFamily menggunakan format URI resource lengkap, seperti users/me/dataSourceFamilies/google-wearables. String ID pendek (seperti "google-wearables", "wearables", atau "FITBIT") tidak valid dan menyebabkan API menampilkan 400 Bad Request dengan error INVALID_ARGUMENT.

Penting: Format ID jenis data berbeda jika jenis data memiliki lebih dari satu kata. Di endpoint, nama jenis data harus dalam format kebab case, seperti body-fat. Namun, dalam parameter filter, nama jenis data harus dalam snake case, seperti body_fat.

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

Misalnya, permintaan GET berikut mengambil data tidur yang direkam 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 kelompok sumber data tertentu, panggil endpoint rollUp dan teruskan kolom dataSourceFamily dalam isi permintaan JSON.

Permintaan POST berikut mengkueri jumlah langkah berjalan intrahari dalam interval per jam (3600s), yang digabungkan 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 kelompok sumber tertentu, panggil endpoint dailyRollUp dan teruskan kolom dataSourceFamily dalam isi permintaan.

Misalnya, permintaan berikut menghitung rollup harian untuk langkah pengguna, termasuk semua sumber pihak pertama Google dan Fitbit (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 tertentu

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

Saat memanggil endpoint rollUp, berikan isi permintaan yang mewakili waktu tutup-buka yang diperlukan range dan windowSize (setidaknya "1s"). Untuk panduan mendetail tentang persyaratan windowSize, penyelarasan resolusi penyimpanan, aturan pengelompokan, serta contoh permintaan dan respons, lihat Menggabungkan selama interval waktu fisik di panduan Menggabungkan data.

Menggabungkan data dalam satu hari atau beberapa hari

Gunakan endpoint dailyRollUp untuk menggabungkan data dalam satu hari atau beberapa hari (windowSizeDays). Berikan waktu sipil tertutup-terbuka range untuk interval yang diperlukan dalam isi permintaan. Bergantung pada jenis data, endpoint akan menampilkan jumlah atau rata-rata di setiap periode.

Untuk mengetahui detail tentang perilaku agregasi harian, penanganan waktu sipil, batas rentang per permintaan, serta contoh permintaan dan respons, lihat Menggabungkan di seluruh hari kalender dalam panduan Menggabungkan data.

Memperbarui data kesehatan pengguna

Gunakan endpoint patch untuk memperbarui data kesehatan pengguna.

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

Catatan: PATCH tidak dapat digunakan untuk membuat data baru. Untuk menyisipkan data baru, lihat Mencatat item makanan untuk contoh penggunaan metode POST.

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 pembaruan 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 yang ditargetkan: Untuk memperbarui pengukuran tertentu, berikan ID-nya dalam permintaan patch.
• Penghapusan: Dengan mempertahankan ID, aplikasi Anda dapat menghapus data nanti menggunakan endpoint batchDelete.

Berikut adalah 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 stempel waktu interval (startTime dan endTime dalam payload JSON REST, atau start_time dan end_time dalam gRPC) dari titik data yang ada, kirim permintaan PATCH ke URI resource titik data. Hanya pembuat atau pemilik asli data 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 caching, 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 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/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 batchDelete untuk menghapus array data aplikasi Fitbit pengguna.

Berikut adalah contoh saat pengguna sebelumnya mencatat lemak tubuhnya pada timbangan, tetapi 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 waktu terakhir 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"
      ]
    }
  ]
}

Membuat kueri data historis

Salah satu manfaat inti Google Health API adalah kemampuan untuk melacak performa pengguna dan memantau tanda-tanda vital kesehatan mereka dalam jangka waktu yang lama. Anda dapat membuat kueri data pengguna sejauh data tersebut telah dicatat; API tidak memberlakukan batasan atau pembatasan pada jumlah data historis yang dapat digunakan aplikasi Anda.

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

• Penomoran halaman otomatis: Jika Anda mengkueri 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 hanya akan menampilkan 25 sesi tidur di halaman pertama.
• Batasan rentang tanggal rollup: Untuk endpoint rollup dan agregasi 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 diperlukan aplikasi Anda, mengambil seluruh set data akan memerlukan penomoran halaman secara berurutan. Ingatlah hal ini saat mendesain proses sinkronisasi data aplikasi Anda.

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

Sinkronisasi data bertahap (pemuatan hot versus cold)

• 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 "cold" latar belakang: Delegasikan pengambilan data historis lama ke antrean asinkron dengan prioritas lebih rendah atau proses latar belakang 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 membagi kueri agregasi historis yang besar menjadi interval yang lebih kecil dan berurutan dalam batas ini.
• Buat batch atau urutkan subkueri ini dengan aman untuk mematuhi batas konkurensi dan mempertahankan indikator progres UI yang stabil.

Memanfaatkan roll-up yang telah diagregasi sebelumnya

Restrukturisasi dasbor ringkasan dan diagram tren untuk menggunakan endpoint ringkasan yang telah digabungkan sebelumnya (seperti DailyRollUpDataPoints). Tindakan 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 pembatasan 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 melipatgandakan kemacetan backend dan memperparah penurunan kualitas sistem.

Peringatan: Tidak mengikuti panduan ini dapat menyebabkan perilaku dan error yang tidak terduga.