Bu sayfada, REST API kurallarına genel bakışın yanı sıra yaygın Google Health API görevlerinin ve her birine ait örneklerin dizini yer almaktadır.
REST API kuralları
Google Health API, Google API Geliştirme Önerileri (AIP) standartlarına, özellikle AIP-127 (HTTP ve gRPC Kod Dönüştürme) ile AIP-131'den AIP-135'e (Standart Yöntemler) kadar olan standartlara uygundur. Bu standartlar, verilerin bir proto mesajdan HTTP isteğine nasıl eşleneceğini tanımlar.
Sorgu parametreleri
Veriler URL'nin bir parçası olduğunda sorgu parametreleri kullanılır. Bu, öncelikle GET istekleri (kaynak getirme) veya LIST istekleri (filtreleme/sayfalama) için kullanılır ancak DELETE işlemleri için de kullanılır.
- Yerleşim: URL'ye
?işaretinden sonra eklenir. - Söz dizimi:
&ile ayrılmış anahtar/değer çiftleri. - Eşleme: İstek mesajındaki URL yolu şablonunun parçası olmayan her alan bir sorgu parametresiyle eşlenir.
- En uygun kullanım alanı: Basit türler (dizeler, tam sayılar, numaralandırmalar) ve yinelenen alanlar.
Örnek söz dizimi:
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"
İstek metni
Veriler bir kaynağın durumunu değiştirdiğinde veya URL için çok büyük olduğunda istek gövdesi kullanılır. Gövde genellikle kaynağın kendisinin JSON gösterimidir. Genellikle POST, PATCH ve PUT işlemleri için kullanılır.
- Yerleşim: HTTP yükünün içinde (URL'de görünmez).
- Söz dizimi: JSON nesnesi olarak biçimlendirilir.
- Eşleme:
google.api.httpek açıklamasında tanımlanır.body: "*", iletinin tamamının gövde olduğu anlamına gelir.body: "resource_name", proto'daki yalnızca belirli bir alanın gövde olduğu anlamına gelir.
- En uygun olduğu durumlar: Karmaşık nesneler, iç içe yerleştirilmiş mesajlar ve hassas veriler.
Örnek söz dizimi:
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"
}Karma durum
AIP-134 uyumlu bir Update yönteminde veya bir PATCH işleminde her ikisi de kullanılır.
URL, kaynak adını içerir. İçerik, güncellenen kaynak verilerini içerir. Bir sorgu parametresi (genellikle update_mask), hangi alanların değiştirileceğini belirtir.
PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id
Content-Type: application/json
{
"endpointUri": "https://myapp.com/new-webhooks/health"
}
Bir bakışta temel farklar
| Özellik | Sorgu Parametreleri | İstek Metni |
|---|---|---|
| AIP Rehberi | Arama, filtreleme ve okuma işlemleri için kullanılır. | Yazma işlemleri için kullanılır. |
| Görünürlük | Tarayıcı geçmişinde ve sunucu günlüklerinde görünür. | URL'den gizlenir. |
| Karmaşıklık | Düz veya tekrarlanan yapılarla sınırlıdır. | Derinlemesine iç içe yerleştirilmiş JSON nesnelerini destekler. |
| Kodlama | URL kodlamalı olmalıdır (örneğin, boşluklar %20 olur). |
Standart JSON kodlaması. |
Tarihler
Google Health API'sindeki tüm tarihler YYYY-MM-DD biçiminde gösterilir. Beslenme API'si, tarih değerleri için ISO-8601 standardını aşağıdaki koşullarla destekler:
- 4 haneli yıl
YYYY - 0000-9999 aralığındaki yıl değerleri
- ISO-8601 standardı veya başka bir dönem tarafından belirtilen başlangıç tarihi kısıtlamaları uygulanmaz.
Üst bilgiler
Google Health API uç noktalarını yürütmek için uygun başlıkların ve erişim jetonunun kullanılması gerekir. Hem GET hem de POST istekleri için aşağıdaki başlık önerilir:
Authorization: Bearer access-token Accept: application/json
API görev dizini
Bu bölümde, yaygın olarak kullanılan Google Health API görevlerinin bir indeksi ve her bir görevle ilgili örnekler verilmiştir.
Fitbit veya Google kullanıcı kimliğini edinme
Kullanıcı, Google OAuth 2.0 aracılığıyla izin verdikten sonra jeton yanıtı, Fitbit veya Google kullanıcı kimliğini içermez. Kullanıcı kimliğini almak için getIdentity uç noktasını çağırın. getIdentity
hem eski Fitbit kullanıcı kimliğini hem de Google kullanıcı kimliğini döndürür.
Yeni bir kullanıcı OAuth üzerinden izin verdiği anda getIdentity uç noktasını çağırmanızı ve her iki kullanıcı kimliğini de saklamanızı öneririz. Bu, entegrasyonunuzda geriye ve ileriye dönük uyumluluk sağlar.
Örneğin:
İstek
GET https://health.googleapis.com/v4/users/me/identity Authorization: Bearer access-token Accept: application/json
Yanıt
{
"name": "users/me/identity",
"legacyUserId": "A1B2C3",
"healthUserId": "111111256096816351"
}Gün içinde toplanan verileri veya gün boyunca toplanan ayrıntılı verileri alma
Belirli bir veri türü için list
uç noktasını kullanarak gün içinde toplanan gün içi veya ayrıntılı verileri, söz konusu veri türü için desteklenen aralıklarla alın.
Örneğin:
İstek
GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints Authorization: Bearer access-token Accept: application/json
Yanıt
{
"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"
}Verileri, aralık başlangıç zamanına göre filtreleme
Verileri sivil saate veya aralığa göre filtrelemek için list uç noktasını filter parametresiyle kullanın.
Örneğin:
İstek
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
Yanıt
{
"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"
}Verileri örnek gözlem fiziksel zamanına göre filtreleme
Verileri örnek gözlem fiziksel zamanına göre filtrelemek için list uç noktasını filter parametresiyle kullanın.
Örneğin:
İstek
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
Yanıt
{
"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": ""
}Verileri giyilebilir cihazlar gibi veri kaynaklarına göre filtreleme
Belirli bir "veri kaynağı ailesi" ile ilgili verileri almak için reconcile
uç noktasını kullanın. Bunu yapmak için dataSourceFamily parametresini sorgu parametresi olarak belirtin.
Aşağıdaki tabloda desteklenen dataSourceFamily seçenekleri açıklanmaktadır:
| Seçenek | Açıklama |
|---|---|
users/me/dataSourceFamilies/all-sources |
Varsayılan değer. Mevcut tüm veri kaynaklarından alınan verileri içerir. |
users/me/dataSourceFamilies/google-wearables |
Google ve Fitbit takip cihazlarından (ör. Fitbit takip cihazları ve Pixel Watch) alınan verileri içerir. Manuel olarak kaydedilen veriler hariç tutulur. |
users/me/dataSourceFamilies/google-sources |
İzleme cihazlarından alınan veriler ve manuel olarak kaydedilen veriler gibi birinci taraf Google verilerini içerir. |
Aşağıda, yalnızca 2026-03-03 tarihinden sonraki gün için izleyici tarafından kaydedilen uykuyu filtreleme örneği verilmiştir:
İstek
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
Yanıt
{
"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": ""
}Veri noktalarını belirli bir zaman aralığında toplama
rollUp
uç noktasını kullanarak, datetime aralığındaki saniye cinsinden bir pencereye göre veri noktalarının toplu değerini döndürün. Bu aralık, kullanıcıların fiziksel zamanına (UTC olarak) göre belirlenir.
rollUp uç noktasını çağırırken kullanıcının yerel saatine göre gerekli tarih aralığını temsil eden istek gövdesini sağlamanız gerekir. Örneğin:
İstek
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"
}Yanıt
{
"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"
}
},
...
]
}Verileri tek bir gün veya birden fazla gün boyunca toplama
dailyRollUp
uç noktası, windowSize olarak bilinen tek bir gün veya birden fazla gün boyunca verileri toplamak istediğinizde kullanılmalıdır. İstek gövdesinde, gerekli aralık için kapalı-açık sivil zaman aralığını sağlayın. Veri türüne bağlı olarak, aralık boyunca toplamı veya ortalamayı alırsınız.
Örneğin:
İstek
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
}Yanıt
{
"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"
}
}
]
}Kullanıcının sağlık verilerini ekleme veya güncelleme
Kullanıcının Fitbit uygulama verilerini eklemek veya güncellemek için patch
uç noktasını kullanın.
Bir kullanıcının "Scales R Us" şirketinin "HumanScale" adlı bir tartısında vücut yağını kaydettiği bir örneği aşağıda bulabilirsiniz. Kullanıcının yeni vücut yağ yüzdesi ölçümü, 10.03.2026 tarihinde% 20'dir.
İstek
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
}
}Yanıt
{
"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
}
}
}Yiyecek öğesi kaydetme
Bir gıda maddesini kaydetmek için POST veri noktaları nutrition-log uç noktasına istek gönderin. İstek metni, nutritionLog nesnesi içeren bir DataPoint içerir.
Daha fazla bilgi için Beslenme kılavuzu'na bakın.
Örneğin:
İstek
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
}
}
}Yanıt
{
"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"
}
}
}Kullanıcı sağlık verilerini silme
Kullanıcının Fitbit uygulama verilerinin dizisini silmek için batchDelete
uç noktasını kullanın.
Kullanıcının daha önce vücut yağ yüzdesini tartıda kaydettiği ancak kaydı silmek istediği bir örneği aşağıda bulabilirsiniz. Orijinal ekleme işlemindeki user-id ve data-point-id öğelerini kullanma:
İstek
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"
]
}Yanıt
{
"done": true,
"response": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
}
}Cihaz bilgilerini bulma
Bir kullanıcının hesabıyla eşlenmiş cihazların listesini almak için list uç noktasını kullanın. Buna cihazın model bilgileri (deviceVersion) ve Google Health mobil uygulamasıyla son senkronize edildiği zaman (lastSyncTime) dahildir.
Liste yapılandırması ve senkronizasyon bilgileri, senkronizasyon sorunlarını gidermek veya son senkronizasyon zamanından bu yana geçmiş verileri getirmek için yararlıdır.
Örneğin:
İstek
GET https://health.googleapis.com/v4/users/me/pairedDevices Authorization: Bearer access-token Accept: application/json
Yanıt
{
"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"
]
}
]
}Geçmiş verileri sorgulama
Google Health API'nin temel avantajlarından biri, kullanıcının performansını takip etme ve sağlık verilerini uzun süre boyunca izleme olanağı sunmasıdır. Kullanıcı verilerini kaydedildikleri tarihten itibaren sorgulayabilirsiniz. API, uygulamanızın kullanabileceği geçmiş veri miktarıyla ilgili herhangi bir sınırlama veya kısıtlama getirmez.
Ancak geçmiş verilerle ilgili sorgular standart hız sınırlarına tabidir. Google Health API, bu sınırlara göre API çağrılarının sayısını azaltmak için bir tarih aralığındaki verilerin sorgulanmasını destekler. Aşağıdaki sayfalara ayırma ve istek sınırlarına dikkat edin:
- Her uç nokta,sayfa başına maksimum 10.000 veri noktası döndürür.
- Sorgu tarih aralıkları, istek başına 14 ila 90 gün arasında olacak şekilde sınırlandırılmıştır.
Uygulamanızın ihtiyaç duyduğu geçmiş verilerin hacmine bağlı olarak, veri kümesinin tamamının alınması için birden fazla sıralı istek gerekebilir ve bu işlem ek zaman alabilir. Uygulamanızın veri senkronizasyonu sürecini tasarlarken bunu göz önünde bulundurun.
En iyi performansı elde etmek ve API hatalarını önlemek için geçmiş verileri sorgularken aşağıdaki yönergeleri uygulayın:
Aşamalı veri senkronizasyonu (sıcak yükleme ve sıfırdan yükleme)
- İlk "sıcak" yükleme: Birincil yükleme sırası sırasında yalnızca son 7-14 güne ait verileri getirin ve oluşturun. Bu sayede kullanıcılar, uzun süren sorguları beklemek zorunda kalmadan verileri anında görür.
- Arka planda "soğuk" yükleme: Birincil kullanıcı arayüzü oluşturulduktan sonra eski geçmiş verilerinin alınmasını eşzamansız, daha düşük öncelikli bir sıraya veya arka plan işlemine devredin.
Zamana dayalı sorgu parçalama
- Tek bir API çağrısında çok yıllık veya çok aylık aralıklar istemeyin. Büyük geçmiş sorgularını daha küçük ve sıralı aralıklara ayırın (örneğin, istek başına 1 hafta).
- Eşzamanlılık sınırlarına uymak ve kullanıcı arayüzündeki ilerleme göstergelerini sabit tutmak için bu alt sorguları güvenli bir şekilde toplu olarak veya sırayla gönderin.
Önceden toplanmış özetlerden yararlanma
Önceden toplanmış özet uç noktalarını (ör. DailyRollUpDataPoints) kullanmak için genel bakış kontrol panellerini ve trend grafiklerini yeniden yapılandırın. Bu, arka uçtaki işlem yükünü ve istemciye ağ aktarım süresini önemli ölçüde azaltır.
Esnek hata işleme (akıllı yeniden denemeler)
- Hız sınırlarıyla (
429 Too Many Requests) ve sunucu ağ geçidi zaman aşımlarıyla (504 Gateway Timeout) karşılaşıldığında katı eksponansiyel geri yükleme işleme uygulayın. Büyük ve başarısız olan yükleri asla hemen yeniden denemeyin. Anında yeniden denemeler, arka uçtaki tıkanıklığı artırır ve sistemin bozulmasını kötüleştirir. - Bir sorgunun süresi tekrar tekrar doluyorsa otomatik olarak daha küçük bir zaman aralığına geri dönün (örneğin, 1 haftalık bir parçayı 3 güne indirin).