בקטע "מפרט ה-API" יש סקירה כללית מפורטת של הרכיבים הטכניים שחיוניים לשילוב עם הפלטפורמה, כולל היקפי הרשאות, הגדרות של סוגי נתונים ומבנים של נקודות קצה. ה-API הזה מייצג התפתחות אסטרטגית של Fitbit Web API הקודם, שנבנה מחדש על תשתית מודרנית כדי להבטיח חוויית פיתוח יציבה ועקבית יותר.
היקפים
אתם צריכים לעדכן את בקשת ההרשאה כדי להשתמש בהיקפי ההרשאות של Google Health API. היקפי ההרשאות קובעים אם האפליקציה תומכת בפעולות קריאה או כתיבה. פועלים לפי ההוראות להטמעת היקף ההרשאות, שבהן מפורט איך לבקש רק את היקפי ההרשאות הנדרשים, להגדיר גישת כתיבה רק כששולחים נתונים ולטפל בהסכמה חלקית בצורה חלקה.
היקפי ההרשאות של Google Health API הם כתובת URL מסוג HTTP שמתחילה ב-https://www.googleapis.com/auth/googlehealth.{scope}. לדוגמה, https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly.
מיפוי היקף ההרשאות
ככה היקפי ההרשאות של Fitbit Web API ממופים להיקפי ההרשאות של Google Health API:
| היקפי ההרשאות של Fitbit Web API | היקפי ההרשאות של Google Health API |
|---|---|
| פעילות | .activity_and_fitness.readonly
.activity_and_fitness.writeonly |
| blood_glucose | .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly |
| cardio_fitness | .activity_and_fitness.readonly
.activity_and_fitness.writeonly |
| אלקטרוקרדיוגרמה | .ecg.readonly
|
| קצב הלב | .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly |
| irregular_rhythm_notifications | .irn.readonly
|
| location | .location.readonly
|
| תזונה | .nutrition.readonly
.nutrition.writeonly |
| oxygen_saturation | .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly |
| פרופיל | .profile.readonly
.profile.writeonly |
| respiratory_rate | .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly |
| הגדרות | .settings.readonly
.settings.writeonly |
| שינה | .sleep.readonly
.sleep.writeonly |
| טמפרטורה | .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly |
| משקל | .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly |
סוגי נתונים
ברשימה הבאה מפורטים סוגי הנתונים של Google Health API ואיך הם ממופים ל-Fitbit Web API.
| סוג הנתונים של Fitbit Web API | סוג הנתונים של Google Health APIdataType |
תיאור |
|---|---|---|
| קלוריות בפעילות | אנרגיה פעילה שנשרפהactive-energy-burned
|
מייצג את הקלוריות שנשרפו בזמן פעילות, כולל ה-BMR בתקופות האלה. ב-Google Health API, אפשר לשחזר את הנתון הזה על ידי הוספת ה-BMR לסוג הנתונים active-energy-burned (שעוקב רק אחרי שריפת הקלוריות בפעילות, לא כולל קצב חילוף החומרים הבסיסי). |
| דקות טווח דופק | דקות טווח דופקactive-zone-minutes
|
|
| מכיל שינויים ברמות הפעילות של המשתמש | רמת הפעילותactivity-level
|
מתעד את רמת הפעילות של המשתמש (למשל, יושבני או פעיל) לאורך פרק זמן מסוים. |
| גובה | Altitudealtitude
|
|
פעילות caloriesBMR |
אנרגיה בסיסית שנשרפהbasal-energy-burned
|
הקלוריות שנשרפו כתוצאה מקצב חילוף החומרים הבסיסי (BMR) במהלך תקופה מסוימת. |
| רמת הסוכר בדם | רמת סוכר בדםblood-glucose
|
|
| אחוז השומן בגוף | אחוז שומן בגוףbody-fat
|
|
caloriesOut בכל טווח דופק |
קלוריות בטווח הדופקcalories-in-heart-rate-zone
|
|
| טמפרטורה (ליבה) | טמפרטורת הגוףcore-body-temperature
|
|
| סיכום HRV | שונות קצב הלב היומיתdaily-heart-rate-variability
|
|
| סיכום הסטורציה | רמת החמצן בדם ביוםdaily-oxygen-saturation
|
סיכום יומי של נתונים סטטיסטיים לגבי רמת החמצן בדם (SpO2) שמחושבים על סמך מדידות שינה מאומתות. |
| הדופק במנוחה | הדופק היומי במנוחהdaily-resting-heart-rate
|
|
| טמפרטורת העור | סטיות יומיות בטמפרטורת השינהdaily-sleep-temperature-derivations
|
|
| מרחק | מרחקdistance
|
|
| אק"ג (ECG) | אק"ג (ECG)electrocardiogram
|
|
| פעילות מוקלטת | פעילות גופניתexercise
|
אימונים או סשנים של פעילות גופנית שתועדו, כולל זמני התחלה וסיום, סוגי פעילויות ומדדי סשנים. |
| קומות | קומותfloors
|
|
| אוכל | אוכלfood
|
|
| יחידת מידה של מזון | יחידת מידה של מזוןfood-measurement-unit
|
|
| דופק | דופקheart-rate
|
|
| HRV במהלך היום | שונות קצב הלבheart-rate-variability
|
|
| התראות על הפרעת קצב (IRN) | התראות על הפרעת קצב (AFib)irregular-rhythm-notification
|
|
| יומן האוכל | יומן תזונהnutrition-log
|
|
| סטורציה במהלך היום | רמת החמצן בדםoxygen-saturation
|
הפונקציה מחזירה רק מדידות SpO2 מאומתות ברמת הדקה, ולא כוללת קריאות שסומנו כלא תקינות בגלל ארטיפקטים של תנועה או רמת סמך נמוכה של החיישן. מכיוון ש-Fitbit Web API החריג רק את ערך הזקיף של 50%, Google Health API מחזיר פחות נקודות על הגרף לאותו טווח תאריכים. פרטים נוספים זמינים במאמר סינון רמת החמצן בדם. |
| ערך VO2 Max כשהמשתמש רץ | ריצה – צריכת חמצן מרבית (VO2 max)run-vo2-max
|
|
| סדרת זמני פעילות: דקות ללא פעילות | תקופת חוסר פעילותsedentary-period
|
|
| שינה | שינהsleep
|
|
| שלבים | שלביםsteps
|
|
| סדרת זמנים של פעילות: חתירות בשחייה | נתוני בריכות שחייהswim-lengths-data
|
|
פעילות caloriesOut |
סה"כ קלוריותtotal-calories
|
המספר הכולל של קלוריות שנשרפו על ידי משתמש במהלך פרק זמן מסוים, כולל קצב חילוף החומרים הבסיסי (BMR) והאנרגיה הפעילה שנשרפה. |
| ערך VO2 Max | צריכת החמצן המרבית (VO2 max)vo2-max
|
|
| משקל | משקלweight
|
חישובים
המיפויים והכללים ב-Google Health API שונים מאלה שב-Fitbit Web API.
סינון לפי רמת החמצן בדם
כששולחים שאילתה לגבי רמת החמצן בדם (oxygen-saturation) ברמת הדקה, Google Health API מחיל סינון מחמיר יותר של תקינות הנתונים מאשר Fitbit Web API הקודם:
- בגרסאות הקודמות של Fitbit Web API (גרסה 1 וגרסה 3) הוחרגו רק דגימות SpO2 עם ערך זקיף של 50%.
- Google Health API (גרסה 4) לא כולל דגימות SpO2 שסומנו כלא תקינות על ידי אלגוריתם האימות. דקה מסומנת כלא תקינה כשתנועת הזרוע או התאמה רופפת לפרק כף היד גורמות לאות של החיישן האופטי להיות לא אמין, כשציון המהימנות יורד מתחת ל-50%, במהלך 3 הדקות מיד לפני ואחרי קריאה לא תקינה, או כשפרק זמן תקין נמשך פחות מ-4 דקות רצופות.
מכיוון ש-Google Health API מסיר את כל המדידות הלא חוקיות ולא רק את ערך הזקיף של 50%, הוא מחזיר פחות oxygen-saturation נקודות על הגרף מאשר Fitbit Web API לאותו טווח תאריכים, וצפויים פערים בכיסוי של דקה אחר דקה. הקריאות שמוחזרות ברמת הדקה תואמות לנקודות הנתונים המאומתות שמשמשות לחישוב סיכום השינה של המשתמש ב-daily-oxygen-saturation. מידע נוסף זמין במאמר סינון SpO2 ברמת הדקה ותוקף הנתונים.
רמת הפעילות, MET וספי הצעדים
ב-Google Health API, רמת הפעילות של המשתמש בכל דקה נגזרת מהשווה ערך מטבולי (MET) ומספירת הצעדים שלו.
| רמת הפעילות | מכשירי דופק | מכשירים שלא מודדים דופק |
|---|---|---|
| לא פעיל | ≤ 1.5 MET | ≤ 1.5 MET |
| פעילות קלה | > 1.5 MET ו-≤ 4.2 MET | > 1.5 MET ו-<= 3.5 MET |
| פעילות בינונית | > 4.2 יחידות MET ו-< 6.0 יחידות MET (אלא אם מתקיימים התנאים של פעילות רבה) |
> 3.5 יחידות MET ו-< 6.0 יחידות MET (אלא אם מתקיימים התנאים של פעילות רבה) |
| פעילות רבה | 6.0 יחידות MET או יותר, או 5.0 יחידות MET או יותר עם קצב של 150 צעדים לדקה או יותר | 6.0 יחידות MET או יותר, או 5.0 יחידות MET או יותר עם קצב של 150 צעדים לדקה או יותר |
דקות הפעילות מורכבות משילוב של דקות MODERATELY_ACTIVE ודקות VERY_ACTIVE. עם זאת, דקה פעילה נספרת רק אם היא מתרחשת במהלך רצף של 10 דקות לפחות, עם מרווחים של 2 דקות לכל היותר של פעילות נמוכה יותר.
דקות של חוסר פעילות ושינה
דקות של חוסר פעילות לא כוללות את זמן השינה. בסיכומים היומיים, דקות המנוחה מחושבות על ידי הפחתת דקות השינה ודקות הפעילות (פעילות קלה, פעילות מתונה ופעילות נמרצת) מסך הדקות ביום (1,440 דקות):
Sedentary Minutes = 1440 - Sleep Minutes - Lightly Active Minutes -
Moderately Active Minutes - Very Active Minutes
מדד מסת הגוף (BMI)
ב-Google Health API אין סוג נתונים מובנה של BMI, ולכן האפליקציות צריכות לחשב את מדד מסת הגוף בצד הלקוח באמצעות רשומות של גובה ומשקל:
- אחזור משקל המשתמש בגרמים מהשדה
weightGramsבסוג הנתונים משקל. ממירים את הערך הזה לקילוגרמים (מחלקים ב-1,000) או לפאונדים (מחלקים ב-453.59237). - אחזור הגובה של המשתמש במילימטרים מהשדה
heightMillimetersבסוג הנתונים גובה. ממירים את הערך הזה למטרים (מחלקים ב-1,000) או לאינצ'ים (מחלקים ב-25.4). - כדי לחשב את ערך ה-BMI, משתמשים באחת מהנוסחאות הבאות:
- נוסחת המדד:
BMI = weight (kg) / [height (m)]^2 - נוסחה אימפריאלית:
BMI = (weight (lbs) / [height (in)]^2) * 703
- נוסחת המדד:
ערכי ה-BMI שמתקבלים תואמים לקטגוריות הבאות:
| קטגוריית משקל | טווח BMI |
|---|---|
| תת-משקל | פחות מ-18.5 |
| משקל תקין | 18.5 עד 24.9 |
| עודף משקל | 25 עד 29.9 |
| השמנת יתר | 30 ומעלה |
קצב חילוף החומרים הבסיסי (BMR)
קצב חילוף החומרים הבסיסי (BMR) הוא המספר המינימלי של קלוריות שנדרשות לתפקודים בסיסיים של הגוף במנוחה. מכיוון ש-Google Health API לא חושף סוג נתונים מובנה של BMR, האפליקציות צריכות לחשב אותו בצד הלקוח באמצעות נוסחת האריס-בנדיקט. מידע נוסף זמין במאמר על משוואת האריס-בנדיקט בוויקיפדיה.
כדי לבצע את החישוב הזה:
- אחזרו את משקל המשתמש בגרמים מהשדה
weightGramsבסוג הנתונים משקל והמירו לקילוגרמים (חלקו ב-1,000). כדי להמיר פאונד לקילוגרם, מחלקים ב-2.2. - אחזרו את גובה המשתמש במילימטרים מהשדה
heightMillimetersבסוג הנתונים גובה והמירו לסנטימטרים (חלקו ב-10). כדי להמיר אינצ'ים לסנטימטרים, מכפילים ב-2.54. - אחזור הגיל של המשתמש בשנים מהשדה
ageבמשאב Profile. - אחזרו את המין הביולוגי באופן עצמאי (לדוגמה, על ידי הצגת בקשה למשתמש או שמירה שלו במסד הנתונים שלכם), כי Google Health API לא חושף את השדה הזה.
- משתמשים באחת מהנוסחאות הבאות, בהתאם למין הביולוגי של המשתמש:
- גברים:
BMR = 66 + (13.7 x weight_kg) + (5 x height_cm) - (6.8 x age_years) - נשים:
BMR = 655 + (9.6 x weight_kg) + (1.8 x height_cm) - (4.7 x age_years)
- גברים:
הוצאת האנרגיה היומית הכוללת (TDEE)
הוצאת האנרגיה היומית הכוללת (TDEE) היא אומדן של מספר הקלוריות הכולל שאדם שורף ביום, והיא מביאה בחשבון גם את ה-BMR וגם את הפעילות הגופנית. כדי להעריך את ה-TDEE של המשתמש, מכפילים את ערך ה-BMR בפקטור פעילות שמתאים לאורח החיים שלו:
| רמת הפעילות | תיאור | מכפיל |
|---|---|---|
| לא פעיל | מעט פעילות גופנית או ללא פעילות גופנית בכלל. | BMR x 1.2 |
| פעילות קלה | 1-3 ימי אימון בשבוע. | BMR x 1.375 |
| פעילות בינונית | 3-5 ימי אימון בשבוע. | BMR x 1.55 |
| פעיל מאוד | 6-7 ימי אימון בשבוע. | BMR x 1.725 |
| פעילות רבה מאוד | פעילות גופנית מאומצת מאוד או עבודה פיזית. | BMR x 1.9 |
נקודות קצה (endpoints)
נקודות הקצה של REST משתמשות בתחביר עקבי לכל סוגי הנתונים.
- נקודת קצה (endpoint) של שירות: כתובת ה-URL הבסיסית מסוג HTTP משתנה ל-https://health.googleapis.com.
- תחביר נקודת הקצה: Google Health API תומך במספר מוגבל של נקודות קצה, שרוב סוגי הנתונים הנתמכים יכולים להשתמש בהן. כך מתקבל תחביר עקבי לכל סוגי הנתונים, וקל יותר להשתמש בנקודות הקצה.
- מזהה משתמש: צריך לציין את מזהה המשתמש או את me בתחביר של נקודת הקצה. כשמשתמשים ב-me, מזהה המשתמש נגזר מטוקן הגישה.
דוגמה: הנה דוגמה לנקודת הקצה GET Profile שנקראת באמצעות Google Health API
GET https://health.googleapis.com/v4/users/me/profile
מיפויים של נקודות קצה (endpoint)
בטבלה סוגי הנתונים של Google Health API מפורטים סוגי הנתונים הזמינים והשיטות של ה-API שנתמכות בהם.
| סוג נקודת הקצה ל-Fitbit Web API | Google Health API |
|---|---|
| GET (יומן | סיכום | סיכום יומי) כשמבקשים נתונים של יום אחד | שיטת dailyRollup עם windowSize = יום אחד |
| GET (תוך-יומי) כשמבקשים נתונים מפורטים | אמצעי תשלום אחד (list) |
| GET (סדרת זמנים) לפי תאריך או מרווח זמן | השיטה rollUp או dailyRollUp, כולל טווח תאריכים |
| GET (רשימת יומנים) | אמצעי תשלום אחד (list) |
| יומני CREATE ו-UPDATE | אמצעי תשלום אחד (patch) |
| מחיקת יומנים | אמצעי תשלום אחד (batchDelete) |
| GET Profile | users.getProfile מחזירה את המידע הספציפי של המשתמשusers.getSettings מחזירה את היחידות ואזורי הזמן של המשתמש |
| עדכון הפרופיל | users.updateProfile משנה את המידע הספציפי של המשתמשusers.updateSettings משנה את היחידות ואת אזורי הזמן של המשתמש |
| קבלת מזהה משתמש | users.getIdentity מחזיר את מזהה המשתמש הקודם ב-Fitbit ואת מזהה המשתמש ב-Google. |
| קבלת מכשירים | users.pairedDevices מחזירה את רשימת המכשירים המותאמים |
| יצירת מינויים | projects.subscribers.subscriptions.create יוצר מינוי באופן ידני |
| מחיקת המינויים | projects.subscribers.subscriptions.delete מחיקת מינוי |
| קבלת רשימת מינויים | projects.subscribers.subscriptions.list מציג את כל המינויים |