Uç noktalar (Endpoint)

Bu sayfada, REST API kurallarına genel bir bakışın yanı sıra yaygın Google Health API görevlerinin ve her birine ait örneklerin indeksi yer almaktadır.

REST API kuralları

Google Health API, Google API Geliştirme Önerileri (AIP) standartlarına, özellikle AIP-127 (HTTP ve gRPC Transkodlama) ile AIP-131'den AIP-135'e (Standart Yöntemler) kadar olan standartlara uygundur. Bu standartlar, verilerin bir proto mesajından 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/sayfalara ayırma) için kullanılır ancak DELETE işlemleri için de kullanılır.

  • Yerleşim: URL'ye ? karakterinden 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.http ek 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 İyi Kullanım Alanları: 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. Derin 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. Nutrition API, aşağıdaki koşullarla tarih değerleri için ISO-8601 standardını destekler:

  • 4 haneli bir 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 Google Health API görevlerinin bir dizini ve her bir görevle ilgili örnekler verilmektedir.

Fitbit veya Google kullanıcı kimliğini alma

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

Aralık verilerinin mutabakatlı görünümünü elde etme

Aralık verilerini çakışan kayıtlar veya çeşitli cihaz çakışmaları olmadan almak için reconcile uç noktasını çağırın. Uzlaştırma uç noktası, senkronizasyon grupları ve birden fazla kayıt cihazı genelinde çakışan aralıkları otomatik olarak tekilleştirir. Bu sayede, etkinlik zaman çizelgelerini oluşturmak ve süreleri hesaplamak için uygun olan yetkili ve kesintisiz bir yayın döndürülür.

Bağlı cihazların neden çakışan aralıklar oluşturduğu ve list ile reconcile arasındaki operasyonel karşılaştırma hakkında bilgi edinmek için Veri yönetimi kılavuzu'na bakın.

Aşağıdaki örnekte, iki çakışan egzersiz oturumu olan bir kullanıcı için list (çakışan kayıtların her ikisini de döndürür) ile reconcile (yetkili kaydı döndürerek çakışmayı çözer) yanıtı karşılaştırılmaktadır:

Ham liste

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

Mutabakat yapıldı

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

Mutabakat, çakışan oturumları tekilleştirerek ve yapay bir zaman birliği (ör. 11:00:00Z ile 11:50:00Z) sentezlemek yerine yetkili kaydı seçerek çözer. Mutabakatlı yanıt, kazanan veri noktasını (7797422996486764704) orijinal olarak kaydedilen aralığıyla (11:20:00Z ile 11:50:00Z) birlikte döndürerek söz konusu oturumun ölçülen telemetrisinin ve metriklerinin bütünlüğünü korur.

Verileri filtrele

Bir zaman aralığı, tarih veya gözlem zamanı gibi ölçütlerle eşleşen veri noktası kayıtlarının belirli alt kümelerini almak için list veya reconcile uç noktasını filter parametresiyle kullanın.

Ayrıntılı yönergeler, biçimlendirme kuralları, doğrulama hataları ve sorgu örnekleri için Verileri filtreleme kılavuzuna bakın.

Veri kaynağı ailesine göre filtreleme

Belirli kaynak türlerindeki verileri (ör. fiziksel giyilebilir cihazlar ve manuel girişler) ayırmak veya toplamak için dataSourceFamily parametresini kullanın.

reconcile, rollUp ve dailyRollUp ile ilgili ayrıntılı yönergeler, desteklenen aileler ve istek ile yanıt örnekleri için Filtreleme verileri kılavuzundaki Veri kaynağı ailesine göre filtreleme başlıklı makaleye bakın.

Verileri aralık başlangıç zamanına göre filtreleme

Verileri sivil saate veya aralığa göre filtrelemek için list parametresiyle filter uç noktasını 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 filter parametresiyle list uç noktasını 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/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": ""
}

Veri kaynağı ailesine göre filtreleme ve toplama

Veri kaynağı ailesi, veri kaynaklarının (ör. akıllı saatler, mobil uygulamalar veya manuel girişler) mantıksal olarak gruplandırılmasıdır. Bu özellik, belirli kaynak türlerinden gelen verileri (ör. fiziksel giyilebilir cihazlar ve manuel girişler) ayırmanıza veya toplamanıza olanak tanır.

reconcile, rollUp ve dailyRollUp uç noktalarının tümü dataSourceFamily parametresini destekler. Geçiş mekanizması, uç noktaya bağlıdır:

Uç nokta (HTTP yöntemi) Sistem
reconcile (GET) dataSourceFamily değerini URL sorgu parametresi olarak iletin.
rollUp (YAYINLA) dataSourceFamily değerini JSON istek gövdesinde alan olarak iletin.
dailyRollUp (YAYINLA) dataSourceFamily değerini JSON istek gövdesinde alan olarak iletin.

Desteklenen Veri Kaynağı Aileleri

Aşağıdaki tabloda desteklenen dataSourceFamily değerleri açıklanmaktadır:

Seçenek Açıklama
users/me/dataSourceFamilies/all-sources Varsayılan değer. Kayıtlı tüm birinci taraf (1P) ve üçüncü taraf (3P) veri kaynaklarında mutabakatı yapılan iade verileri noktalarını döndürür. Bu seçenekle üçüncü taraf uygulama verileri (ör. akıllı saat adımları + üçüncü taraf uygulama adımları + cep telefonu adımları + manuel adımlar) döndürülür.
users/me/dataSourceFamilies/google-wearables Google ve Fitbit takip cihazları (ör. Fitbit giyilebilir takip cihazları ve Pixel Watch) tarafından kaydedilen veriler dahildir. Manuel olarak kaydedilen veriler ve telefon tarafından tahmin edilen veriler hariç tutulur. Entegrasyonunuz için doğrudan giyilebilir donanım tarafından kaydedilen ham sensör telemetrisi gerektiğinde bu seçeneği kullanın.
users/me/dataSourceFamilies/google-sources Birinci taraf Google ve Fitbit kaynaklarını içerir. Buna fiziksel takip cihazı kayıtları, Health Connect'ten alınan veriler ve birinci taraf uygulamaları (ör. Fitbit uygulaması veya Google Fit) üzerinden kaydedilen tüm manuel girişler dahildir.

Belirli bir veri kaynağı ailesinden mutabakatı yapılmış bir veri akışı almak için reconcile uç noktasını dataSourceFamily sorgu parametresiyle çağırın.

Örneğin, aşağıdaki GET isteği, 2026-03-03'ten sonraki gün için izleyici tarafından kaydedilen uyku verilerini getirir:

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

Belirli bir veri kaynağı ailesiyle sınırlı olan belirli bir pencere boyutundaki veri noktalarını toplamak için rollUp uç noktasını çağırın ve dataSourceFamily alanını JSON istek gövdesine iletin.

Aşağıdaki POST isteği, yalnızca giyilebilir cihazlardan toplanan verilerle saatlik aralıklarla (3600s) gün içi yürüme adımı sayılarını sorgular:

İstek

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

Yanıt

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

Belirli bir kaynak ailesi için günlük veri noktalarını toplamak üzere dailyRollUp uç noktasını çağırın ve istek gövdesinde dataSourceFamily alanını iletin.

Örneğin, aşağıdaki istek, kullanıcının adımlarının günlük toplamlarını hesaplar. Bu hesaplamaya tüm birinci taraf Google ve Fitbit kaynakları (giyilebilir cihazlar + manuel girişler) dahildir:

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

Yanıt

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

Bir zaman aralığındaki veri noktalarını toplama

Saniyeler içinde bir aralığa göre veri noktalarının toplu değerini döndürmek için rollUp uç noktasını kullanın. Bu değer, kullanıcıların fiziksel zamanına (UTC olarak) göre datetime aralığı üzerinden hesaplanır.

rollUp uç noktasını çağırırken gerekli zaman aralığını ve windowSize değerini temsil eden istek gövdesini sağlayın. windowSize için aşağıdaki şartlara dikkat edin:

  • Minimum pencere boyutu: windowSize süresi en az 1 saniye olmalıdır ("1s"). Saniyeden kısa süreler, sıfır veya negatif süreler 400 Bad Request (INVALID_ROLLUP_WINDOW) ile reddedilir.
  • Depolama çözünürlüğü hizalama: Toplanan verilerin alt gruplar arasında eşit olmayan şekilde dağıtılmasını önlemek için veri türünün temel depolama çözünürlüğüne eşit veya daha büyük bir windowSize seçin (ör. 1 dakikalık adım aralıkları için "60s"). Ayrıntılı bilgi için Toplama penceresi boyutu ve temel depolama çözünürlüğü başlıklı makaleyi inceleyin.

Örneğin, adım sayılarını 1 dakikalık aralıklarla toplamak için (60s):

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

Yanıt

{
  "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"
      }
    },
...
  ]
}

Verileri tek bir güne veya birden fazla güne göre toplama

dailyRollUp endpoint, 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ı belirtin. 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"
      }
    }
  ]
}

Aralık, pencere boyutunun katı olmadığında gruplandırma

İstenen aralık, windowSize (veya windowSizeDays) değerinin tam katı değilse son grup, aralığın üst uç noktasında kronolojik olarak kesilir ve pencere boyutundan daha kısa bir süreyi kapsar. API, isteğinizi değiştirmeden kabul eder ve herhangi bir yuvarlama, zaman kaydırma veya veri enterpolasyonu gerçekleştirmez.

API, istenen aralığın tamamını kapsamak için toplama pencerelerinin toplam sayısını hesaplarken yukarı yuvarlama bölme işlemini kullanır:

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

Her grup, aralığınızın başından itibaren sırayla başlar. Başka bir tam boyutlu pencere eklemek, istenen bitiş zamanını aşacaksa son pencere, aralık bitiş zamanında kesilir (sıkıştırılır).

Gruplandırma nasıl çalışır?

Bölünemeyen aralıklarla toplama isteğinde bulunurken API aşağıdaki kuralları uygular:

  • Gruplandırma, istenen aralığınızın başında (range.startTime veya range.start) başlar ve pencere boyutu (windowSize veya windowSizeDays) kadar ilerler.
  • Son kronolojik grup, istenen aralığınızın sonunda (range.endTime veya range.end) sabitlenir. Bu nedenle, istenen pencere boyutundan daha kısa bir süreyi kapsar.
  • Döndürülen RollupDataPoint veya DailyRollupDataPoint nesneleri, kendi başlangıç ve bitiş zaman damgalarını açıkça belirtir. Bu zaman damgalarını, kesilmiş paketin gerçek süresini incelemek için kullanabilirsiniz.
  • API, birleştirilmiş verileri ters kronolojik sırada (en yeni önce) döndürdüğünden, son kronolojik grup (kısaltılmış olan) döndürülen listede ilk öğe (index 0) olarak görünür.

Senaryo: 5 dakikalık aralıkla 12 dakika

Bir müşterinin 12 dakikalık bir aralıkta 5 dakikalık bir özet istediğini varsayalım windowSize:

  • range.startTime: 10:00:00
  • range.endTime: 10:12:00 (Toplam süre: 12 dakika)
  • windowSize: 5 minutes

12 dakika, 5 dakikanın katı olmadığı için (12 = 5 * 2 + 2) API, isteği kabul eder ve pencere sayısını ceiling(12 / 5) = 3 olarak hesaplar.

Bu işlem, aşağıdaki üç kronolojik grubu oluşturur:

  1. 1. grup: [10:00:00, 10:05:00) — Süre: 5 dakika (tam pencere)
  2. Grup 2: [10:05:00, 10:10:00) Süre: 5 dakika (tam pencere)
  3. 3. grup (Kısaltılmış): [10:10:00, 10:12:00) — Süre: 2 dakika (range.endTime saniyesinde kısaltıldı)

Toplanan değerler üzerindeki etki

Son pencerenin süresi daha kısa olduğundan, eklenen metrikler (ör. adım sayısı veya toplamı) yalnızca daha kısa zaman aralığı nedeniyle kesilmiş grupta daha düşük olur.

Kullanıcı bu 12 dakikalık süre boyunca dakikada 100 adım olacak şekilde sabit bir hızda yürürse:

  • Grup 1 (10:00-10:05): 500 adım (5 dakika × 100 adım/dakika)
  • 2. grup (10:05-10:10): 500 adım (5 dakika × 100 adım/dakika)
  • 3. grup (10:10-10:12): 200 adım (2 dakika × 100 adım/dakika)

Sıralamayı gösteren örnek API yanıtı

API sonuçları ters kronolojik sırada döndürdüğünden, kesilmiş paket döndürülen listede ilk öğe olarak görünür:

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

Toplama penceresi boyutu ve temel depolama çözünürlüğü

rollUp uç noktası 1 saniye veya daha uzun süreli herhangi bir windowSize değerini kabul etse de farklı veri türleri, ölçümleri farklı örnekleme hızlarında veya temel depolamadaki aralık sürelerinde kaydeder ve kalıcı hale getirir. Örneğin, steps, distance, active-minutes ve active-energy-burned gibi giyilebilir cihazlardaki fiziksel aktivite metrikleri genellikle 1 dakikalık (60s) aralıklarla kaydedilir.

Aralık veri türleri toplanırken rollUp uç noktası, kaydedilen her veri noktasını veri noktasının startTime değerini içeren pakete yerleştirir. API, aralık verilerini alt aralık grupları arasında dilimlemez, enterpolasyon yapmaz veya dağıtmaz.

Temel veri depolama aralığından daha küçük bir windowSize belirtirseniz (örneğin, 1 dakikalık aralıklarla depolanan steps için 10 saniyelik bir pencere isteğinde bulunursanız):

  1. Aralığın startTime ile eşleşen ilk alt paket (örneğin, 10:00:00 ile 10:00:10) bir dakikada biriken sayımın tamamını alır (örneğin, o dakika için kaydedilen 100 adımın tamamı).
  2. Aynı dakika içindeki kalan alt gruplar (10:00:10 - 10:00:20, 10:00:20 - 10:00:30 vb.) bu pencerelerde aralık başlamadığından veri noktası almaz.

Bu durum, aralığın tamamının değerinin ilk alt pencerede yoğunlaştığı "ani artışlı" verilere yol açar.

Eşit şekilde dağıtılmış ve anlamlı toplamlar elde etmek için windowSize'yı her zaman hedef veri türünün temel depolama çözünürlüğüne eşit veya daha büyük bir süreye (örneğin, steps için 60s veya daha büyük) ayarlayın. Her veri türü için depolama çözünürlüğü ve minimum önerilen toplama penceresi hakkında bilgi edinmek için Google Health API veri türleri referansına bakın.

Kullanıcının sağlık verilerini güncelleme

Kullanıcının sağlık verilerini güncellemek için patch uç noktasını kullanın.

patch uç noktası, istek URL'sinde belirtilen tanımlayıcıya göre mevcut bir kaydı günceller. Daha önce eklenmiş bir veri noktasının tanımlayıcısını sağlayın. API, mevcut kaydın üzerine yazar.

Bir veri noktasının aralık zaman damgaları (startTime ve endTime), kaydın sahibi tarafından da güncellenebilir veya Health Connect gibi yukarı akış platformlarından yayılabilir. Zaman damgası değiştirilebilirliği hakkında ayrıntılı bilgi için Veri yönetimi kılavuzu'na bakın. Aralık zaman damgalarını güncelleme örneği için Mevcut veriler için aralık zaman damgalarını güncelleme başlıklı makaleyi inceleyin.

Veri noktası tanımlayıcısı ne zaman kullanılır?

Veri noktası tanımlayıcısı aşağıdaki senaryolarda gereklidir:

  • Hedeflenen güncellemeler: Belirli bir ölçümü güncellemek için patch isteğinde tanımlayıcısını sağlayın.
  • Silme işlemleri: Tanımlayıcıyı saklamak, uygulamanızın batchDelete uç noktasını kullanarak kaydı daha sonra silmesine olanak tanır.

Aşağıda, bir kullanıcının "Scales R Us" şirketinin "HumanScale" adlı bir tartısında vücut yağ yüzdesi ölçümünü güncellediği bir örnek verilmiştir. Kullanıcının 10.03.2026 tarihine ait yeni vücut yağ yüzdesi okuması% 20:

İstek

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

Yanıt

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

Mevcut veriler için güncelleme aralığı zaman damgaları

Mevcut bir veri noktasının aralık zaman damgalarını (REST JSON yüklerinde startTime ve endTime ya da gRPC'de start_time ve end_time) güncellemek için veri noktasının kaynak URI'sine bir PATCH isteği gönderin. Bir kaydın alanlarını yalnızca kaydı oluşturan veya kaydın sahibi olan kullanıcı değiştirebilir. Uygulamalar, oluşturmadıkları veri noktalarını düzenleyemez.

Zaman damgası değişkenliği, Health Connect'ten gelen yukarı akış güncellemeleri ve önbelleğe alma etkileri hakkında bilgi edinmek için Veri yönetimi kılavuzuna bakın.

Aşağıdaki örnekte, patch uç noktasını kullanarak mevcut bir hidrasyon günlüğünün aralık zaman damgalarını güncelleyen bir sahip uygulaması gösterilmektedir:

İstek

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

Yanıt

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

Yiyecek öğesi günlüğe kaydetme

Bir yiyecek öğesini kaydetmek için nutrition-log dataPoints uç noktasına bir POST isteği gönderin. İstek gövdesinde nutritionLog nesnesi içeren bir DataPoint bulunur. 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/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"
    }
  }
}

Kullanıcı sağlık verilerini silme

Bir kullanıcının Fitbit uygulama verileri dizisini silmek için batchDelete yöntemini kullanın.

Bir 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 simgelerini 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/123456789/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ğı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 yine standart hız sınırlarına tabidir. Google Health API, sistem kararlılığını yönetmek ve aşırı yükleri önlemek için uç nokta özel sayfa boyutlarıyla otomatik sayfalama kullanır. Aşağıdaki sınırlara ve davranışa dikkat edin:

  • Otomatik sayfalara ayırma: Uzun bir veri aralığını sorgularsanız API, yalnızca bu uç nokta için sayfa boyutu sınırına kadar olan sonuçların ilk sayfasını nextPageToken ile birlikte döndürür. Sonraki sayfaları istemek için nextPageToken öğesini kullanmanız gerekir.
  • Değişken sayfa boyutları: Sınırlama sınırları, uç noktaya ve veri türüne bağlıdır. Çoğu veri türünde sayfa boyutları en fazla 10.000 ile sınırlıdır. Ancak exercise ve sleep gibi belirli veri türleri için varsayılan ve maksimum sayfa boyutu 25 ile sınırlıdır. Örneğin, bir istemci son 10 yıla ait tüm uyku verilerini isterse API, ilk sayfada yine yalnızca 25 uyku oturumu döndürür.
  • Toplama tarih aralığı kısıtlamaları: Veri toplama ve birleştirme uç noktaları (ör. rollUp ve dailyRollUp) için sorgu tarih aralıkları, veri türüne göre kısıtlanır:
    • calories-in-heart-rate-zone, heart-rate, active-minutes ve total-calories için maksimum 14 günlük aralık.
    • Diğer tüm toplama verisi türleri için maksimum aralık 90 gündür.

Uygulamanızın ihtiyaç duyduğu geçmiş veri hacmine bağlı olarak, veri kümesinin tamamını almak için sayfalar arasında sırayla gezinmeniz gerekir. 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 getirip 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ş verilerin alınmasını eşzamansız, daha düşük öncelikli bir sıraya veya arka plan işlemine devredin.

Toplama için sorgu parçalama

  • Toplama ve günlük toplama uç noktaları maksimum tarih aralığı sınırı (veri türüne bağlı olarak 14 veya 90 gün) uyguladığından, büyük geçmiş toplama sorgularını bu sınırlar içinde daha küçük ve sıralı aralıklara bölmeniz gerekir.
  • Eşzamanlılık sınırlarına uymak ve kullanıcı arayüzünde tutarlı ilerleme göstergeleri sağlamak 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 performansını düşürür.
Önceki
İstemci Kitaplıkları
Sonraki
Filtreler