נקודות קצה

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

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

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

לדוגמה:

בקשה

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.

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

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

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

אפשר להשתמש ב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/2515055256096816351/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

תשובה

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