Google Health API की मदद से, वर्कआउट से जुड़े अनुभव डेवलप करना

Google Health API, exercise सेशन डेटा टाइप का इस्तेमाल करके, उपयोगकर्ता के वर्कआउट सेशन और कसरत के इतिहास को ट्रैक करता है. सेशन, एक कंटेनर की तरह काम करता है. इसमें गतिविधि का मेटाडेटा, रोकने और फिर से शुरू करने के इवेंट, लैप या स्प्लिट, और खास जानकारी देने वाले मेट्रिक बंडल होते हैं.

अपने ऐप्लिकेशन में वर्कआउट को पढ़ने, लिखने, और स्ट्रक्चर करने का तरीका जानें, ताकि उपयोगकर्ताओं को बेहतरीन अनुभव दिया जा सके.

डेटा टाइप, जो इस्तेमाल किए जा सकते हैं

यह एपीआई, कसरत और गतिविधि सेशन को ट्रैक करने के लिए इस डेटा टाइप के साथ काम करता है:

टेबल: Google Health API के वर्कआउट डेटा टाइप

डेटा टाइप   dataType   filter पैरामीटर	रिकॉर्ड टाइप	उपलब्ध कार्रवाइयां	दायरा	वेबबुक support	ट्रू ज़ीरो की सुविधा
एक्सरसाइज़   exercise   exercise	सेशन	list, get, reconcile, create, update, batchDelete	activity_and_fitness

मिलते-जुलते टेलीमेट्री डेटा टाइप

वर्कआउट सेशन के लिए, exercise डेटा टाइप का इस्तेमाल कंटेनर के तौर पर किया जाता है. हालांकि, सामान्य वर्कआउट ट्रैकर, सेशन के दौरान ज़्यादा फ़्रीक्वेंसी वाली टेलीमेट्री को लिखते और पढ़ते हैं. इन मेज़रमेंट (जैसे, धड़कन की दर या कदमों की संख्या) को उनके डेटा टाइप के हिसाब से पढ़ा या लिखा जाना चाहिए.

यहां दी गई टेबल में, metricsSummary डेटा टाइप के metricsSummary ऑब्जेक्ट में मौजूद फ़ील्ड को Google Health API के संबंधित रॉ टेलीमेट्री डेटा टाइप के साथ मैप किया गया है:exercise

खास जानकारी वाला फ़ील्ड (metricsSummary)	इंट्राडे टेलीमेट्री डेटा टाइप का नाम	एपीआई टेलीमेट्री डेटा टाइप आईडी
caloriesKcal	शारीरिक गतिविधि में खर्च हुई कैलोरी	active-energy-burned
distanceMillimeters	दूरी	distance
steps	चरण	steps
averageHeartRateBeatsPerMinute	धड़कन की दर	heart-rate
activeZoneMinutes	ऐक्टिव ज़ोन मिनट	active-zone-minutes

यहां दिए गए सेक्शन में, exercise डेटा टाइप की तकनीकी जानकारी दी गई है. इसमें REST के उदाहरण, जीपीएस रूट को मैनेज करने का तरीका, और इंटिग्रेशन के दिशा-निर्देश शामिल हैं.

कसरत के सेशन

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

सेशन के एट्रिब्यूट

एक्सरसाइज़ के डेटा पॉइंट को स्ट्रक्चर करते समय, इन मुख्य कॉम्पोनेंट की पुष्टि करें:

• सेशन का समय (interval): पूरे वर्कआउट सेशन के शुरू और खत्म होने का समय. साथ ही, उस समय के हिसाब से टाइमज़ोन ऑफ़सेट.
• गतिविधि का टाइप (exerciseType): की गई गतिविधि की कैटगरी (जैसे कि RUNNING, WALKING, BIKING या AEROBIC_WORKOUT). शारीरिक ट्रेनिंग के सटीक टाइप की जानकारी दें.
• दिखने वाला नाम (displayName): यह कसरत के सेशन का ऐसा नाम होता है जिसे आसानी से समझा जा सके. उदाहरण के लिए, "दोपहर की ट्रेल रन".
• कसरत में लगा कुल समय (activeDuration): कसरत में लगा कुल समय. इसमें, रोके गए इंटरवल शामिल नहीं होते. स्टैंडर्ड फ़ॉर्मैटिंग में Duration फ़ॉर्मैट का इस्तेमाल किया जाता है (उदाहरण के लिए, "1800s").

खास जानकारी वाली मेट्रिक

metricsSummary नेस्ट किए गए ऑब्जेक्ट में, कसरत के सेशन की पूरी अवधि के लिए कैलकुलेट की गई कुल और औसत मेट्रिक शामिल होती हैं:

• caloriesKcal: कसरत के दौरान खर्च की गई कुल ऐक्टिव कैलोरी. इसे किलोकैलोरी (kcal) में मापा जाता है.
• distanceMillimeters: तय की गई कुल दूरी, जिसे मिलीमीटर में मापा जाता है, ताकि सभी इकाइयों में सटीक जानकारी बनी रहे.
• steps: कसरत के दौरान चले गए कुल कदम.
• averageHeartRateBeatsPerMinute: सेशन के ऐक्टिव मिनट के दौरान, उपयोगकर्ता की औसत धड़कन की दर.
• activeZoneMinutes: कसरत के दौरान हासिल किए गए कुल ऐक्टिव ज़ोन मिनट.
• averageSpeedMillimetersPerSecond: मिलीमीटर प्रति सेकंड में, चलने की औसत रफ़्तार.
• averagePaceSecondsPerMeter: सेशन के ऐक्टिव मिनट के दौरान औसत रफ़्तार, जिसे सेकंड प्रति मीटर के हिसाब से मापा जाता है.
• elevationGainMillimeters: सेशन के दौरान कुल एलिवेशन गेन.

लैप और स्प्लिट

लैप वाली कसरतों (जैसे, ट्रैक पर दौड़ना या पूल में तैरना) के लिए, splitSummaries का इस्तेमाल करें.

हर स्प्लिट में यह जानकारी शामिल होती है:

• किसी खास startTime और endTime.
• activeDuration, लैप का सही समय दिखाता है.
• metricsSummary, जिसे सिर्फ़ उस सेगमेंट के लिए स्कोप किया गया हो.
• स्प्लिट की सीमाओं को तय करने के लिए splitType (जैसे, DISTANCE, DURATION या MANUAL).

कसरत वाले इवेंट

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

हर इवेंट में टाइमस्टैंप (eventTime) और टाइप शामिल होता है:

• START / STOP: इससे यह पता चलता है कि उपयोगकर्ता ने रिकॉर्डिंग कब शुरू की और कब बंद की.
• PAUSE / RESUME: इससे पता चलता है कि सेशन को मैन्युअल तरीके से कब रोका गया या फिर से शुरू किया गया.
• AUTO_PAUSE / AUTO_RESUME: इससे पता चलता है कि सेंसर की वजह से, वीडियो अपने-आप रुक गया है या फिर से चलने लगा है.

कसरत के सेशन का डेटा सेव करने की अनुमति

वर्कआउट सेशन बनाने, अपडेट करने या इंपोर्ट करने के लिए, exercise डेटा टाइप कलेक्शन में एक डेटा पॉइंट लिखें. create डेटा पॉइंट एंडपॉइंट का इस्तेमाल करें.

REST के उदाहरण के तौर पर दिखाया गया डेटा

यहां दिए गए उदाहरण में, POST तरीके का इस्तेमाल करके, वर्कआउट सेशन लिखने का तरीका दिखाया गया है:

अनुरोध

POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "dataSource": {
    "recordingMethod": "ACTIVELY_MEASURED"
  },
  "exercise": {
    "interval": {
      "startTime": "2026-04-20T08:00:00Z",
      "startUtcOffset": "0s",
      "endTime": "2026-04-20T08:35:00Z",
      "endUtcOffset": "0s"
    },
    "exerciseType": "RUNNING",
    "displayName": "Morning Trail Run",
    "activeDuration": "1800s",
    "metricsSummary": {
      "caloriesKcal": 380.0,
      "distanceMillimeters": 5000000.0,
      "steps": "6200",
      "averageSpeedMillimetersPerSecond": 2777.78,
      "averagePaceSecondsPerMeter": 360.0,
      "averageHeartRateBeatsPerMinute": "148",
      "activeZoneMinutes": "30"
    },
    "exerciseMetadata": {
      "hasGps": true
    },
    "exerciseEvents": [
      {
        "eventTime": "2026-04-20T08:15:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "PAUSE"
      },
      {
        "eventTime": "2026-04-20T08:20:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "RESUME"
      }
    ],
    "splitSummaries": [
      {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:15:00Z",
        "endUtcOffset": "0s",
        "splitType": "DISTANCE",
        "metricsSummary": {
          "distanceMillimeters": 2500000.0,
          "caloriesKcal": 190.0
        }
      }
    ]
  }
}

जवाब

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
    "name": "users/me/dataTypes/exercise/dataPoints/morning-trail-run-123456",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "application": {
        "packageName": "com.example.workoutapp"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "exercise": {
      "interval": {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:35:00Z",
        "endUtcOffset": "0s"
      },
      "exerciseType": "RUNNING",
      "displayName": "Morning Trail Run",
      "activeDuration": "1800s",
      "metricsSummary": {
        "caloriesKcal": 380.0,
        "distanceMillimeters": 5000000.0,
        "steps": "6200",
        "averageSpeedMillimetersPerSecond": 2777.78,
        "averagePaceSecondsPerMeter": 360.0,
        "averageHeartRateBeatsPerMinute": "148",
        "activeZoneMinutes": "30"
      },
      "exerciseMetadata": {
        "hasGps": true
      },
      "exerciseEvents": [
        {
          "eventTime": "2026-04-20T08:15:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "PAUSE"
        },
        {
          "eventTime": "2026-04-20T08:20:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "RESUME"
        }
      ],
      "splitSummaries": [
        {
          "startTime": "2026-04-20T08:00:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-04-20T08:15:00Z",
          "endUtcOffset": "0s",
          "activeDuration": "900s",
          "splitType": "DISTANCE",
          "metricsSummary": {
            "distanceMillimeters": 2500000.0,
            "caloriesKcal": 190.0
          }
        }
      ]
    }
  }
}

जीपीएस रूट और जगह की जानकारी ट्रैक करने की सुविधा

यह एपीआई, सेशन की बुनियादी खास जानकारी को सीधे exercise डेटा पॉइंट में सेव करता है. हालांकि, यह जगह की पूरी जानकारी और जीपीएस रूट के कोऑर्डिनेट को अलग स्ट्रीम के तौर पर मैनेज करता है.

आउटडोर सेशन के लिए, रास्ते का पूरा डेटा डाउनलोड करने के लिए, exportExerciseTcx कस्टम तरीके को कॉल करें. यह एंडपॉइंट, इंडस्ट्री स्टैंडर्ड Training Center XML (TCX) फ़ॉर्मैट में रूट की जानकारी दिखाता है.

जीपीएस रूट एक्सपोर्ट करना

अनुरोध

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints/exercise-data-point-id:exportExerciseTcx?alt=media
Authorization: Bearer access-token

जवाब

Content-Type: application/tcx+xml और हेडर वाला एचटीटीपी पेलोड, जो ब्राउज़र को फ़ाइल सेव करने का निर्देश देता है.

<?xml version="1.0" encoding="UTF-8"?>
<TrainingCenterDatabase xmlns="http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2">
  <Activities>
    <Activity Sport="Running">
      <Id>2026-04-20T08:00:00Z</Id>
      <Lap StartTime="2026-04-20T08:00:00Z">
        <TotalTimeSeconds>1800</TotalTimeSeconds>
        <DistanceMeters>5000</DistanceMeters>
        <Calories>380</Calories>
        <Intensity>Active</Intensity>
        <TriggerMethod>Manual</TriggerMethod>
        <Track>
          <Trackpoint>
            <Time>2026-04-20T08:00:00Z</Time>
            <Position>
              <LatitudeDegrees>37.7749</LatitudeDegrees>
              <LongitudeDegrees>-122.4194</LongitudeDegrees>
            </Position>
            <AltitudeMeters>15.0</AltitudeMeters>
            <DistanceMeters>0.0</DistanceMeters>
          </Trackpoint>
        </Track>
      </Lap>
    </Activity>
  </Activities>
</TrainingCenterDatabase>

अहम जानकारी: ओरिजनल TCX फ़ाइल डाउनलोड करने के लिए, आपको अनुरोध किए गए यूआरएल में `?alt=media` जोड़ना होगा. ऐसा न होने पर, सर्वर स्टैंडर्ड JSON एनवलप के साथ जवाब देता है.

ज़रूरी स्कोप और जगह की जानकारी

जीपीएस रास्तों और जगह की जानकारी को ट्रैक करने के लिए, डेटा को पढ़ने या लिखने के लिए, अपने ऐप्लिकेशन के ऐक्सेस टोकन में ये OAuth स्कोप का अनुरोध करें:

• पढ़ने का ऐक्सेस: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
• बदलाव करने का ऐक्सेस: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
• पढ़ने का ऐक्सेस: https://www.googleapis.com/auth/googlehealth.location.readonly

अगर अनुमति देने वाले हेडर में ज़रूरी स्कोप मौजूद नहीं है, तो Google Health API, अनुमति से जुड़ी गड़बड़ी दिखाता है.

दिशा-निर्देश

अपने ऐप्लिकेशन में कसरत की ट्रैकिंग को इंटिग्रेट करते समय, डिज़ाइन और लागू करने से जुड़े इन दिशा-निर्देशों का पालन करें.

ऐक्टिव रहने की अवधि बनाम कुल अवधि

रफ़्तार या पेस मेट्रिक का हिसाब लगाने के लिए, हमेशा activeDuration का इस्तेमाल करें. startTime और endTime के बीच के अंतर का इस्तेमाल न करें. इससे रुके हुए इंटरवल की वजह से, आपकी मेट्रिक में गड़बड़ी नहीं होती.

उदाहरण के लिए, अगर कोई उपयोगकर्ता 08:00 बजे कसरत शुरू करता है और 08:35 बजे खत्म करता है, तो कसरत की कुल अवधि 2,100 सेकंड होगी. अगर उपयोगकर्ता ने कसरत को 5 मिनट (300 सेकंड) के लिए रोक दिया है, तो activeDuration को "1800s" (2,100 - 300) पर सेट करें. एपीआई, औसत की गिनती करने के लिए सक्रिय अवधि का इस्तेमाल करता है. इसमें कुल दूरी को 2,100 सेकंड के बजाय 1,800 सेकंड से भाग दिया जाता है.

जगह की जानकारी का अनुरोध पहले ही कर लें

अगर आपका ऐप्लिकेशन, कसरत के रूट मैप करता है, तो गतिविधि और फ़िटनेस के स्कोप के साथ-साथ, जगह की जानकारी की अनुमतियों और Google Health location स्कोप का अनुरोध करें. उपयोगकर्ताओं को बताएं कि जीपीएस की मदद से की जाने वाली कसरत की समीक्षा करते समय, आपके ऐप्लिकेशन को जगह की जानकारी के स्कोप की ज़रूरत क्यों होती है.

जब आपका ऐप्लिकेशन, जगह की जानकारी के स्कोप (https://www.googleapis.com/auth/googlehealth.location.readonly) का अनुरोध करता है, तो Google OAuth, उपयोगकर्ता को सहमति लेने का प्रॉम्प्ट दिखाता है. अपने उपयोगकर्ताओं को बताएं कि रूट ओवरले रेंडर करने और जीपीएस ट्रैक फ़ाइलें (टीसीएक्स) एक्सपोर्ट करने के लिए, यह अनुमति ज़रूरी है. अगर कोई उपयोगकर्ता गतिविधि का स्कोप ऐक्सेस करने की अनुमति देता है, लेकिन जगह की जानकारी की अनुमति नहीं देता है, तो exportExerciseTcx में अनुमति से जुड़ी गड़बड़ी दिखती है. हालांकि, metricsSummary में अब भी सेशन एग्रीगेट ऐक्सेस किए जा सकते हैं.

वेबहुक का इस्तेमाल करके रीयल-टाइम में सिंक करना

exercise डेटा टाइप की सदस्यता लें, ताकि कसरत का नया डेटा उपलब्ध होने पर, वेबहुक का इस्तेमाल करके अपने बैकएंड को सूचना दी जा सके. इससे आपको कसरत के बाद के अनुभव को रीयल टाइम में ट्रिगर करने की सुविधा मिलती है.

जब आपके सर्वर को वेबुक सूचना मिलती है, तो उसमें healthUserId और वर्कआउट का तय समय शामिल होता है. आपके सर्वर को सूचना को एसिंक्रोनस तरीके से प्रोसेस करना चाहिए. इसके बाद, /users/me/dataTypes/exercise/dataPoints एंडपॉइंट से नए exercise डेटा पॉइंट का अनुरोध करना चाहिए. सदस्यताएं सेट अप करने के तरीके के बारे में जानकारी के लिए, वेबहुक सदस्यताएं देखें.

मेट्रिक में एक जैसा डेटा बनाए रखना

कसरत का पूरा अनुभव देने के लिए, आपके ऐप्लिकेशन को exercise सेशन के साथ-साथ, ज़्यादा फ़्रीक्वेंसी वाले टेलीमेट्री डेटा पॉइंट को सिंक करना होगा. इससे यह पक्का होता है कि उपयोगकर्ता के रोज़ के कुल डेटा, पुराने रुझानों, और जानकारी वाले चार्ट में कोई अंतर न हो.

टेलीमेट्री और सेशन सिंक करना (राइट पाथ)

Google Health API में कसरत की पूरी जानकारी इंपोर्ट करते समय या लिखते समय, कई चरणों वाला राइट पैटर्न लागू करें:

1. सेशन की जानकारी लिखना: POST /users/me/dataTypes/exercise/dataPoints पर डेटा पॉइंट पोस्ट करके, खास जानकारी वाले इवेंट को फ़ाइल करें.
2. टाइम-सीरीज़ इंटरवल लिखें: कसरत के दौरान लॉग किए गए विस्तृत डेटा पॉइंट को एक साथ लिखें. उदाहरण के लिए, हर मिनट के हिसाब से कदमों की संख्या या कैलोरी बर्न करने के इंटरवल. इन डेटा पॉइंट को उनके कलेक्शन में लिखें:
   • POST /users/me/dataTypes/steps/dataPoints
   • POST /users/me/dataTypes/active-energy-burned/dataPoints
   • POST /users/me/dataTypes/heart-rate/dataPoints

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

चार्ट के लिए क्वेरी का ज़्यादा जानकारी वाला डेटा (रीड पाथ)

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

1. सेशन की खास जानकारी के बारे में क्वेरी करना: कॉल /users/me/dataTypes/exercise/dataPoints करके, कसरत की पूरी जानकारी और फ़ाइनल metricsSummary पाएं.
2. चार्ट मेट्रिक फ़ेच करना: कसरत की interval.startTime और interval.endTime की जांच करें. उस खास समयावधि के लिए, टेलीमेट्री कलेक्शन को सेकंडरी GET कॉल करें:
   • GET /users/me/dataTypes/heart-rate/dataPoints?startTime=2026-04-20T08:00:00Z&endTime=2026-04-20T08:35:00Z
3. जीपीएस रूट फ़ेच करें: अगर सेशन के मेटाडेटा से पता चलता है कि जीपीएस डेटा मौजूद है (exerciseMetadata.hasGps true है), तो रूट के निर्देशांक डाउनलोड करने के लिए, exportExerciseTcx हेल्पर तरीके का इस्तेमाल करें.