‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

נקודות קצה

בדף הזה מופיעה סקירה כללית של מוסכמות 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"
}

סנן נתונים

כדי לאחזר קבוצות משנה ספציפיות של רשומות נקודות על הגרף שתואמות לקריטריונים כמו מרווח זמן, תאריך או זמן תצפית, משתמשים בנקודת הקצה list או reconcile עם פרמטר filter.

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

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

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

הנחיות מפורטות, משפחות נתמכות ודוגמאות לבקשות ולתגובות של reconcile, rollUp ו-dailyRollUp זמינות במאמר סינון לפי משפחה של מקור נתונים במדריך לסינון נתונים.

סינון נתונים לפי שעת התחלה אזרחית של מרווח זמן

משתמשים בנקודת הקצה list עם הפרמטר filter כדי לסנן נתונים לפי זמן אזרחי או לפי מרווח.

חשוב: הפורמט של מזהי סוגי הנתונים שונה כשסוג הנתונים כולל יותר ממילה אחת. בנקודת קצה, שם סוג הנתונים צריך להיות בפורמט kebab case, כמו body-fat. בפרמטר של מסנן, לעומת זאת, שם סוג הנתונים צריך להיות בפורמט snake case, למשל body_fat.

לדוגמה:

בקשה

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, צריך לספק את גוף הבקשה שמייצג את טווח התאריכים הנדרש בשעון המקומי של המשתמש. לדוגמה:

בקשה

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": "30s"
}

תשובה

{
  "rollupDataPoints": [
    {
      "startTime": "2026-02-17T17:55:00Z",
      "endTime": "2026-02-17T17:55:30Z",
      "steps": {
        "countSum": "41"
      }
    },
    {
      "startTime": "2026-02-17T17:54:00Z",
      "endTime": "2026-02-17T17:54:30Z",
      "steps": {
        "countSum": "31"
      }
    },
...
  ]
}

צבירת נתונים על פני יום אחד או כמה ימים

צריך להשתמש בנקודת הקצה 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 at range.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"
      }
    }
  ]
}

עדכון נתוני בריאות וכושר של משתמש

כדי לעדכן את נתוני הבריאות וכושר של משתמש, משתמשים בנקודת הקצה patch.

נקודת הקצה patch מעדכנת רשומה קיימת על סמך המזהה שצוין בכתובת ה-URL של הבקשה. מזינים את המזהה של נקודת נתונים שהוזנה בעבר. ה-API מחליף את הרשומה הקיימת.

מתי כדאי להשתמש במזהה של נקודה על הגרף

מזהה נקודת הנתונים חיוני בתרחישים הבאים:

עדכונים ממוקדים: כדי לעדכן מדידה ספציפית, צריך לציין את המזהה שלה בבקשת 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
    }
  }
}

רישום פריט מזון

כדי לתעד פריט מזון, שולחים בקשת 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 יום לכל שאר סוגי הנתונים המצטברים.

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

כדי להבטיח ביצועים אופטימליים ולמנוע שגיאות ב-API, כדאי לפעול לפי ההנחיות הבאות כששולחים שאילתות לגבי נתונים היסטוריים:

סנכרון נתונים בשלבים (טעינה חמה לעומת הפעלה מההתחלה)

טעינה ראשונית של נתונים 'פעילים': במהלך רצף הטעינה העיקרי, המערכת מאחזרת ומציגה רק את הנתונים מ-7 עד 14 הימים האחרונים. כך המשתמשים יכולים לראות את הנתונים באופן מיידי בלי לחכות לשאילתות ארוכות.
טעינה "קרה" ברקע: אחזור של נתונים היסטוריים ישנים יותר מועבר לתור אסינכרוני בעדיפות נמוכה יותר או לתהליך ברקע אחרי שהממשק הראשי מוצג.

חלוקת שאילתות לחלקים לצורך צבירה

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

שימוש בסיכומי נתונים מצטברים שהוגדרו מראש

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

טיפול בשגיאות בצורה גמישה (ניסיונות חוזרים חכמים)

יש ליישם טיפול קפדני ב-השהיה מעריכית לפני ניסיון חוזר (exponential backoff) בעת נתקלות ב-הגבלת קצב של יצירת בקשות (429 Too Many Requests) ובפסק זמן של שער שרת (504 Gateway Timeout). לעולם אל תנסה שוב מטענים ייעודיים גדולים שנכשלו באופן מיידי. ניסיונות חוזרים מיידיים מגבירים את העומס על השרתים ומחמירים את הירידה בביצועי המערכת.

ספריות לקוח

מסננים

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

מוסכמות של API בארכיטקטורת REST

פרמטרים של שאילתה

גוף הבקשה

המקרה ההיברידי

הבדלים מרכזיים במבט מהיר

תאריכים

כותרות

אינדקס של משימות API

איך מוצאים את מזהה המשתמש ב-Fitbit או ב-Google

בקשה

תשובה

קבלת נתונים מפורטים או נתונים המתקבלים במשך היום שנאספים במהלך יום

בקשה

תשובה

סנן נתונים

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

סינון נתונים לפי שעת התחלה אזרחית של מרווח זמן

בקשה

תשובה

סינון נתונים לפי זמן פיזי של תצפית לדוגמה

בקשה

תשובה

סינון וצבירה לפי משפחה של מקורות נתונים

משפחות של מקורות נתונים נתמכים

בקשה

תשובה

בקשה

תשובה

בקשה

תשובה

צבירה של נקודות נתונים בטווח זמן מסוים

בקשה

תשובה

צבירת נתונים על פני יום אחד או כמה ימים

בקשה

תשובה

חלוקה לקטגוריות כשטווח לא מתחלק בגודל החלון

איך פועל תהליך ההעברה לדלי

תרחיש: טווח של 12 דקות עם חלון של 5 דקות

ההשפעה על ערכים נצברים

דוגמה לתגובה של API שמציגה הזמנה

עדכון נתוני בריאות וכושר של משתמש

מתי כדאי להשתמש במזהה של נקודה על הגרף

בקשה

תשובה

רישום פריט מזון

בקשה

תשובה

מחיקת נתוני בריאות וכושר של משתמשים

בקשה

תשובה

איך מוצאים מידע על מכשיר

בקשה

תשובה

שליחת שאילתה לגבי נתונים היסטוריים

סנכרון נתונים בשלבים (טעינה חמה לעומת הפעלה מההתחלה)

חלוקת שאילתות לחלקים לצורך צבירה

שימוש בסיכומי נתונים מצטברים שהוגדרו מראש

טיפול בשגיאות בצורה גמישה (ניסיונות חוזרים חכמים)

נקודות קצה