कुल डेटा

Google Health API, खास तौर पर एग्रीगेशन एंडपॉइंट उपलब्ध कराता है. ये एंडपॉइंट, सेहत के डेटा को समयावधि के हिसाब से ग्रुप करते हैं और उनकी खास जानकारी देते हैं. क्लाइंट पर अलग-अलग रॉ रिकॉर्ड को वापस पाने और उनका योग करने के बजाय, एग्रीगेशन एंडपॉइंट का इस्तेमाल करें. इससे, डेटा स्ट्रीम के लिए मेट्रिक (जैसे, कुल, औसत, कम से कम, और ज़्यादा से ज़्यादा) का हिसाब लगाया जा सकता है:

• rollUp एंडपॉइंट, यूटीसी में तय किए गए समय के अंतराल के हिसाब से डेटा पॉइंट इकट्ठा करता है. इसके लिए, वह कॉन्फ़िगर की जा सकने वाली विंडो की अवधि का इस्तेमाल करता है. यह अवधि सेकंड (windowSize) में होती है.
• dailyRollUp एंडपॉइंट, उपयोगकर्ता की स्थानीय घड़ी के हिसाब से सिविल टाइम का इस्तेमाल करके, एक या उससे ज़्यादा कैलेंडर दिनों (windowSizeDays) के डेटा पॉइंट को इकट्ठा करता है.

दोनों एंडपॉइंट, कनेक्ट किए गए डिवाइसों के ओवरलैप होने वाले डेटा पॉइंट को अपने-आप मैच करते हैं. साथ ही, कलाई पर पहने जाने वाले डिवाइसों के डेटा टाइप के लिए, कलाई पर न पहने जाने की अवधि को हटा देते हैं.

एग्रीगेशन एंडपॉइंट की तुलना करना

ऐसा एग्रीगेशन एंडपॉइंट चुनें जो आपके ऐप्लिकेशन के ग्रुप और टाइम सीरीज़ के हिसाब से सेहत की मेट्रिक दिखाने के तरीके से मेल खाता हो:

सुविधा	rollUp एंडपॉइंट	dailyRollUp एंडपॉइंट
एचटीटीपी अनुरोध	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
समय दिखाने का तरीका	यूटीसी में फ़िज़िकल टाइम (आरएफ़सी 3339 फ़ॉर्मैट में startTime और endTime).	सिविल टाइम (start और end, CivilDateTime ऑब्जेक्ट के तौर पर).
विंडो पैरामीटर	windowSize (सेकंड में स्ट्रिंग की ज़रूरी अवधि, कम से कम "1s").	windowSizeDays (दिनों की संख्या के लिए पूर्णांक, ज़रूरी नहीं है. डिफ़ॉल्ट रूप से, यह 1 पर सेट होता है).
जवाब का ऑब्जेक्ट	RollupDataPoint	DailyRollupDataPoint
जवाबों का क्रम	उल्टे क्रम में (सबसे नई विंडो पहले).	उल्टे क्रम में (सबसे नई विंडो पहले).
इन स्थितियों में बेहतर है	इंट्राडे चार्ट, हर घंटे या मिनट के हिसाब से हिस्टोग्राम, और तय अवधि के यूटीसी विश्लेषण.	रोज़ाना के डैशबोर्ड, कई दिनों के ट्रेंड, और खास जानकारी, जो टाइम ज़ोन में यात्रा करने या डेलाइट सेविंग टाइम को ध्यान में रखती है.

दोनों एंडपॉइंट, डेटा टाइप के आधार पर क्वेरी की ज़्यादा से ज़्यादा रेंज की सीमाएं लागू करते हैं:

• calories-in-heart-rate-zone, heart-rate, active-minutes, और total-calories के लिए, क्वेरी की ज़्यादा से ज़्यादा रेंज 14 दिन की होती है.
• अन्य सभी तरह के डेटा के लिए, क्वेरी की ज़्यादा से ज़्यादा सीमा 90 दिन है.

यह देखने के लिए कि कौनसे डेटा टाइप rollup और dailyRollup के साथ काम करते हैं, Google Health API के डेटा टाइप का रेफ़रंस देखें.

समय के अंतराल के हिसाब से एग्रीगेट करना

rollUp एंडपॉइंट का इस्तेमाल करके, यूटीसी (range) के हिसाब से डेटा पॉइंट एग्रीगेट करें. इन्हें सेकंड (windowSize) में विंडो की अवधि के हिसाब से ग्रुप किया जाता है.

rollUp एंडपॉइंट को कॉल करते समय, JSON अनुरोध का मुख्य हिस्सा दें. इसमें क्लोज़्ड-ओपन range (startTime शामिल है, endTime शामिल नहीं है) और windowSize शामिल है. windowSize की इन ज़रूरी शर्तों का ध्यान रखें:

• windowSize की अवधि कम से कम एक सेकंड ("1s") होनी चाहिए. एपीआई, एक सेकंड से कम, शून्य या नेगेटिव अवधि को अस्वीकार कर देता है. साथ ही, 400 Bad Request (INVALID_ROLLUP_WINDOW) गड़बड़ी दिखाता है.
• सब-बकेट में कुल डेटा के असमान डिस्ट्रिब्यूशन से बचने के लिए, ऐसा windowSize चुनें जो डेटा टाइप के स्टोरेज रिज़ॉल्यूशन के बराबर या उससे बड़ा हो. जैसे, एक मिनट के अंतराल पर कदमों की संख्या के लिए "60s". ज़्यादा जानकारी के लिए, रोलअप विंडो और स्टोरेज रिज़ॉल्यूशन देखें.

उदाहरण के लिए, यहां दिए गए अनुरोध में, एक मिनट के अंतराल पर कदमों की संख्या को रोल अप किया गया है (60s):

अनुरोध

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

जवाब

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

कैलेंडर के दिनों के हिसाब से एग्रीगेट करना

dailyRollUp एंडपॉइंट का इस्तेमाल करके, एक या एक से ज़्यादा दिनों (windowSizeDays) का डेटा इकट्ठा करें. अनुरोध के मुख्य हिस्से में, क्लोज़्ड-ओपन सिविल टाइम range (start और end) दें. डेटा टाइप के आधार पर, एंडपॉइंट एग्रीगेट की गई वैल्यू दिखाता है. जैसे, हर सिविल विंडो के लिए कुल या औसत वैल्यू.

dailyRollUp, हर डेटा पॉइंट के साथ रिकॉर्ड किए गए यूटीसी ऑफ़सेट का इस्तेमाल करके, सिविल टाइम पर काम करता है. इसलिए, यह डेलाइट सेविंग टाइम में बदलावों या अलग-अलग टाइम ज़ोन में यात्रा करने की वजह से, दिन की अवधि में होने वाले बदलावों को अपने-आप अडजस्ट कर लेता है.

उदाहरण के लिए, इस अनुरोध में एक दिन (windowSizeDays: 1) के दौरान चले गए कदमों की संख्या को एग्रीगेट किया गया है:

अनुरोध

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
}

जवाब

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

डेटा सोर्स फ़ैमिली के हिसाब से एग्रीगेट करना

rollUp और dailyRollUp, दोनों JSON अनुरोध के मुख्य हिस्से में, वैकल्पिक dataSourceFamily फ़ील्ड को स्वीकार करते हैं. इससे एग्रीगेशन को खास सोर्स ग्रुप तक सीमित किया जा सकता है:

• users/me/dataSourceFamilies/all-sources विकल्प (डिफ़ॉल्ट) रजिस्टर किए गए सभी पहले पक्ष और तीसरे पक्ष के सोर्स से मिले डेटा को इकट्ठा करता है.
• users/me/dataSourceFamilies/google-wearables विकल्प, Google और Fitbit के पहने जाने वाले ट्रैकर डिवाइसों से रिकॉर्ड किए गए डेटा को इकट्ठा करता है. इसमें मैन्युअल तरीके से लॉग किया गया और फ़ोन से अनुमानित डेटा शामिल नहीं होता.
• users/me/dataSourceFamilies/google-sources विकल्प, Google और Fitbit के पहले पक्ष के सोर्स से डेटा इकट्ठा करता है. इसमें पहने जाने वाले ट्रैकर, Health Connect, और पहले पक्ष के ऐप्लिकेशन में मैन्युअल तरीके से की गई एंट्री शामिल हैं.

पैरामीटर से जुड़ी सभी ज़रूरी शर्तों और अनुरोध और जवाब के उदाहरणों के लिए, डेटा फ़िल्टर करने की गाइड में डेटा सोर्स फ़ैमिली के हिसाब से फ़िल्टर करें लेख पढ़ें.

रोलअप विंडो और स्टोरेज से जुड़ी समस्या का समाधान

rollUp एंडपॉइंट, एक सेकंड ("1s") या उससे ज़्यादा की किसी भी windowSize को स्वीकार करता है. हालांकि, अलग-अलग तरह के डेटा टाइप, स्टोरेज में अलग-अलग सैंपलिंग रेट या इंटरवल की अवधि के हिसाब से मेज़रमेंट को रिकॉर्ड और सेव करते हैं. उदाहरण के लिए, पहने जाने वाले डिवाइस से रिकॉर्ड की गई शारीरिक गतिविधि की मेट्रिक, जैसे कि steps, distance, active-minutes, और active-energy-burned को आम तौर पर एक मिनट (60s) के अंतराल पर रिकॉर्ड किया जाता है.

यहां दी गई टेबल में, सामान्य डेटा टाइप के लिए, स्टोरेज के रिज़ॉल्यूशन और सुझाई गई कम से कम windowSize वैल्यू की सूची दी गई है:

स्टोरेज से जुड़ी समस्या का समाधान	कम से कम windowSize का सुझाव दिया जाता है	डेटा टाइप
1 सेकंड (1s)	"1s"	heart-rate
1 मिनट (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

इंटरवल डेटा टाइप को एग्रीगेट करते समय, rollUp एंडपॉइंट, रिकॉर्ड किए गए हर डेटा पॉइंट को उस बकेट में डालता है जिसमें डेटा पॉइंट का startTime शामिल होता है. एपीआई, इंटरवल डेटा को सब-इंटरवल बकेट में स्लाइस, इंटरपोलेट या डिस्ट्रिब्यूट नहीं करता.

अगर आपने डेटा स्टोरेज के इंटरवल से छोटा windowSize तय किया है, तो: उदाहरण के लिए, एक मिनट के इंटरवल पर स्टोर किए गए steps के लिए, 10 सेकंड की विंडो का अनुरोध करना:

1. इंटरवल के startTime से मैच होने वाली पहली सब-बकेट (उदाहरण के लिए, 10:00:00 से 10:00:10) को पूरे मिनट की कुल संख्या मिलती है (उदाहरण के लिए, उस मिनट के लिए रिकॉर्ड किए गए सभी 100 कदम).
2. उसी मिनट के बाकी सब-बकेट (10:00:10 से 10:00:20, 10:00:20 से 10:00:30 वगैरह) को कोई डेटा पॉइंट नहीं मिलता, क्योंकि उन विंडो में कोई इंटरवल शुरू नहीं होता.

इससे स्पाइकी डेटा जनरेट होता है. इसमें पूरे इंटरवल की वैल्यू, पहली सब-विंडो में इकट्ठा होती है, जैसा कि इमेज 1 में दिखाया गया है.

पहली इमेज: सब-इंटरवल रोलअप बकेटिंग, जिसमें startTime के हिसाब से, 1 मिनट के इंटरवल को 10 सेकंड की पहली सब-बकेट को असाइन किया गया है

बराबर बंटे हुए और काम के एग्रीगेट पाने के लिए, windowSize को हमेशा टारगेट डेटा टाइप के स्टोरेज रिज़ॉल्यूशन के बराबर या उससे ज़्यादा अवधि पर सेट करें. उदाहरण के लिए, steps के लिए "60s" या उससे ज़्यादा. हर डेटा टाइप के स्टोरेज रिज़ॉल्यूशन और रोलअप विंडो के लिए सुझाई गई कम से कम अवधि के बारे में जानने के लिए, Google Health API के डेटा टाइप का रेफ़रंस देखें.

जब रेंज, विंडो के साइज़ का मल्टीपल न हो, तब बकेटिंग करना

अगर अनुरोध की गई रेंज, windowSize (या windowSizeDays) का सटीक गुणज नहीं है, तो समय के हिसाब से आखिरी बकेट को रेंज के ऊपरी एंडपॉइंट पर छोटा कर दिया जाता है. साथ ही, यह विंडो के साइज़ से कम अवधि को कवर करती है. एपीआई, आपके अनुरोध को बिना किसी बदलाव के स्वीकार करता है. साथ ही, यह राउंडिंग, टाइम शिफ़्ट या डेटा इंटरपोलेशन नहीं करता.

अनुरोध की गई पूरी रेंज को कवर करने के लिए, एपीआई सीलिंग डिवीज़न का इस्तेमाल करता है. इससे, एग्रीगेशन विंडो की कुल संख्या का हिसाब लगाया जाता है:

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

हर बकेट, आपकी रेंज की शुरुआत से क्रम से शुरू होती है. अगर फ़ुल-साइज़ की एक और विंडो जोड़ने से, अनुरोध किए गए खत्म होने के समय से ज़्यादा समय लगता है, तो आखिरी विंडो को रेंज के खत्म होने के समय पर छोटा (क्लैंप) कर दिया जाता है.

बकेटिंग की सुविधा कैसे काम करती है

जब ऐसी रेंज के साथ रोलअप का अनुरोध किया जाता है जिन्हें बांटा नहीं जा सकता, तो एपीआई ये नियम लागू करता है:

• बकेटिंग, आपकी अनुरोध की गई रेंज (range.startTime या range.start) की शुरुआत से शुरू होती है और विंडो साइज़ (windowSize या windowSizeDays) के हिसाब से आगे बढ़ती है.
• समय के हिसाब से आखिरी बकेट, आपके अनुरोध की गई रेंज (range.endTime या range.end) के आखिर में क्लैंप की जाती है. इसमें अनुरोध की गई विंडो के साइज़ से कम अवधि शामिल होती है.
• वापस किए गए RollupDataPoint या DailyRollupDataPoint ऑब्जेक्ट में, शुरू और खत्म होने के टाइमस्टैंप शामिल होते हैं. इनका इस्तेमाल करके, छोटी की गई बकेट की असल अवधि की जांच की जा सकती है.
• एपीआई, रोलअप डेटा को रिवर्स-क्रोनोलॉजिकल ऑर्डर (सबसे नया डेटा पहले) में दिखाता है. इसलिए, क्रोनोलॉजिकल ऑर्डर वाली आखिरी बकेट (ट्रंकेट की गई बकेट), दिखाई गई सूची में पहले एलिमेंट (index 0) के तौर पर दिखती है.

दूसरी इमेज में दिखाया गया है कि एपीआई, range.startTime से शुरू होने वाली ऐसी रेंज को कैसे बकेट करता है जिसे विभाजित नहीं किया जा सकता. साथ ही, आखिरी बकेट को range.endTime पर क्लैंप करता है और नतीजे के तौर पर मिलने वाली बकेट को उल्टे क्रम में दिखाता है.

दूसरी इमेज: रोलअप बकेटिंग, रेंज के आखिर में ट्रंकेशन, और जवाबों को उल्टे क्रम में लगाना

उदाहरण के लिए, पांच मिनट की विंडो के साथ 12 मिनट की रेंज

मान लें कि कोई क्लाइंट, 5 मिनट के windowSize ("300s") के साथ 12 मिनट की रेंज में रोलअप का अनुरोध करता है:

• range.startTime की वैल्यू 10:00:00Z है.
• range.endTime की वैल्यू 10:12:00Z है. यह वैल्यू, कुल 12 मिनट की अवधि के लिए है.
• windowSize की वैल्यू "300s" (पांच मिनट) है.

12 मिनट, 5 मिनट (12 = 5 * 2 + 2) का सटीक गुणज नहीं है. इसलिए, एपीआई विंडो की संख्या को ceiling(12 / 5) = 3 के तौर पर कैलकुलेट करता है. इससे, समय के हिसाब से तीन बकेट बनती हैं:

बकेट	इंटरवल	कुल समय	विंडो का स्टेटस
बकेट 1	[10:00:00Z, 10:05:00Z)	5 मिनट	फ़ुल विंडो
बकेट 2	[10:05:00Z, 10:10:00Z)	5 मिनट	फ़ुल विंडो
बकेट 3	[10:10:00Z, 10:12:00Z)	2 मिनट	range.endTime पर ट्रंकेट किया गया

एग्रीगेट की गई वैल्यू पर असर

समय के हिसाब से आखिरी विंडो की अवधि कम होती है. इसलिए, कम अवधि की वजह से, ट्रंकेट की गई बकेट में ऐडिटिव मेट्रिक (जैसे, कदमों की कुल संख्या या गिनती) कम होती हैं.

अगर कोई उपयोगकर्ता इस 12 मिनट की पूरी रेंज के दौरान, हर मिनट 100 कदमों की स्थिर रफ़्तार से चलता है, तो बकेट में ये कुल संख्याएं शामिल होंगी:

• बकेट 1 (10:00:00Z से 10:05:00Z) में 500 कदम रिकॉर्ड किए जाते हैं. इसका मतलब है कि पांच मिनट तक, हर मिनट 100 कदम चले गए.
• बकेट 2 (10:05:00Z से 10:10:00Z) में 500 कदम रिकॉर्ड किए जाते हैं. इसका मतलब है कि पांच मिनट तक हर मिनट 100 कदम चले गए.
• बकेट 3 (10:10:00Z से 10:12:00Z) में 200 कदम रिकॉर्ड किए जाते हैं. इसका मतलब है कि दो मिनट तक, हर मिनट 100 कदम चले गए.

बकेट 3 में 200 कदमों की कम संख्या, ट्रंकेट की गई विंडो की दो मिनट की अवधि की वजह से है, न कि उपयोगकर्ता की गतिविधि में गिरावट की वजह से. इस डेटा को प्लॉट या विश्लेषण करते समय, हर बकेट की सटीक अवधि का इस्तेमाल करके, संख्या को सामान्य करें. इससे उपयोगकर्ता गतिविधि में गुमराह करने वाली गिरावट को दिखाने से बचा जा सकता है.

तीसरी इमेज में, तीनों बकेट में रॉ एडिटिव स्टेप टोटल (countSum) की तुलना, अवधि के हिसाब से सामान्य की गई दरों से की गई है.

इमेज 3: ट्रंकेटेड रोलअप बकेट के लिए, अवधि के हिसाब से सामान्य की गई दरों की तुलना में, रॉ एडिटिव टोटल

एपीआई से मिली जानकारी का उदाहरण, जिसमें क्रम से लगाने की सुविधा दिखाई गई है

एपीआई, नतीजों को उल्टे क्रम में दिखाता है. इसलिए, काटी गई बकेट, दिखाई गई सूची में पहले एलिमेंट के तौर पर दिखती है:

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