בדף הזה מופיעה סקירה כללית של מוסכמות API בארכיטקטורת REST, וגם אינדקס של משימות נפוצות ב-Google Health API ודוגמאות לכל אחת מהן.
מוסכמות של API בארכיטקטורת REST
ה-Google Health API פועל לפי התקנים של הצעות לשיפור Google API (AIP), ובאופן ספציפי לפי AIP-127 (קידוד טרנסקוד של HTTP ו-gRPC) ו-AIP-131 עד AIP-135 (שיטות סטנדרטיות). התקנים האלה מגדירים איך נתונים ממופים מהודעת פרוטו לבקשת HTTP.
פרמטרים של שאילתה
משתמשים בפרמטרים של שאילתה כשהנתונים הם חלק מכתובת ה-URL. השדה הזה מיועד בעיקר לבקשות GET (אחזור משאב) או לבקשות LIST (סינון/חלוקה לדפים), אבל הוא משמש גם לפעולות DELETE.
- מיקום: מצורף לכתובת ה-URL אחרי
?. - תחביר: צמדי מפתח/ערך מופרדים באמצעות
&. - מיפוי: כל שדה בהודעת הבקשה שלא נכלל בתבנית של נתיב כתובת ה-URL ממופה לפרמטר של שאילתה.
- הכי מתאים ל: סוגים פשוטים (מחרוזות, מספרים שלמים, ספירות) ושדות חוזרים.
תחביר לדוגמה:
GET https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints?page_size=10&filter=data_type.interval.start_time >= "2025-10-01T00:00:00Z"
גוף הבקשה
גוף הבקשה משמש כשהנתונים משנים את מצב המשאב או כשהם גדולים מדי בשביל כתובת URL. הגוף הוא בדרך כלל ייצוג JSON של המשאב עצמו. בדרך כלל משתמשים בהן לפעולות POST, PATCH ו-PUT.
- מיקום: בתוך מטען הייעודי (payload) של HTTP (לא מוצג בכתובת ה-URL).
- תחביר: בפורמט של אובייקט JSON.
- מיפוי: מוגדר בהערה
google.api.http.-
body: "*"פירושו שכל ההודעה היא הגוף. -
body: "resource_name"אומר שרק שדה ספציפי בפרוטו הוא הגוף.
-
- הכי מתאים ל: אובייקטים מורכבים, הודעות בתצוגת עץ ומידע אישי רגיש.
תחביר לדוגמה:
POST https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints:rollUp
Content-Type: application/json
{
"range": {
"startTime": "2025-11-05T00:00:00Z",
"endTime": "2025-11-13T00:00:00Z"
},
"windowSize": "3600s"
}המקרה ההיברידי
בשיטת Update או בפעולת PATCH שתואמות ל-AIP-134, נעשה שימוש בשניהם.
כתובת ה-URL מכילה את שם המשאב, הגוף מכיל את נתוני המשאב המעודכנים, ופרמטר של שאילתה (בדרך כלל update_mask) מציין אילו שדות לשנות.
PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id
Content-Type: application/json
{
"endpointUri": "https://myapp.com/new-webhooks/health"
}
הבדלים מרכזיים במבט מהיר
| תכונה | פרמטרי שאילתה | גוף הבקשה |
|---|---|---|
| הנחיות לשימוש ב-AIP | משמש לחיפוש, לסינון ולפעולות קריאה. | משמש לפעולות כתיבה. |
| חשיפה | אפשר לראות את הנתונים האלה בהיסטוריית הגלישה וביומני השרת. | מוסתר מכתובת ה-URL. |
| מורכבות | מוגבל למבנים שטוחים או חוזרים. | תומך באובייקטים של JSON שהם רכיב בתוך רכיב. |
| קידוד | חייב להיות מקודד בקידוד URL (לדוגמה, רווחים הופכים ל-%20). |
קידוד JSON רגיל. |
תאריכים
כל התאריכים ב-Google Health API מוצגים בפורמט YYYY-MM-DD. Nutrition API תומך בתקן ISO-8601 לערכי תאריך, בתנאים הבאים:
- שנה בת 4 ספרות
YYYY - ערכי השנה בטווח 0000-9999
- אין אכיפה של הגבלות על תאריך התחלה שמשתמעות מתקן ISO-8601 או מתקופה אחרת
כותרות
כדי להפעיל את נקודות הקצה של Google Health API, צריך להשתמש בכותרות המתאימות ובאסימון הגישה. מומלץ להשתמש בכותרת הבאה גם בבקשות GET וגם בבקשות POST:
Authorization: Bearer access-token Accept: application/json
אינדקס של משימות API
בקטע הזה מופיע אינדקס של משימות נפוצות ב-Google Health API ודוגמאות לכל אחת מהן.
איך מוצאים את מזהה המשתמש ב-Fitbit או ב-Google
אחרי שמשתמש נותן הסכמה באמצעות Google OAuth 2.0, תגובת האסימון לא כוללת את מזהה המשתמש ב-Fitbit או ב-Google. כדי לקבל את ה-User-ID, קוראים לנקודת הקצה getIdentity. getIdentity
מחזירה גם את מזהה המשתמש בגרסה הקודמת של Fitbit וגם את מזהה המשתמש ב-Google.
מומלץ, ברגע שמשתמש חדש מאשר את השימוש ב-OAuth, לקרוא לנקודת הקצה getIdentity ולאחסן את שני מזהי המשתמשים. כך אפשר להבטיח תאימות לאחור ולפנים בשילוב.
לדוגמה:
בקשה
GET https://health.googleapis.com/v4/users/me/identity Authorization: Bearer access-token Accept: application/json
תשובה
{
"name": "users/me/identity",
"legacyUserId": "A1B2C3",
"healthUserId": "111111256096816351"
}קבלת נתונים מפורטים או נתונים המתקבלים במשך היום שנאספים במהלך יום
כדי לקבל נתונים מפורטים או נתונים תוך-יומיים שנאספו במהלך היום במרווחי זמן נתמכים עבור סוג נתונים מסוים, אפשר להשתמש בנקודת הקצה list של סוג הנתונים הזה.
לדוגמה:
בקשה
GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints Authorization: Bearer access-token Accept: application/json
תשובה
{
"dataPoints": [
{
"dataSource": {
"recordingMethod": "PASSIVELY_MEASURED",
"device": {
"manufacturer": "",
"displayName": "Charge 6"
},
"platform": "FITBIT"
},
"steps": {
"interval": {
"startTime": "2026-03-04T07:05:00Z",
"startUtcOffset": "0s",
"endTime": "2026-03-04T07:06:00Z",
"endUtcOffset": "0s",
"civilStartTime": {
"date": {
"year": 2026,
"month": 3,
"day": 4
},
"time": {
"hours": 7,
"minutes": 5
}
},
"civilEndTime": {
"date": {
"year": 2026,
"month": 3,
"day": 4
},
"time": {
"hours": 7,
"minutes": 6
}
}
},
"count": "40"
}
},
...
],
"nextPageToken": "Xm5h-6L0viZxIlRuWjx5bmvy98zj85uG34tuMn16mu2pntsnZI32iqhq"
}איך מקבלים תצוגה מאוחדת של נתונים לפי מרווחי זמן
כדי לאחזר נתונים של מרווחי זמן בלי רשומות חופפות או התנגשויות בין מכשירים, צריך להתקשר לנקודת הקצה reconcile. נקודת הקצה reconcile מסירה באופן אוטומטי כפילויות של מרווחי זמן חופפים בין קבוצות של סנכרון ומכמה מכשירי הקלטה, ומחזירה זרם רציף ומהימן שמתאים לעיבוד של ציר זמן של פעילות ולחישוב משכי זמן.
כדי לקבל מידע נוסף על הסיבה לכך שמכשירים מקושרים יוצרים חפיפה בין מרווחי הזמן ועל השוואה תפעולית בין list לבין reconcile, אפשר לעיין במדריך לניהול נתונים.
בדוגמה הבאה מוצגת השוואה בין התגובה של list (שמחזירה את שני הרשומות החופפות) לבין התגובה של reconcile (שפותרת את הקונפליקט על ידי החזרת הרשומה הסמכותית) עבור משתמש עם שתי סשנים חופפים של פעילות גופנית:
רשימה גולמית
GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints Authorization: Bearer access-token Accept: application/json
{
"dataPoints": [
{
"name": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
"exercise": {
"interval": {
"startTime": "2026-09-03T11:20:00Z",
"endTime": "2026-09-03T11:50:00Z"
},
"exerciseType": "RUNNING"
}
},
{
"name": "users/111111256096816351/dataTypes/exercise/dataPoints/4389052750481144696",
"exercise": {
"interval": {
"startTime": "2026-09-03T11:00:00Z",
"endTime": "2026-09-03T11:30:00Z"
},
"exerciseType": "RUNNING"
}
}
]
}ההזמנה הוסדרה
GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints:reconcile Authorization: Bearer access-token Accept: application/json
{
"dataPoints": [
{
"dataPointName": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
"exercise": {
"interval": {
"startTime": "2026-09-03T11:20:00Z",
"endTime": "2026-09-03T11:50:00Z"
},
"exerciseType": "RUNNING"
}
}
]
}תהליך ההתאמה פותר סתירות בין סשנים על ידי ביטול כפילויות ובחירה ברשומה הסמכותית, במקום ליצור איחוד מלאכותי של הזמנים (למשל 11:00:00Z עד 11:50:00Z). בתגובה לאחר ההתאמה מוחזרת נקודת הנתונים המנצחת (7797422996486764704) עם מרווח הזמן המקורי שלה (11:20:00Z עד 11:50:00Z), וכך נשמרת השלמות של הטלמטריה והמדדים שנמדדו בסשן הזה.
סנן נתונים
כדי לאחזר קבוצות משנה ספציפיות של רשומות נקודות על הגרף שתואמות לקריטריונים כמו מרווח זמן, תאריך או זמן תצפית, משתמשים בנקודת הקצה list או reconcile עם פרמטר filter.
הנחיות מפורטות, כללי עיצוב, שגיאות אימות ודוגמאות לשאילתות מופיעים במדריך לסינון נתונים.
סינון לפי משפחה של מקורות נתונים
כדי לבודד או לצבור נתונים מסוגים ספציפיים של מקורות (לדוגמה, מכשירים פיזיים לבישים לעומת הזנות ידניות), משתמשים בפרמטר dataSourceFamily.
הנחיות מפורטות, משפחות נתמכות ודוגמאות לבקשות ולתגובות של reconcile, rollUp ו-dailyRollUp זמינות במאמר סינון לפי משפחה של מקור נתונים במדריך לסינון נתונים.
סינון נתונים לפי שעת התחלה אזרחית של מרווח זמן
משתמשים בנקודת הקצה list עם הפרמטר filter כדי לסנן נתונים לפי זמן אזרחי או לפי מרווח.
לדוגמה:
בקשה
GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints?filter=steps.interval.civil_start_time >= "2026-03-04T00:00:00" Authorization: Bearer access-token Accept: application/json
תשובה
{
"dataPoints": [
{
"dataSource": {
"recordingMethod": "PASSIVELY_MEASURED",
"device": {
"manufacturer": "",
"displayName": "Charge 6"
},
"platform": "FITBIT"
},
"steps": {
"interval": {
"startTime": "2026-03-04T07:05:00Z",
"startUtcOffset": "0s",
"endTime": "2026-03-04T07:06:00Z",
"endUtcOffset": "0s",
"civilStartTime": {
"date": {
"year": 2026,
"month": 3,
"day": 4
},
"time": {
"hours": 7,
"minutes": 5
}
},
"civilEndTime": {
"date": {
"year": 2026,
"month": 3,
"day": 4
},
"time": {
"hours": 7,
"minutes": 6
}
}
},
"count": "40"
}
...
],
"nextPageToken": "Xm5h-6L0viZxIlRuQjp5bml1bZ4ve2dhNmZvMnt4Yn7qIGQhbHN3YQ"
}סינון נתונים לפי זמן פיזי של תצפית לדוגמה
משתמשים בנקודת הקצה list עם הפרמטר filter כדי לסנן נתונים לפי הזמן הפיזי של תצפית המדגם.
לדוגמה:
בקשה
GET https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints?filter=body_fat.sample_time.physical_time >= "2026-03-01T00:00:00Z" Authorization: Bearer access-token Accept: application/json
תשובה
{
"dataPoints": [
{
"name": "users/123456789/dataTypes/body-fat/dataPoints/1234567890",
"dataSource": {
"recordingMethod": "UNKNOWN",
"application": {
"packageName": "",
"webClientId": "",
"googleWebClientId": "google-web-client-id"
},
"platform": "GOOGLE_WEB_API"
},
"bodyFat": {
"sampleTime": {
"physicalTime": "2026-03-10T10:00:00Z",
"utcOffset": "0s",
"civilTime": {
"date": {
"year": 2026,
"month": 3,
"day": 10
},
"time": {
"hours": 10
}
}
},
"percentage": 20
}
}
"nextPageToken": ""
}סינון וצבירה לפי משפחה של מקורות נתונים
משפחה של מקורות נתונים היא קיבוץ לוגי של מקורות נתונים (כמו שעונים חכמים, אפליקציות לנייד או רשומות שהוזנו באופן ידני). היא מאפשרת לכם לבודד או לצבור נתונים מסוגים ספציפיים של מקורות (לדוגמה, מכשירים לבישים פיזיים לעומת הזנות ידניות).
כל נקודות הקצה reconcile, rollUp ו-dailyRollUp תומכות בפרמטר dataSourceFamily. מנגנון ההעברה תלוי בנקודת הקצה:
| נקודת קצה (שיטת HTTP) | מנגנון |
|---|---|
reconcile (GET) |
מעבירים את dataSourceFamily כפרמטר של שאילתה בכתובת URL. |
rollUp (POST) |
מעבירים את dataSourceFamily כשדה בגוף בקשת ה-JSON. |
dailyRollUp (POST) |
מעבירים את dataSourceFamily כשדה בגוף בקשת ה-JSON. |
משפחות של מקורות נתונים נתמכים
בטבלה הבאה מפורטים הערכים הנתמכים של dataSourceFamily:
| אפשרות | תיאור |
|---|---|
users/me/dataSourceFamilies/all-sources |
ערך ברירת מחדל. הפונקציה מחזירה נקודות נתונים שתואמו בין כל מקורות הנתונים הרשומים מאינטראקציה ישירה (1P) ומצד שלישי (3P). האפשרות הזו תחזיר נתונים מאפליקציות של צד שלישי (למשל, צעדים משעון חכם + צעדים מאפליקציה של צד שלישי + צעדים מטלפון נייד + צעדים שהוזנו ידנית). |
users/me/dataSourceFamilies/google-wearables |
כולל נתונים שתועדו על ידי מכשירי מעקב של Google ו-Fitbit (כמו מכשירי מעקב לבישים של Fitbit ו-Pixel Watch). לא כולל נתונים שנרשמו באופן ידני ונתונים משוערים מהטלפון. האפשרות הזו מתאימה אם השילוב שלכם דורש טלמטריה גולמית של חיישנים שנרשמת ישירות על ידי חומרה של מכשירים לבישים. |
users/me/dataSourceFamilies/google-sources |
כולל מקורות מאינטראקציה ישירה של Google ו-Fitbit. הנתונים האלה כוללים רשומות של מכשירי מעקב פיזי, נתונים מ-Health Connect וכל נתון שהוזן באופן ידני דרך אפליקציות של צד ראשון (כמו אפליקציית Fitbit או Google Fit). |
כדי לקבל מקור נתונים שעבר התאמה ממשפחה ספציפית של מקורות נתונים, מפעילים את נקודת הקצה reconcile עם פרמטר השאילתה dataSourceFamily.
לדוגמה, בקשת ה-GET הבאה מאחזרת את נתוני השינה שתועדו על ידי מכשיר המעקב ביום שאחרי 2026-03-03:
בקשה
GET https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints:reconcile?dataSourceFamily=users/me/dataSourceFamilies/google-wearables&filter=sleep.interval.civil_end_time >= "2026-03-03" Authorization: Bearer access-token Accept: application/json
תשובה
{
"dataPoints": [
{
"name": "users/2515055256096816351/dataTypes/sleep/dataPoints/2724123844716220216",
"dataSource": {
"recordingMethod": "DERIVED",
"device": {
"displayName": "Charge 6"
},
"platform": "FITBIT"
},
"sleep": {
"interval": {
"startTime": "2026-03-03T20:57:30Z",
"startUtcOffset": "0s",
"endTime": "2026-03-04T04:41:30Z",
"endUtcOffset": "0s"
},
"type": "STAGES",
"stages": [
{
"startTime": "2026-03-03T20:57:30Z",
"startUtcOffset": "0s",
"endTime": "2026-03-03T20:59:30Z",
"endUtcOffset": "0s",
"type": "AWAKE",
"createTime": "2026-03-04T04:43:40.937183Z",
"updateTime": "2026-03-04T04:43:40.937183Z"
},
{
"startTime": "2026-03-04T04:07:30Z",
"startUtcOffset": "0s",
"endTime": "2026-03-04T04:41:30Z",
"endUtcOffset": "0s",
"type": "AWAKE",
"createTime": "2026-03-04T04:43:40.937183Z",
"updateTime": "2026-03-04T04:43:40.937183Z"
}
],
"metadata": {
"stagesStatus": "SUCCEEDED",
"processed": true,
"main": true
},
"summary": {
"minutesInSleepPeriod": "464",
"minutesAfterWakeUp": "0",
"minutesToFallAsleep": "0",
"minutesAsleep": "407",
"minutesAwake": "57",
"stagesSummary": [
{
"type": "AWAKE",
"minutes": "56",
"count": "12"
},
{
"type": "LIGHT",
"minutes": "198",
"count": "19"
},
{
"type": "DEEP",
"minutes": "114",
"count": "10"
},
{
"type": "REM",
"minutes": "94",
"count": "4"
}
]
},
"createTime": "2026-03-04T04:43:40.337983Z",
"updateTime": "2026-03-04T04:43:40.937183Z"
}
}
],
"nextPageToken": ""
}כדי לצבור נקודות נתונים בחלון זמן מסוים שמוגבל למשפחה מסוימת של מקורות נתונים, מפעילים את נקודת הקצה rollUp ומעבירים את השדה dataSourceFamily בגוף הבקשה ב-JSON.
בקשת ה-POST הבאה שולחת שאילתה לגבי מספר הצעדים היומיים במרווחי שעה (3600s), שמצטברים רק ממכשירים לבישים:
בקשה
POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:rollUp
Authorization: Bearer access-token
Accept: application/json
{
"range": {
"startTime": "2026-07-29T00:00:00Z",
"endTime": "2026-07-29T23:59:59Z"
},
"windowSize": "3600s",
"dataSourceFamily": "users/me/dataSourceFamilies/google-wearables"
}תשובה
{
"rollupDataPoints": [
{
"startTime": "2026-07-29T08:00:00Z",
"endTime": "2026-07-29T09:00:00Z",
"steps": {
"countSum": "1200"
}
},
{
"startTime": "2026-07-29T09:00:00Z",
"endTime": "2026-07-29T10:00:00Z",
"steps": {
"countSum": "3450"
}
}
]
}כדי לצבור נקודות נתונים יומיות עבור משפחת מקורות ספציפית, קוראים לנקודת הקצה dailyRollUp ומעבירים את השדה dataSourceFamily בגוף הבקשה.
לדוגמה, הבקשה הבאה מחשבת את הסיכומים היומיים של הצעדים של המשתמש, כולל כל המקורות של Google ו-Fitbit (מכשירים לבישים + הזנות ידניות):
בקשה
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": 7,
"day": 28
},
"time": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"nanos": 0
}
},
"end": {
"date": {
"year": 2026,
"month": 7,
"day": 30
},
"time": {
"hours": 0,
"minutes": 0,
"seconds": 0,
"nanos": 0
}
}
},
"windowSizeDays": 1,
"dataSourceFamily": "users/me/dataSourceFamilies/google-sources"
}תשובה
{
"rollupDataPoints": [
{
"civilStartTime": {
"date": {
"year": 2026,
"month": 7,
"day": 28
},
"time": {}
},
"civilEndTime": {
"date": {
"year": 2026,
"month": 7,
"day": 28
},
"time": {
"hours": 23,
"minutes": 59,
"seconds": 59
}
},
"steps": {
"countSum": "8430"
}
},
{
"civilStartTime": {
"date": {
"year": 2026,
"month": 7,
"day": 29
},
"time": {}
},
"civilEndTime": {
"date": {
"year": 2026,
"month": 7,
"day": 29
},
"time": {
"hours": 23,
"minutes": 59,
"seconds": 59
}
},
"steps": {
"countSum": "11245"
}
}
]
}צבירה של נקודות נתונים בטווח זמן מסוים
משתמשים בנקודת הקצה rollUp כדי להחזיר את צבירת נקודות הנתונים על סמך חלון בזמן בשניות, בטווח datetime על סמך הזמן הפיזי של המשתמש (ב-UTC).
כשמתקשרים לנקודת הקצה rollUp, צריך לספק את גוף הבקשה שמייצג את טווח הזמן הנדרש ואת 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 כשרוצים לצבור נתונים על פני יום אחד או כמה ימים, שנקראים windowSize. בגוף הבקשה, מציינים את טווח הזמן האזרחי של המרווח הנדרש. בהתאם לסוג הנתונים, תקבלו את הסכום או את הממוצע של הנתונים במהלך המרווח.
לדוגמה:
בקשה
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"
}
}
]
}חלוקה לקטגוריות כשטווח לא מתחלק בגודל החלון
אם הטווח המבוקש לא מתחלק בדיוק ב-windowSize (או ב-windowSizeDays), המקטע האחרון יקוצר בקצה העליון של הטווח ויכסה משך זמן קצר יותר מגודל החלון. ה-API מקבל את הבקשה שלכם ללא שינוי, ולא מבצע עיגול, הזזות זמן או אינטרפולציה של נתונים.
כדי לכסות את כל הטווח המבוקש, ה-API משתמש בחלוקה מעגלת כלפי מעלה כדי לחשב את המספר הכולל של חלונות הצבירה:
Number of windows = ceiling(Range duration / Window size)
כל קבוצה מתחילה באופן רציף מתחילת הטווח. אם הוספה של חלון נוסף בגודל מלא תגרום לחריגה מזמן הסיום שביקשתם, החלון האחרון ייחתך (clamp) בזמן הסיום של הטווח.
איך פועל תהליך ההעברה לדלי
כשמבקשים נתוני סיכום עם טווחי תאריכים שלא מתחלקים, ה-API מחיל את הכללים הבאים:
- החלוקה לקבוצות מתחילה בתחילת טווח התאריכים שצוין (
range.startTimeאוrange.start) וממשיכה קדימה לפי גודל חלון הזמן (windowSizeאוwindowSizeDays). - הקטגוריה האחרונה לפי סדר כרונולוגי מוגבלת לסוף הטווח המבוקש (
range.endTimeאוrange.end), כלומר היא מכסה משך זמן קצר יותר מגודל חלון הזמן המבוקש. - באובייקטים
RollupDataPointאוDailyRollupDataPointשמוחזרים מצוינים במפורש חותמות הזמן של ההתחלה והסיום שלהם, ואפשר להשתמש בהם כדי לבדוק את משך הזמן בפועל של הקטגוריה שקוצרה. - ה-API מחזיר נתונים מצטברים בסדר כרונולוגי הפוך (החדשים ביותר קודם), ולכן הקטגוריה הכרונולוגית האחרונה (זו שקוצצה) מופיעה כרכיב הראשון (
index 0) ברשימה שמוחזרת.
תרחיש: טווח של 12 דקות עם חלון של 5 דקות
נניח שלקוח מבקש איחוד לתצוגה אחת של נתונים בטווח של 12 דקות עם מרווח של 5 דקות בין נקודות הנתונים:windowSize
range.startTime:10:00:00-
range.endTime:10:12:00(משך כולל: 12 דקות) windowSize:5 minutes
12 דקות הוא לא כפולה של 5 דקות (12 = 5 * 2 + 2), ולכן ה-API מקבל את הבקשה ומחשב את מספר החלונות כך: ceiling(12 / 5) = 3.
כך נוצרות שלוש קטגוריות כרונולוגיות:
- מאגר 1:
[10:00:00, 10:05:00)— משך הזמן: 5 דקות (החלון המלא) - מאגר 2:
[10:05:00, 10:10:00)— משך הזמן: 5 דקות (החלון המלא) - Bucket 3 (Truncated):
[10:10:00, 10:12:00)— Duration: 2 minutes (truncated atrange.endTime)
ההשפעה על ערכים נצברים
מכיוון שהחלון הסופי קצר יותר, מדדים מצטברים (כמו סכום או מספר השלבים) יהיו נמוכים יותר בדלי המקוצר רק בגלל ציר הזמן הקצר יותר.
אם משתמש הולך בקצב קבוע של 100 צעדים בדקה במשך כל טווח 12 הדקות הזה:
- קבוצה 1 (10:00 עד 10:05): 500 צעדים (5 דקות × 100 צעדים בדקה)
- קבוצה 2 (10:05 עד 10:10): 500 צעדים (5 דקות × 100 צעדים בדקה)
- קבוצה 3 (10:10 עד 10:12): 200 צעדים (2 דקות × 100 צעדים בדקה)
דוגמה לתגובה של API שמציגה הזמנה
מכיוון שה-API מחזיר תוצאות בסדר כרונולוגי הפוך, הקטגוריה שקוצצה מופיעה כרכיב הראשון ברשימה שמוחזרת:
{
"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"
}
}
]
}
גודל החלון של סיכום הנתונים והרזולוציה של האחסון הבסיסי
נקודת הקצה rollUp מקבלת כל windowSize של שנייה אחת או יותר, אבל סוגי נתונים שונים מתעדים ושומרים את המדידות בקצב דגימה שונה או במרווחי זמן שונים באחסון הבסיסי. לדוגמה, מדדים של פעילות גופנית שאפשר לענוד, כמו steps, distance, active-minutes ו-active-energy-burned, בדרך כלל נרשמים במרווחי זמן של דקה אחת (60s).
כשמצטברים נתונים מסוגים שונים של מרווחי זמן, נקודת הקצה rollUp ממקמת כל נקודה על הגרף שתועדה בדלי שמכיל את startTime של נקודה על הגרף. ה-API לא מבצע פילוח, אינטרפולציה או חלוקה של נתוני מרווחים בין קבוצות של מרווחי משנה.
אם מציינים windowSize שקטן ממרווח אחסון הנתונים הבסיסי (לדוגמה, אם מבקשים חלון זמן של 10 שניות לנתוני steps שאוחסנו במרווחים של דקה אחת):
- המשנה הראשון שמתאים לערך
startTimeשל המרווח (לדוגמה,10:00:00עד10:00:10) מקבל את הספירה המצטברת של הדקה כולה (לדוגמה, כל 100 הצעדים שתועדו באותה דקה). - המשנה-דליים שנותרו באותה דקה (
10:00:10עד10:00:20,10:00:20עד10:00:30וכן הלאה) לא מקבלים נקודות נתונים, כי אף מרווח לא מתחיל בחלונות האלה.
התוצאה היא נתונים עם עליות וירידות חדות, שבהם הערך של כל המרווח מרוכז בחלון המשנה הראשון.
כדי לקבל נתונים מצטברים משמעותיים ומפוזרים באופן שווה, צריך תמיד להגדיר את windowSize
למשך זמן ששווה לפרק הזמן של רזולוציית האחסון הבסיסית של סוג נתוני היעד או גדול ממנו (לדוגמה, 60s או יותר עבור steps). למידע על רזולוציית האחסון וחלון הצבירה המינימלי המומלץ לכל סוג נתונים, אפשר לעיין בהפניה סוגי הנתונים ב-Google Health API.
עדכון נתוני בריאות וכושר של משתמש
כדי לעדכן את נתוני הבריאות וכושר של משתמש, משתמשים בנקודת הקצה patch.
נקודת הקצה patch מעדכנת רשומה קיימת על סמך המזהה שצוין בכתובת ה-URL של הבקשה. מזינים את המזהה של נקודת נתונים שהוזנה בעבר. ה-API מחליף את הרשומה הקיימת.
בעלי הרשומה יכולים גם לעדכן את חותמות הזמן של המרווח של נקודת נתונים (startTime ו-endTime), או להעביר אותן מפלטפורמות במעלה הזרם כמו Health Connect. פרטים על שינוי חותמות זמן מופיעים במדריך לניהול נתונים. דוגמה לעדכון חותמות זמן של מרווחים מופיעה במאמר בנושא עדכון חותמות זמן של מרווחים לנתונים קיימים.
מתי כדאי להשתמש במזהה של נקודה על הגרף
מזהה נקודת הנתונים חיוני בתרחישים הבאים:
- עדכונים ממוקדים: כדי לעדכן מדידה ספציפית, צריך לציין את המזהה שלה בבקשת
patch. - מחיקות: שמירת המזהה מאפשרת לאפליקציה למחוק את הרשומה בשלב מאוחר יותר באמצעות נקודת הקצה
batchDelete.
דוגמה לעדכון של קריאת אחוז השומן בגוף של משתמש במשקל שנקרא HumanScale מהחברה Scales R Us. המשתמש קיבל קריאה חדשה של אחוז השומן בגוף בשיעור של 20% בתאריך 2026-03-10:
בקשה
PATCH https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints/1234567890
Authorization: Bearer access-token
Content-Type: application/json
{
"name": "users/me/dataTypes/body-fat/dataPoints/1234567890",
"dataSource": {
"recordingMethod": "ACTIVELY_MEASURED",
"device": {
"formFactor": "SCALE",
"manufacturer": "Scales R Us",
"displayName": "HumanScale"
}
},
"bodyFat": {
"sampleTime": {
"physicalTime": "2026-03-10T10:00:00Z"
},
"percentage": 20
}
}תשובה
{
"done": true,
"response": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
"name": "users/123456789/dataTypes/body-fat/dataPoints/1234567890",
"dataSource": {
"recordingMethod": "ACTIVELY_MEASURED",
"device": {
"formFactor": "SCALE",
"manufacturer": "Scales R Us",
"displayName": "HumanScale"
},
"application": {
"googleWebClientId": "618308034039.apps.googleusercontent.com"
},
"platform": "GOOGLE_WEB_API"
},
"bodyFat": {
"sampleTime": {
"physicalTime": "2026-03-10T10:00:00Z"
},
"percentage": 20
}
}
}עדכון חותמות הזמן של מרווחי העדכון לנתונים קיימים
כדי לעדכן את startTime או endTime של נקודה על הגרף קיימת במרווח זמן, שולחים בקשת PATCH ל-URI של מקור המידע של נקודה על הגרף. רק היוצר או הבעלים המקוריים של רשומה יכולים לשנות את השדות שלה. אפליקציות לא יכולות לערוך נקודות נתונים שהן לא יצרו.
מידע נוסף על שינוי חותמות זמן, על עדכונים במעלה הזרם מ-Health Connect ועל השלכות של שמירת נתונים במטמון זמין במדריך לניהול נתונים.
בדוגמה הבאה מוצג עדכון של חותמות הזמן של מרווחים ביומן הידרציה קיים באמצעות נקודת הקצה patch על ידי אפליקציית בעלים:
בקשה
PATCH https://health.googleapis.com/v4/users/me/dataTypes/hydration-log/dataPoints/4093039283164890826
Authorization: Bearer access-token
Content-Type: application/json
{
"hydrationLog": {
"interval": {
"startTime": "2026-09-03T10:05:00Z",
"endTime": "2026-09-03T10:19:59Z"
},
"amountConsumed": {
"milliliters": 350
}
}
}תשובה
{
"done": true,
"response": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
"name": "users/111111256096816351/dataTypes/hydration-log/dataPoints/4093039283164890826",
"hydrationLog": {
"interval": {
"startTime": "2026-09-03T10:05:00Z",
"endTime": "2026-09-03T10:19:59Z",
"civilStartTime": {
"date": {
"year": 2026,
"month": 9,
"day": 3
},
"time": {
"hours": 10,
"minutes": 5
}
},
"civilEndTime": {
"date": {
"year": 2026,
"month": 9,
"day": 3
},
"time": {
"hours": 10,
"minutes": 19,
"seconds": 59
}
}
},
"amountConsumed": {
"milliliters": 350
}
}
}
}רישום פריט מזון
כדי לתעד פריט מזון, שולחים בקשת POST לנקודת הקצה nutrition-log dataPoints. גוף הבקשה מכיל DataPoint עם אובייקט nutritionLog.
מידע נוסף זמין במדריך התזונה.
לדוגמה:
בקשה
POST https://health.googleapis.com/v4/users/me/dataTypes/nutrition-log/dataPoints
Authorization: Bearer access-token
Content-Type: application/json
{
"nutritionLog": {
"interval": {
"startTime": "2026-06-16T12:00:00Z",
"endTime": "2026-06-16T12:30:00Z"
},
"foodDisplayName": "Banana",
"mealType": "LUNCH",
"energy": {
"kcal": 105
},
"totalCarbohydrate": {
"grams": 27
},
"totalFat": {
"grams": 0.3
}
}
}תשובה
{
"done": true,
"response": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
"name": "users/123456789/dataTypes/nutrition-log/dataPoints/567890",
"dataSource": {
"recordingMethod": "ACTIVELY_MEASURED",
"platform": "GOOGLE_WEB_API"
},
"nutritionLog": {
"interval": {
"startTime": "2026-06-16T12:00:00Z",
"startUtcOffset": "0s",
"endTime": "2026-06-16T12:30:00Z",
"endUtcOffset": "0s"
},
"energy": {
"kcal": 105
},
"totalCarbohydrate": {
"grams": 27
},
"totalFat": {
"grams": 0.3
},
"mealType": "LUNCH",
"foodDisplayName": "Banana"
}
}
}מחיקת נתוני בריאות וכושר של משתמשים
אפשר להשתמש בbatchDelete שיטה כדי למחוק מערך של נתוני האפליקציה של משתמש באפליקציית Fitbit.
לדוגמה, משתמש תיעד בעבר את אחוז השומן בגוף שלו באמצעות משקל, אבל הוא רוצה למחוק את התיעוד. שימוש ב-user-id וב-data-point-id מפעולת ההוספה המקורית:
בקשה
POST https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints:batchDelete
Authorization: Bearer access-token
Accept: application/json
content-length: 93
{
"names": [
"users/123456789/dataTypes/body-fat/dataPoints/1234567890"
]
}תשובה
{
"done": true,
"response": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
}
}איך מוצאים מידע על מכשיר
משתמשים בנקודת הקצה list כדי לאחזר את רשימת המכשירים שמצורפים לחשבון של משתמש. המידע הזה כולל את פרטי הדגם של המכשיר (deviceVersion) ואת הפעם האחרונה שבה הוא סונכרן עם אפליקציית Google Health לנייד (lastSyncTime).
הגדרת הרשימה ופרטי הסנכרון שימושיים לפתרון בעיות בסנכרון או לאחזור נתונים היסטוריים מאז זמן הסנכרון האחרון.
לדוגמה:
בקשה
GET https://health.googleapis.com/v4/users/me/pairedDevices Authorization: Bearer access-token Accept: application/json
תשובה
{
"pairedDevices": [
{
"name": "users/me/pairedDevices/123456",
"deviceType": "TRACKER",
"batteryStatus": "High",
"batteryLevel": 88,
"lastSyncTime": "2026-03-04T07:05:00Z",
"deviceVersion": "Charge 6",
"macAddress": "00:11:22:33:44:55",
"features": [
"STEPS",
"HEART_RATE"
]
}
]
}שליחת שאילתה לגבי נתונים היסטוריים
אחד היתרונות העיקריים של Google Health API הוא היכולת לעקוב אחרי הביצועים של המשתמש ולנטר את המדדים החיוניים שלו לאורך תקופות ארוכות. אפשר לשלוח שאילתה לגבי נתוני משתמשים עד לנקודה שבה הם נרשמו. ה-API לא מטיל מגבלות על כמות הנתונים ההיסטוריים שאפליקציה יכולה לצרוך.
עם זאת, שאילתות של נתונים היסטוריים עדיין כפופות למגבלות הקצב הרגילות. כדי לשמור על יציבות המערכת ולמנוע עומסים גדולים מדי, Google Health API משתמש בחלוקה אוטומטית לדפים עם גדלים ספציפיים של דפים לנקודות קצה. חשוב לשים לב לגבולות ולמאפיינים הבאים:
- חלוקה אוטומטית לדפים: אם שולחים שאילתה לגבי טווח ארוך של נתונים, ה-API יחזיר רק את הדף הראשון של התוצאות עד למגבלת גודל הדף של נקודת הקצה הזו, יחד עם
nextPageToken. כדי לבקש דפים נוספים, צריך להשתמש ב-nextPageToken. - גדלים משתנים של דפים: מגבלות הקיבולת תלויות בנקודת הקצה ובסוג הנתונים. ברוב סוגי הנתונים, גודל הדף מוגבל ל-10,000.
עם זאת, עבור סוגי נתונים מסוימים כמו
exerciseו-sleep, גודל הדף המקסימלי וגודל הדף שמוגדר כברירת מחדל מוגבל ל-25. לדוגמה, אם לקוח מבקש את כל נתוני השינה מ-10 השנים האחרונות, ה-API עדיין יחזיר רק 25 סשנים של שינה בדף הראשון. - הגבלות על טווח התאריכים של נתוני סיכום: בנקודות קצה של סיכום וצבירה של נתונים
(כמו
rollUpו-dailyRollUp), טווחי התאריכים של השאילתות מוגבלים על סמך סוג הנתונים:- טווח מקסימלי של 14 ימים ל-
calories-in-heart-rate-zone,heart-rate,active-minutesו-total-calories. - טווח מקסימלי של 90 יום לכל שאר סוגי הנתונים המצטברים.
- טווח מקסימלי של 14 ימים ל-
בהתאם לנפח הנתונים ההיסטוריים שנדרשים לאפליקציה, כדי לאחזר את מערך הנתונים כולו צריך להשתמש בדפדוף בין הדפים באופן רציף. חשוב לזכור את זה כשמתכננים את תהליך סנכרון הנתונים של האפליקציה.
כדי להבטיח ביצועים אופטימליים ולמנוע שגיאות ב-API, כדאי לפעול לפי ההנחיות הבאות כששולחים שאילתות לגבי נתונים היסטוריים:
סנכרון נתונים בשלבים (טעינה חמה לעומת הפעלה מההתחלה)
- טעינה ראשונית של נתונים 'פעילים': במהלך רצף הטעינה העיקרי, המערכת מאחזרת ומציגה רק את הנתונים מ-7 עד 14 הימים האחרונים. כך המשתמשים יכולים לראות את הנתונים באופן מיידי בלי לחכות לשאילתות ארוכות.
- טעינה "קרה" ברקע: אחזור של נתונים היסטוריים ישנים יותר מועבר לתור אסינכרוני בעדיפות נמוכה יותר או לתהליך ברקע אחרי שהממשק הראשי מוצג.
חלוקת שאילתות לחלקים לצורך צבירה
- מכיוון שבנקודות הקצה של סיכום הנתונים וסיכום הנתונים היומי יש מגבלה על טווח התאריכים (14 או 90 ימים, בהתאם לסוג הנתונים), צריך לפצל שאילתות גדולות של צבירת נתונים היסטוריים למרווחים קטנים יותר שמוגדרים ברצף, במסגרת המגבלות האלה.
- כדי לכבד את מגבלות הריצה המקבילה ולשמור על אינדיקטורים יציבים של התקדמות ממשק המשתמש, מומלץ להריץ את שאילתות המשנה האלה בקבוצות או ברצף.
שימוש בסיכומי נתונים מצטברים שהוגדרו מראש
ארגון מחדש של לוחות הבקרה של הסקירה הכללית ושל תרשימי המגמות כך שישתמשו בנקודות קצה של סיכום שעברו צבירה מראש (כמו DailyRollUpDataPoints). כך יצטמצם באופן משמעותי העומס על המחשוב בשרת העורפי וזמן העברת הנתונים ללקוח.
טיפול בשגיאות בצורה גמישה (ניסיונות חוזרים חכמים)
- צריך להטמיע טיפול קפדני בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) כשנתקלים במגבלות קצב (
429 Too Many Requests) ובפסק זמן של שער השרת (504 Gateway Timeout). אסור לנסות שוב מיד לשלוח מטען ייעודי גדול שנכשל. ניסיונות חוזרים מיידיים מגבירים את העומס על השרתים ומחמירים את הירידה בביצועי המערכת.