Birleştirilmiş veriler

Google Health API, sağlık kayıtlarını zaman aralıklarına göre gruplandırıp özetleyen özel toplama uç noktaları sağlar. İstemcideki ham kayıtları tek tek alıp toplamak yerine, mutabakatı yapılmış bir veri akışı üzerinden metrikleri (toplamlar, ortalamalar, minimumlar ve maksimumlar gibi) hesaplamak için toplama uç noktalarını kullanın:

  • rollUp uç noktası, saniye cinsinden yapılandırılabilir bir pencere süresi (windowSize) kullanarak UTC'deki fiziksel zaman aralıkları üzerinden veri noktalarını toplar.
  • dailyRollUp uç noktası, kullanıcının yerel saatine göre sivil saati kullanarak bir veya daha fazla takvim günündeki (windowSizeDays) veri noktalarını birleştirir.

Her iki uç nokta da bağlı cihazlardaki çakışan veri noktalarını otomatik olarak mutabık kılar ve bilek algılamayı destekleyen giyilebilir veri türleri için bilekte olmayan dönemleri hariç tutar.

Toplama uç noktalarını karşılaştırma

Uygulamanızın zaman serisi sağlık metriklerini gruplandırma ve görüntüleme şekliyle eşleşen toplama uç noktasını seçin:

Özellik rollUp uç nokta dailyRollUp uç nokta
HTTP isteği 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
Zaman gösterimi UTC cinsinden fiziksel zaman (RFC 3339 biçiminde startTime ve endTime). Sivil saat (CivilDateTime nesneleri olarak start ve end).
Pencere parametresi windowSize (saniye cinsinden gerekli dize süresi, minimum "1s"). windowSizeDays (isteğe bağlı tam sayı gün sayısı, varsayılan olarak 1).
Yanıt nesnesi RollupDataPoint DailyRollupDataPoint
Yanıt sıralaması Ters kronolojik sıra (en yeni pencere en başta). Ters kronolojik sıra (en yeni pencere en başta).
En uygun olduğu durumlar Gün içi grafikler, saatlik veya dakikalık histogramlar ve sabit süreli UTC analizi. Saat dilimi seyahatini veya yaz saati uygulamasını hesaba katan günlük kontrol panelleri, çok günlük trendler ve özetler.

Her iki uç nokta da veri türüne göre maksimum sorgu aralığı sınırları uygular:

  • calories-in-heart-rate-zone, heart-rate, active-minutes ve total-calories için maksimum 14 günlük sorgu aralığı geçerlidir.
  • Desteklenen diğer tüm veri türleri için maksimum 90 günlük sorgu aralığı geçerlidir.

rollup ve dailyRollup işlemlerini destekleyen veri türlerini kontrol etmek için Google Health API veri türleri referansına bakın.

Fiziksel zaman aralıklarına göre toplama

Veri noktalarını saniye cinsinden bir pencere süresine (windowSize) göre gruplandırılmış fiziksel bir zaman range (UTC olarak) üzerinden toplamak için rollUp uç noktasını kullanın.

rollUp uç noktasını çağırırken kapalı-açık range (startTime dahil, endTime hariç) ve windowSize içeren bir JSON istek gövdesi sağlayın. Aşağıdaki windowSize şartlarını göz önünde bulundurun:

  • windowSize süresi en az 1 saniye ("1s") olmalıdır. API, bir saniyeden kısa süreleri, sıfır veya negatif süreleri 400 Bad Request (INVALID_ROLLUP_WINDOW) hatasıyla reddeder.
  • Birleştirilmiş 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 ondan daha büyük bir windowSize seçin (ör. 1 dakikalık adım aralıkları için "60s"). Ayrıntılar için Toplama penceresi ve depolama çözünürlüğü bölümünü inceleyin.

Örneğin, aşağıdaki istek, adım sayılarını 1 dakikalık aralıklarla (60s) toplar:

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

Takvim günleri arasında toplama

Tek bir takvim günü veya birden fazla gün (windowSizeDays) boyunca verileri toplamak için dailyRollUp uç noktasını kullanın. İstek gövdesinde kapalı-açık sivil zamanı range (start ve end) belirtin. Veri türüne bağlı olarak uç nokta, her bir sivil penceredeki toplam veya ortalama gibi toplu değerleri döndürür.

dailyRollUp, her veri noktasıyla kaydedilen UTC farklarını kullanarak sivil saate göre çalıştığından, yaz saati uygulaması geçişleri veya saat dilimleri arasında seyahat nedeniyle oluşan değişken gün uzunluklarını otomatik olarak uzlaştırır.

Örneğin, aşağıdaki istek, tek bir sivil gün (windowSizeDays: 1) boyunca adım sayılarını toplar:

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

Veri kaynağı ailesine göre toplama

Hem rollUp hem de dailyRollUp, toplama işlemini belirli kaynak gruplarıyla kısıtlamak için JSON istek gövdesinde isteğe bağlı bir dataSourceFamily alanını kabul eder:

  • users/me/dataSourceFamilies/all-sources seçeneği (varsayılan), kayıtlı tüm birinci taraf ve üçüncü taraf kaynaklarda mutabakatı yapılan verileri birleştirir.
  • users/me/dataSourceFamilies/google-wearables seçeneği, Google ve Fitbit giyilebilir takip cihazları tarafından kaydedilen birleştirilmiş verileri içerir. Manuel olarak kaydedilen ve telefon tarafından tahmin edilen veriler bu seçeneğe dahil edilmez.
  • users/me/dataSourceFamilies/google-sources seçeneği; giyilebilir takip cihazları, Health Connect ve birinci taraf uygulamalardaki manuel girişler dahil olmak üzere birinci taraf Google ve Fitbit kaynaklarından gelen verileri birleştirir.

Tüm parametre koşulları ve istek ile yanıt örnekleri için Verileri filtreleme kılavuzundaki Veri kaynağı ailesine göre filtreleme bölümüne bakın.

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

rollUp uç noktası 1 saniye ("1s") veya daha uzun olan tüm windowSize değerlerini kabul etse de farklı veri türleri, temel depolama alanında farklı örnekleme hızlarında veya aralık sürelerinde ölçümleri kaydeder ve saklar. Örneğin, steps, distance, active-minutes ve active-energy-burned gibi giyilebilir fiziksel aktivite metrikleri genellikle 1 dakikalık (60s) aralıklarla kaydedilir.

Aşağıdaki tabloda, yaygın veri türleri için temel depolama çözünürlükleri ve önerilen minimum windowSize değerleri listelenmiştir:

Depolama alanı çözümü Önerilen minimum değer: windowSize Veri türleri
1 saniye (1s) "1s" heart-rate
1 dakika (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

Aralık veri türleri toplanırken rollUp uç noktası, kaydedilen her veri noktasını, veri noktasının startTime değerini içeren gruba yerleştirir. API, aralık verilerini alt aralık gruplarına bölmez, aralık verileri arasında interpolasyon yapmaz veya aralık verilerini alt aralık gruplarına 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 isterseniz):

  1. Aralığın startTime değeriyle eşleşen ilk alt grup (ör. 10:00:00 - 10:00:10), tüm dakikanın birikmiş sayısını (ör. o dakika için kaydedilen 100 adımın tamamı) alır.
  2. Aynı dakika içindeki kalan alt gruplar (10:00:10 - 10:00:20, 10:00:20 - 10:00:30 vb.) bu aralıklarda başlayan bir aralık olmadığı için veri noktası almaz.

Bu, Şekil 1'de gösterildiği gibi tüm aralığın değerinin ilk alt pencerede yoğunlaştığı ani artışlar gösteren veriler üretir.

Depolama çözünürlüğüyle karşılaştırıldığında alt aralık toplama gruplandırması
Şekil 1: 1 dakikalık bir aralığın startTime'a göre ilk 10 saniyelik alt gruba atandığı alt aralık toplama gruplandırması

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

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

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

API, istenen aralığın tamamını kapsamak için tavan bölme yöntemini kullanarak toplam toplama penceresi sayısını hesaplar:

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

Her aralık, aralığınızın başından itibaren sıralı olarak başlar. Tam boyutlu başka bir pencere eklemek istediğiniz bitiş zamanını aşarsa son pencere, aralık bitiş zamanında kesilir (sınırlandırılır).

Kümelemenin işleyiş şekli

Bölünemez aralıklarla toplayıcı istediğinizde API aşağıdaki kuralları uygular:

  • Gruplandırma, istediğiniz aralığın başında (range.startTime veya range.start) başlar ve pencere boyutuna (windowSize veya windowSizeDays) göre ilerler.
  • Son kronolojik grup, istediğiniz aralığın (range.endTime veya range.end) sonunda sabitlenir ve istenen aralık boyutundan daha kısa bir süreyi kapsar.
  • Döndürülen RollupDataPoint veya DailyRollupDataPoint nesneleri, kendi açık başlangıç ve bitiş zaman damgalarını içerir. Bu zaman damgalarını, kesilen zaman aralığının gerçek süresini incelemek için kullanabilirsiniz.
  • API, toplayıcı verilerini ters kronolojik sırayla (en yeni ilk sırada) döndürdüğünden, son kronolojik grup (kesilmiş grup), döndürülen listedeki ilk öğe (index 0) olarak görünür.

Şekil 2'de, API'nin bölünemez bir aralığı range.startTime tarihinden ileriye doğru nasıl gruplandırdığı, son grubu range.endTime tarihinde nasıl sabitlediği ve elde edilen grupları ters kronolojik sırayla nasıl döndürdüğü gösterilmektedir.

Toplu gruplandırma, kesme ve yanıt sıralama
Şekil 2: Toplu gruplandırma, aralık sonu kesme ve ters kronolojik yanıt sıralaması

5 dakikalık aralıkla 12 dakikalık aralık örneği

Bir istemcinin 5 dakikalık windowSize ("300s") ile 12 dakikalık bir aralıkta toplama istediğini varsayalım:

  • range.startTime değeri 10:00:00Z.
  • range.endTime değeri 10:12:00Z olup toplam süre 12 dakikadır.
  • windowSize değeri "300s" (5 dakika) olarak belirlenmiştir.

12 dakika, 5 dakikanın (12 = 5 * 2 + 2) tam katı olmadığından API, pencere sayısını ceiling(12 / 5) = 3 olarak hesaplar. Bu işlem sonucunda üç kronolojik grup oluşur:

Paket Aralık Süre Süre durumu
1. grup [10:00:00Z, 10:05:00Z) 5 dakika Tam pencere
2. grup [10:05:00Z, 10:10:00Z) 5 dakika Tam pencere
3. grup [10:10:00Z, 10:12:00Z) 2 dakika range.endTime konumunda kesildi

Birleştirilmiş değerler üzerindeki etkisi

Son kronolojik aralığın süresi daha kısa olduğundan, toplama metrikleri (ör. adım toplamı veya sayısı) daha kısa zaman aralığı nedeniyle kısaltılmış grupta daha düşüktür.

Kullanıcı bu 12 dakikalık aralık boyunca dakikada 100 adım olacak şekilde sabit bir tempoda yürürse kovalarda aşağıdaki toplamlar yer alır:

  • 1. grup (10:00:00Z - 10:05:00Z) 500 adım (dakikada 100 adım hızında 5 dakika) kaydeder.
  • 2. grup (10:05:00Z - 10:10:00Z) 500 adım kaydeder (dakikada 100 adım hızında 5 dakika).
  • 3. grup (10:10:00Z - 10:12:00Z) 200 adım (dakikada 100 adım hızında 2 dakika) kaydeder.

3. gruptaki 200 adımlık daha düşük adım sayısı, kullanıcının etkinliğindeki bir düşüşten değil, kısaltılmış pencerenin 2 dakikalık süresinden kaynaklanır. Bu verileri grafiğe dökerken veya analiz ederken, kullanıcı etkinliğinde yanıltıcı bir düşüş göstermemek için her bir aralığın açık süresini kullanarak sayıları normalleştirin.

Şekil 3'te, ham ek adım toplamları (countSum) ile üç gruptaki süreye göre normalleştirilmiş oranlar karşılaştırılmaktadır.

Ham grup adım toplamları ile normalleştirilmiş adım oranlarının karşılaştırması
3. Şekil: Kısaltılmış bir toplayıcı grubu için süreye göre normalleştirilmiş oranlarla karşılaştırılan ham eklemeli toplamlar

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

API, sonuçları ters kronolojik sırayla döndürdüğünden, kesilen paket döndürülen listedeki 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"
      }
    }
  ]
}
Önceki
Filtreler
Sonraki
Hız sınırları