סינון נתונים

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

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

מוסכמות סינון

המסננים ב-Google Health API מוטמעים בהתאם לתקן של הצעות לשיפור Google API‏ (AIP-160).

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

המסננים מועברים באמצעות מחרוזת השאילתה של כתובת ה-URL בפרמטר filter. מכיוון שהמסננים מכילים תווים מיוחדים (כמו <, >= ומרכאות), צריך לבצע קידוד URL כשמעבירים אותם בבקשת ה-HTTP.

לדוגמה, בקשה עם המסנן steps.interval.civil_start_time >= "2026-03-04T00:00:00" צריכה להיות מוצפנת כך:

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
  ?filter=steps.interval.civil_start_time%20%3E%3D%20%222026-03-04T00%3A00%3A00%22

פורמט השם

אם סוג הנתונים כולל יותר ממילה אחת, הפורמט של המזהה שונה בין נתיב המשאב לבין המסנן:

  • נתיב נקודת הקצה: משתמשים במקפים (לדוגמה, /dataTypes/body-fat).
  • מחרוזת סינון: משתמשים בקו תחתון (לדוגמה, body_fat).

אם משתמשים במקפים במזהה המסנן, ה-API מחזיר 400 Bad Requestעם סיבת השגיאה INVALID_DATA_POINT_FILTER.

סוגי מסננים ושדות

השדות שבהם משתמשים במסנן תלויים בסוג הרשומה של סוג הנתונים ששולחים לגביו שאילתה. בטבלה הבאה מתוארים השדות הנתמכים לכל סוג רשומה:

סוג הרשומה תיאור שדות סינון נתמכים
Interval נקודות נתונים שנרשמו לאורך תקופה מסוימת (לדוגמה, steps, distance, calories). {dataType}.interval.start_time
{dataType}.interval.civil_start_time

לדוגמה:
steps.interval.civil_start_time
דוגמה תצפיות מיידיות או מדידות קצרות (לדוגמה, weight, ‏ body-fat, ‏ blood-glucose). {dataType}.sample_time.physical_time
{dataType}.sample_time.civil_time

לדוגמה:
body_fat.sample_time.physical_time
מדי יום מדדים וסיכומים יומיים (לדוגמה, daily-heart-rate-variability). {dataType}.date

לדוגמה:
daily_heart_rate_variability.date
סשן סשנים ממושכים של משתמשים עם כללי תזמון מיוחדים. פעילות גופנית: {dataType}.interval.civil_start_time
שינה: sleep.interval.end_time, sleep.interval.civil_end_time
אק"ג: electrocardiogram.interval.start_time

דוגמה:
sleep.interval.civil_end_time

אופרטורים וכללים לפורמט שנתמכים

ביטויי הסינון צריכים לעמוד בכללי הפורמט הבאים:

אופרטורים להשוואה

יש תמיכה רק בשני אופרטורים להשוואה:

מפעיל תיאור
>= הגבול התחתון (כולל).
< הגבול העליון (לא כולל).

שימוש באופרטורים אחרים להשוואה (כמו >,‏ <= או =) מחזיר 400 Bad Request עם INVALID_DATA_POINT_FILTER_RESTRICTION_COMPARATOR.

אופרטורים לוגיים

מפעיל תמיכה
AND אופרטור ברירת המחדל והאופרטור היחיד שנתמך. משמש לשילוב של גבולות התחלה וסיום.
OR אין תמיכה השימוש ב-OR מחזיר 400 Bad Request עם סיבת השגיאה INVALID_DATA_POINT_FILTER_EXPRESSION_STRUCTURE ("המסנן חייב להיות צירוף או רצף של הגבלות. נמצא: DISJUNCTION").

ערכים מילוליים של זמן

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

סוג השעה דרישות דוגמאות
זמן פיזי פורמט RFC 3339, שמסתיים ב-Z או בהפרש משעון UTC. מייצג אירועים מהעולם האמיתי לפי שעון UTC. נכון: "2026-03-01T00:00:00Z", "2026-03-01T00:00:00-08:00"
לא נכון: "2026-03-01"
זמן אזרחי פורמט ISO 8601: ‏ YYYY-MM-DD[THH:mm:ss]. מייצג את השעה בשעון של המשתמש, בלי קשר למיקום או להפרשי אזורי הזמן. נכון: "2026-03-01", "2026-03-01T08:30:00"

כללים לאימות מסננים

המסננים פועלים לפי הכללים הבאים:

כלל תיאור דוגמאות
אין סוגי זמן מעורבים לא כדאי לערבב בין גבולות פיזיים וגבולות של זמן אזרחי. לא תקין: steps.interval.start_time >= "2026-03-01T00:00:00Z" AND steps.interval.civil_start_time < "2026-03-02"
שגיאה: INVALID_DATA_POINT_FILTER_MIXED_TIME_RESTRICTIONS ("המסנן לא יכול להכיל טווחי זמן פיזיים וגם טווחי זמן אזרחיים")
אין סוגי נתונים מעורבים משתמשים בשדות ששייכים לסוג הנתונים בנתיב הבקשה. לא תקין: נתיב /users/.../dataTypes/steps/... עם מסנן distance.interval.start_time >= "..."
שגיאה: INVALID_DATA_POINT_FILTER_COLLECTION_MISMATCH ("סוג הנתונים במסנן לא תואם לסוג הנתונים של אוסף האב")
לוגיקה של סדר הזמנים הגבול העליון חייב להיות גדול מהגבול התחתון. לא תקין: steps.interval.start_time >= "2026-03-02T00:00:00Z" AND steps.interval.start_time < "2026-03-01T00:00:00Z"
שגיאה: INVALID_TIME_RANGE ("שעת הסיום של השאילתה חייבת להיות גדולה משעת ההתחלה")
פורמט בקשת התמיכה צריך להשתמש ב-snake case בהתאם לשם סוג הנתונים. לא תקין: body-fat.sample_time.physical_time >= "..."
שגיאה: INVALID_DATA_POINT_FILTER ("מסנן לא תקין")

ה-API מחזיר HTTP 400 Bad Request למסננים לא תקינים. בודקים את error.details[].metadata.detailedReasons כדי לראות את קוד הסיבה לשגיאה.

היקפי הרשאות נדרשים של OAuth

כדי לשלוח שאילתות לנקודות נתונים באמצעות מסננים, המשתמש המורשה צריך להעניק את היקף OAuth הרלוונטי לסוג הנתונים הזה. אם ההיקף הנדרש חסר, ה-API מחזיר סטטוס 403 Forbidden עם MISSING_OAUTH_SCOPE.

בטבלה הבאה מפורטים היקפי ההרשאות של OAuth וסוגי הנתונים שאליהם הם מעניקים גישת קריאה. הטבלה מציגה את ההיקפים בפורמט היחסי שלהם (לדוגמה, .activity_and_fitness.readonly מייצג https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly):

היקף הרשאות OAuth נדרש סוגי נתונים
.activity_and_fitness.readonly active-energy-burned, active-minutes, active-zone-minutes, activity-level, altitude, calories-in-heart-rate-zone, daily-vo2-max, distance, exercise, floors, run-vo2-max, sedentary-period, steps, swim-lengths-data, time-in-heart-rate-zone, total-calories, vo2-max
.ecg.readonly אלקטרוקרדיוגרם
.health_metrics_and_measurements.readonly blood-glucose, body-fat, core-body-temperature, daily-heart-rate-variability, daily-heart-rate-zones, daily-oxygen-saturation, daily-respiratory-rate, daily-resting-heart-rate, daily-sleep-temperature-derivations, heart-rate, heart-rate-variability, height, oxygen-saturation, respiratory-rate-sleep-summary, skin-temperature-sensors, weight
.irn.readonly irregular-rhythm-notification
.nutrition.readonly אוכל, יחידת מידה של אוכל, יומן מעקב אחר מאזן הנוזלים, יומן מעקב אחר תזונה
.sleep.readonly שינה

אם ללקוח שלכם מוענק היקף הרשאות כתיבה בלבד (לדוגמה, .activity_and_fitness.writeonly) עבור סוג נתונים מסוים שנדרש, עדיין תוכלו לשלוח שאילתות לגבי נקודות נתונים שהלקוח שלכם כתב. במקרה הזה, הבקשות מוגבלות באופן מרומז למשפחת מקורות הנתונים self-sources. פרטים נוספים ומגבלות על סוגי הנתונים מופיעים במאמר סינון לפי משפחה של מקורות נתונים.

תרחישי שימוש ודוגמאות

בדוגמאות הבאות מוסבר איך ליצור מסננים לתרחישים נפוצים:

שאילתת שלבים לפי טווח זמן פיזי

שאילתת שלבים שתועדו בין 2026-03-01T00:00:00Z (כולל) לבין 2026-03-02T00:00:00Z (לא כולל):

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
  ?filter=steps.interval.start_time >= "2026-03-01T00:00:00Z"
  AND steps.interval.start_time < "2026-03-02T00:00:00Z"

שאילתת שלבים לפי טווח זמן אזרחי

שלבי שאילתה ליום שלם, 4 במרץ 2026, ביחס לשעון המקומי של המשתמש:

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
  ?filter=steps.interval.civil_start_time >= "2026-03-04"
  AND steps.interval.civil_start_time < "2026-03-05"

שאילתה לגבי אחוז השומן בגוף לפי זמן הדגימה הפיזית

שאילתה לגבי מדידות של אחוז השומן בגוף שתועדו החל ממרץ 2026 (לפי שעון UTC):

GET https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints
  ?filter=body_fat.sample_time.physical_time >= "2026-03-01T00:00:00Z"

משקל השאילתה לפי זמן הדגימה האזרחי

יומנים של משקלי שאילתות שנרשמו אחרי שעה מקומית מסוימת:

GET https://health.googleapis.com/v4/users/me/dataTypes/weight/dataPoints
  ?filter=weight.sample_time.civil_time >= "2026-03-01T08:00:00"

שאילתת סיכומים יומיים של שונות קצב הלב

שאילתה לגבי סיכומים יומיים של שונות קצב הלב (HRV) שנרשמו לפני תאריך מסוים:

GET https://health.googleapis.com/v4/users/me/dataTypes/daily-heart-rate-variability/dataPoints
  ?filter=daily_heart_rate_variability.date < "2026-08-15"

שאילתת סשנים של תרגילים לפי שעת התחלה אזרחית

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

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
  ?filter=exercise.interval.civil_start_time >= "2026-03-01"
  AND exercise.interval.civil_start_time < "2026-03-08"

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

שאילתות לגבי רשומות שינה לפי שעת הסיום של הסשן:

GET https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints
  ?filter=sleep.interval.civil_end_time >= "2026-03-04T05:00:00"
  AND sleep.interval.civil_end_time < "2026-03-04T12:00:00"

שאילתת אק"ג לפי שעת התחלה

שליחת שאילתה לגבי הקלטות של בדיקות אק"ג החל מנקודת זמן פיזית לפי שעון UTC. שימו לב: שאילתות ECG תומכות רק בהשוואה >= ב-start_time:

GET https://health.googleapis.com/v4/users/me/dataTypes/electrocardiogram/dataPoints
  ?filter=electrocardiogram.interval.start_time >= "2026-03-10T12:00:00Z"

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

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

כל נקודות הקצה list,‏ reconcile,‏ rollUp ו-dailyRollUp תומכות בפרמטר dataSourceFamily. מנגנון ההעברה תלוי בנקודת הקצה:

נקודת קצה (שיטת HTTP) מנגנון
list (GET) מעבירים את dataSourceFamily כפרמטר של שאילתה בכתובת URL.
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).
users/me/dataSourceFamilies/self-sources כולל רק את הנתונים שהלקוח המבצע כתב באמצעות Google Health API (נקודות נתונים שמקור הנתונים שלהן נרשם באמצעות ה-API עם אותו מזהה לקוח OAuth כמו של הלקוח המבצע).

אם אין נקודת נתונים שתואמת למשפחת מקור הנתונים המבוקשת, התשובה היא רשימה ריקה ולא שגיאה.

הרשאות קריאה בלבד ומקורות עצמיים

מתקשרים שמקבלים הרשאות כתיבה בלבד (כמו .activity_and_fitness.writeonly) לסוגי הנתונים המבוקשים יכולים לקרוא את הנתונים שהם כתבו בעצמם, ורק את הנתונים האלה.

  • בקשות ללא הפרמטר dataSourceFamily או עם הפרמטר dataSourceFamily שהערך שלו הוא users/me/dataSourceFamilies/self-sources, מוגבלות באופן מרומז ל-self-sources.
  • בקשה של כל משפחה אחרת של מקורות נתונים (כמו all-sources, google-wearables או google-sources) עם היקף כתיבה בלבד תיכשל עם שגיאה 403 Forbidden (PERMISSION_DENIED).

מגבלות על סוגי הנתונים בנקודת הקצה של הרשימה

בנקודת הקצה list (users.dataTypes.dataPoints.list), סינון לפי dataSourceFamily לא נתמך עבור סוגי הנתונים sleep,‏ food ו-food-measurement-unit:

  • הגדרה מפורשת של dataSourceFamily ב-list עבור sleep,‏ food או food-measurement-unit נכשלת עם שגיאה 400 Bad Request (INVALID_ARGUMENT).
  • קריאה ל-list עבור סוגי הנתונים האלה כשניתנת רק הרשאת כתיבה (כשההגבלה ל-self-sources משתמעת מההיקפים של המתקשר) נכשלת עם השגיאה 403 Forbidden (PERMISSION_DENIED).
  • כדי לסנן נקודות על הגרף sleep לפי dataSourceFamily, צריך להשתמש בנקודת הקצה reconcile במקום זאת.

דוגמאות למשפחות של מקורות נתונים

כדי להציג רשימה של נקודות נתונים גולמיות שנכתבו על ידי הלקוח שלכם עבור משתמש, צריך להתקשר לנקודת הקצה list כשפרמטר השאילתה dataSourceFamily מוגדר ל-users/me/dataSourceFamilies/self-sources.

לדוגמה, בקשת ה-GET הבאה מפרטת את המדידות הגולמיות של body-fat שנכתבו על ידי הלקוח המתקשר החל מ-2026-03-01:

בקשה

GET https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints
  ?dataSourceFamily=users/me/dataSourceFamilies/self-sources
  &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 עם פרמטר השאילתה 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"
      }
    }
  ]
}
הקודם
נקודות קצה
הבא
נתונים מצטברים