נקודות קצה

בדף הזה מופיעה סקירה כללית של מוסכמות 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 עם הפרמטר 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/2515055256096816351/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.

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

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

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

לדוגמה, משתמש תיעד את אחוז השומן בגוף שלו באמצעות משקל שנקרא 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-length: 329

{
  "name": "bodyFatName",
  "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/2515055256096816351/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
    }
  }
}

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

כדי למחוק מערך של נתונים מאפליקציית Fitbit של משתמש, משתמשים בנקודת הקצה batchDelete.

לדוגמה, משתמש תיעד בעבר את אחוז השומן בגוף שלו באמצעות משקל, אבל הוא רוצה למחוק את התיעוד. שימוש ב-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/2515055256096816351/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

תשובה

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
  }
}

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

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

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

  • כל נקודת קצה מחזירה גודל דף מקסימלי של 10,000 נקודות נתונים לכל דף.
  • טווח התאריכים של השאילתה מוגבל ל-14 עד 90 ימים לכל בקשה.

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