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

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

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

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

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

टेबल: Google Health API में वर्कआउट के डेटा टाइप
डेटा टाइप उपलब्ध
कार्रवाइयां
दायरा
कसरत
dataType: exercise
filter parameter: exercise
रिकॉर्ड टाइप: सेशन

संगत डिवाइस

list, get, reconcile, create, update, batchDelete .activity_and_fitness.readonly
.activity_and_fitness.writeonly

कसरत के सेशन, exercise डेटा टाइप को कंटेनर के तौर पर इस्तेमाल करते हैं. वहीं, पहने जाने वाले डिवाइस, सेशन के दौरान ज़्यादा फ़्रीक्वेंसी वाली टेलीमेट्री को भी रिकॉर्ड करते हैं. Google Health API में, दिन के दौरान इकट्ठा किए गए टेलीमेट्री डेटा के ये टाइप सिर्फ़ पढ़ने के लिए होते हैं. इन्हें सीधे तौर पर अपने REST एंडपॉइंट से न तो बनाया जा सकता है और न ही इनमें बदलाव किया जा सकता है. REST API का इस्तेमाल करके वर्कआउट सेशन का डेटा लिखते समय, exercise डेटा पॉइंट के metricsSummary ऑब्जेक्ट में, वर्कआउट की एग्रीगेट मेट्रिक पास करें.

यहां दी गई टेबल में, exercise.metricsSummary में मौजूद खास जानकारी वाले फ़ील्ड को, रीड-ओनली इंट्राडे टेलीमेट्री डेटा टाइप से मैप किया गया है. इस डेटा टाइप के लिए, कसरत के समय की विंडो के लिए क्वेरी की जा सकती है:

खास जानकारी वाला फ़ील्ड (metricsSummary) इंट्राडे टेलीमेट्री डेटा टाइप का नाम एपीआई टेलीमेट्री डेटा टाइप आईडी (रीड-ओनली) फ़िल्टर फ़ील्ड (?filter=) OAuth के दायरे को पढ़ने की अनुमति ज़रूरी है
caloriesKcal शारीरिक गतिविधि में खर्च कैलोरी active-energy-burned active_energy_burned.interval.start_time activity_and_fitness.readonly
distanceMillimeters दूरी distance distance.interval.start_time activity_and_fitness.readonly
steps चरण steps steps.interval.start_time activity_and_fitness.readonly
averageHeartRateBeatsPerMinute धड़कन की दर heart-rate heart_rate.sample_time.physical_time health_metrics_and_measurements.readonly
activeZoneMinutes ऐक्टिव ज़ोन मिनट active-zone-minutes active_zone_minutes.interval.start_time activity_and_fitness.readonly

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

कसरत के सेशन

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

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

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

  • सेशन का समय (interval): पूरे वर्कआउट सेशन के शुरू होने का समय और खत्म होने का समय. साथ ही, उन समय पर चालू टाइमज़ोन ऑफ़सेट.
  • गतिविधि का टाइप (exerciseType): की गई गतिविधि की कैटगरी (जैसे, RUNNING, WALKING, BIKING या AEROBIC_WORKOUT). फ़िज़िकल ट्रेनिंग के सटीक टाइप की जानकारी दें.
  • डिसप्ले नेम (displayName): कसरत के सेशन का ऐसा नाम जो उपयोगकर्ता के लिए आसान हो. REST API की मदद से बनाए जाने पर, सर्वर exerciseType के लिए स्थानीय भाषा में डिसप्ले नेम भरता है. जैसे, RUNNING के लिए "Run".
  • कसरत की अवधि (activeDuration): कसरत की असल अवधि. इसमें कसरत के दौरान लिए गए ब्रेक शामिल नहीं होते. स्टैंडर्ड फ़ॉर्मैटिंग में Duration फ़ॉर्मैट का इस्तेमाल किया जाता है. उदाहरण के लिए, "1800s". सर्वर पर, activeDuration का हिसाब लगाने के लिए, सेशन interval में से exerciseEvents में मौजूद PAUSE/RESUME या AUTO_PAUSE/AUTO_RESUME इंटरवल को घटाया जाता है.

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

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 dataPoints एंडपॉइंट का इस्तेमाल करें.

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",
    "platform": "GOOGLE_WEB_API"
  },
  "exercise": {
    "interval": {
      "startTime": "2026-04-20T08:00:00Z",
      "startUtcOffset": "0s",
      "endTime": "2026-04-20T08:35:00Z",
      "endUtcOffset": "0s"
    },
    "exerciseType": "RUNNING",
    "activeDuration": "1800s",
    "metricsSummary": {
      "caloriesKcal": 380.0,
      "distanceMillimeters": 5000000.0,
      "steps": "6200",
      "averageHeartRateBeatsPerMinute": "148",
      "averagePaceSecondsPerMeter": 0.36
    },
    "exerciseEvents": [
      {
        "eventTime": "2026-04-20T08:15:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "PAUSE"
      },
      {
        "eventTime": "2026-04-20T08:20:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "RESUME"
      }
    ]
  }
}

जवाब

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/999298779973222220/dataTypes/exercise/dataPoints/3054085373369111216",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "application": {
        "googleWebClientId": "438076457939-example.apps.googleusercontent.com"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "exercise": {
      "interval": {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:35:00Z",
        "endUtcOffset": "0s"
      },
      "exerciseType": "RUNNING",
      "metricsSummary": {
        "caloriesKcal": 380,
        "distanceMillimeters": 5000000,
        "steps": "6200",
        "averagePaceSecondsPerMeter": 0.36,
        "averageHeartRateBeatsPerMinute": "148"
      },
      "exerciseMetadata": {},
      "displayName": "Run",
      "activeDuration": "1800s",
      "exerciseEvents": [
        {
          "eventTime": "2026-04-20T08:15:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "PAUSE"
        },
        {
          "eventTime": "2026-04-20T08:20:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "RESUME"
        }
      ],
      "updateTime": "2026-04-20T08:35:10.123456Z",
      "createTime": "2026-04-20T08:35:10.123456Z"
    }
  }
}

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

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

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

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

अनुरोध

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>

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

जीपीएस रूट और जगह की जानकारी को ट्रैक करने की सुविधा का इस्तेमाल करने के लिए, आपके ऐप्लिकेशन को इन 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

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

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

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

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

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

स्पीड और पेस का कैलकुलेशन

Google Health API, रफ़्तार और पेस का हिसाब लगाने के लिए स्टैंडर्ड फ़ॉर्मूले इस्तेमाल करता है:

  • स्पीड = distance / time(hour)
  • रफ़्तार = time(seconds) / distance

अनुरोध में बताया गया Accept-Language हेडर, दूरी की इकाई तय करता है.

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

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

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

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

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

जब आपके सर्वर को वेबहुक की सूचना मिलती है, तो उसमें अपडेट की गई कसरत का healthUserId और सिविल टाइम इंटरवल (civilIso8601TimeInterval) शामिल होता है. आपके सर्वर को 204 No Content के साथ सूचना को तुरंत स्वीकार करना चाहिए, पेलोड को एसिंक्रोनस तरीके से प्रोसेस करना चाहिए, और exercise.interval.civil_start_time फ़िल्टर का इस्तेमाल करके, मिलान किए गए exercise एंडपॉइंट से क्वेरी करनी चाहिए. ध्यान दें कि exercise सिर्फ़ civil_start_time के हिसाब से फ़िल्टर करने की सुविधा देता है:

GET https://health.googleapis.com/v4/users/healthUserId/dataTypes/exercise/dataPoints:reconcile?filter=exercise.interval.civil_start_time >= "2026-04-20T08:00:00" AND exercise.interval.civil_start_time < "2026-04-20T10:00:00"

सदस्यताएं सेट अप करने के बारे में जानने के लिए, वेबहुक सदस्यताएं देखें.

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

कसरत से जुड़ा पूरा अनुभव देने के लिए, exercise सेशन लिखते समय खास जानकारी वाली मेट्रिक शामिल करें. साथ ही, ज़्यादा जानकारी वाले चार्ट रेंडर करते समय, समयसीमा वाले फ़िल्टर का इस्तेमाल करके, रीड-ओनली टेलीमेट्री एंडपॉइंट के लिए क्वेरी करें.

कसरत की खास जानकारी वाली मेट्रिक सेव करना (पाथ सेव करना)

Google Health API में, पूरी हो चुकी कसरत का डेटा इंपोर्ट या सेव करते समय, exercise डेटा पॉइंट के metricsSummary ऑब्जेक्ट में, कसरत की कुल टेलीमेट्री मेट्रिक (steps, caloriesKcal, distanceMillimeters, averageHeartRateBeatsPerMinute, और averagePaceSecondsPerMeter) शामिल करें:

  • POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints

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

किसी खास सेशन के लिए वर्कआउट डैशबोर्ड या चार्ट बनाने के लिए, उस वर्कआउट के टाइम विंडो के लिए, टेलीमेट्री एंडपॉइंट से मिले डेटा को क्वेरी करें:

  1. civil_start_time फ़िल्टर का इस्तेमाल करके, exercise एंडपॉइंट से कसरत के सेशन का डेटा फ़ेच करें. इससे आपको interval और metricsSummary की जानकारी मिलेगी:

    GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints:reconcile?filter=exercise.interval.civil_start_time >= "2026-04-20T00:00:00" AND exercise.interval.civil_start_time < "2026-04-21T00:00:00"
  2. उस समयावधि के टेलीमेट्री एंडपॉइंट के बारे में क्वेरी करने के लिए, सेशन के interval.startTime और interval.endTime का इस्तेमाल करें.

  3. अगर exerciseMetadata.hasGps, true है, तो रास्ते के निर्देशांक डाउनलोड करने के लिए exportExerciseTcx को कॉल करें.