פיתוח חוויות אימון באמצעות Google Health API

‫Google Health API עוקב אחרי סשנים של אימונים והיסטוריית אימונים של משתמשים באמצעות exercise סוג הנתונים של הסשן. סשן הוא קונטיינר שכולל מטא-נתונים של פעילות, אירועי השהיה והמשך, הקפות או זמני ביניים ומדדי סיכום.

כך תוכלו להבין איך לקרוא, לכתוב ולבנות אימוני כושר באפליקציה כדי לספק למשתמשים את חוויית השימוש הטובה ביותר.

סוגי נתונים נתמכים

ה-API תומך בסוג הנתונים הבא למעקב אחרי אימונים וסשנים של פעילות:

טבלה: סוגי נתונים של אימונים ב-Google Health API

סוג הנתונים	פעולות זמינות	היקף
תרגיל ‫dataType: exercise filter parameter: exercise סוג הרשומה: סשן תמיכה ב-Webhook מדריך לאימונים מכשירים תואמים Fitbit Air Fitbit Alta Fitbit Alta HR Fitbit Blaze Fitbit Charge 2 Fitbit Charge 3 Fitbit Charge 4 Fitbit Charge 5 ‫Fitbit Charge 6 Fitbit Flex 2 Fitbit Inspire Fitbit Inspire 2 Fitbit Inspire 3 Fitbit Inspire HR Fitbit Ionic Fitbit Luxe ‫Fitbit MobileTrack Pixel Watch Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense ‫Fitbit Sense 2 Fitbit Versa Fitbit Versa 2 Fitbit Versa 3 ‫Fitbit Versa 4 Fitbit Versa Lite	list, get, reconcile, create, update, batchDelete	.activity_and_fitness.readonly .activity_and_fitness.writeonly

סוגים של נתוני טלמטריה שקשורים לחיפוש

סשנים של אימונים משתמשים בסוג הנתונים exercise כמאגר, אבל בדרך כלל מכשירי מעקב אחר אימונים כותבים וקוראים טלמטריה מפורטת בתדירות גבוהה במהלך הסשן. את המדדים האלה (כמו דופק או מספר צעדים) צריך לקרוא או לכתוב באמצעות סוגי הנתונים המתאימים שלהם.

בטבלה הבאה מפורטים השדות באובייקט metricsSummary של סוג הנתונים exercise, והסוגים המתאימים של נתוני טלמטריה גולמיים ב-Google Health API:

שדה סיכום (metricsSummary)	שם סוג הנתונים של טלמטרייה במהלך היום	מזהה סוג נתוני טלמטריה של API
caloriesKcal	אנרגיה שנשרפה בזמן פעילות	active-energy-burned
distanceMillimeters	מרחק	distance
steps	שלבים	steps
averageHeartRateBeatsPerMinute	דופק	heart-rate
activeZoneMinutes	דקות טווח דופק	active-zone-minutes

בקטעים הבאים מפורטים פרטים טכניים על סוג הנתונים exercise, כולל דוגמאות לייצוג REST, טיפול במסלול GPS והנחיות לשילוב.

אימונים

לכתוב פעילויות יומיומיות או אימונים כ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 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"
  },
  "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
          }
        }
      ]
    }
  }
}

מסלולים לפי GPS ומעקב אחר מיקום

ה-API שומר סיכומים בסיסיים של סשנים ישירות בנקודת הנתונים של exercise, אבל מטפל בהיסטוריית מיקומים מפורטת ובקואורדינטות של מסלולי GPS כמקור נתונים נפרד.

כדי להוריד את נתוני המסלול המפורטים של אימון בחוץ, מפעילים את השיטה exportExerciseTcx בהתאמה אישית. נקודת הקצה הזו מחזירה את המסלול בפורמט XML של מרכז האימונים (TCX), שהוא פורמט סטנדרטי בתעשייה.

ייצוא מסלול GPS

בקשה

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

תשובה

מטען ייעודי (payload) של HTTP עם הכותרות 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` לכתובת ה-URL של הבקשה. אחרת, השרת מגיב עם מעטפת JSON רגילה.

היקפים ומיקום נדרשים

כדי להשתמש בתכונה מסלולי GPS ומעקב מיקום, האפליקציה צריכה לבקש את היקפי ההרשאות הבאים של 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 שניות. אם המשתמש הפסיק את האימון למשך 5 דקות (300 שניות), צריך להגדיר את activeDuration ל-"1800s" (2,100 – 300). ה-API משתמש במשך הפעילות כדי לחשב ממוצעים, ומחלק את המרחק הכולל ב-1,800 שניות במקום ב-2,100.

חישוב המהירות והקצב

ב-Google Health API נעשה שימוש בנוסחאות סטנדרטיות לחישוב המהירות והקצב:

• מהירות = distance / time(hour)
• קצב = time(seconds) / distance

הכותרת Accept-Language שצוינה בבקשה קובעת את יחידת המרחק.

בקשת מיקום מוקדם

אם האפליקציה ממפה מסלולים של אימונים, צריך לבקש הרשאות מיקום ואת היקף ההרשאות של Google Health‏ location בנוסף להיקף ההרשאות של פעילות וכושר. עליך להסביר למשתמשים למה האפליקציה שלך דורשת את היקף המיקום כשבודקים אימונים עם GPS.

כשהאפליקציה מבקשת את היקף ההרשאות למיקום (https://www.googleapis.com/auth/googlehealth.location.readonly), מערכת Google OAuth מציגה למשתמש בקשת הסכמה. להסביר למשתמשים שההרשאה הזו נחוצה כדי להציג שכבות-על של מסלולים ולייצא קובצי מעקב GPS ‏(TCX). אם משתמש מעניק הרשאה להיקף הפעילות אבל דוחה את הרשאת המיקום, פונקציית exportExerciseTcx מחזירה שגיאת הרשאה, אבל עדיין אפשר לגשת לנתוני סשן מצטברים ב-metricsSummary.

סנכרון בזמן אמת באמצעות Webhooks

כדי לקבל הודעה בבק-אנד באמצעות webhook כשנתוני אימון כושר חדשים זמינים, צריך להירשם לסוג הנתונים exercise. כך תוכלו להפעיל חוויות אחרי האימון בזמן אמת.

כשהשרת מקבל התראה על webhook, היא מכילה את healthUserId ואת מרווח הזמן הפיזי הספציפי של האימון. השרת שלכם צריך לעבד את ההתראה באופן אסינכרוני ואז לשלוח בקשה לנקודת הקצה /users/me/dataTypes/exercise/dataPoints כדי לקבל את נקודה על הגרף exercise חדש. הוראות להגדרת מינויים זמינות במאמר בנושא מינויים ל-Webhook.

שמירה על מדדים עקביים

כדי לספק חוויית אימון מלאה, האפליקציה צריכה לסנכרן נקודות נתונים טלמטריות בתדירות גבוהה לצד נתוני הפעילות הכוללים ב-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. שליפת מסלולי GPS: אם מטא-הנתונים של הסשן מציינים שקיימים נתוני GPS (הערך של exerciseMetadata.hasGps הוא true), מפעילים את שיטת העזר exportExerciseTcx כדי להוריד את קואורדינטות המסלול.