Endpoint

本頁面概要說明 REST API 慣例，並提供常見 Google Health API 工作和各項工作的範例索引。

REST API 慣例

Google Health API 遵循 Google API 改進提案 (AIP) 標準，特別是 AIP-127 (HTTP 和 gRPC 轉碼) 和 AIP-131 至 AIP-135 (標準方法)。這些標準定義了如何將資料從 Proto 訊息對應至 HTTP 要求。

查詢參數

如果資料是網址的一部分，請使用查詢參數。這主要是用於 GET 要求 (擷取資源) 或 LIST 要求 (篩選/分頁)，但也用於 DELETE 作業。

  • 刊登位置：附加至 ? 後方的網址。
  • 語法：以 & 分隔的鍵/值組合。
  • 對應：要求訊息中不屬於網址路徑範本的每個欄位，都會對應至查詢參數。
  • 適用情況：簡單型別 (字串、整數、列舉) 和重複欄位。

語法範例：

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"

要求主體

當資料會修改資源狀態，或資料量過大而無法透過網址傳送時，就會使用要求主體。主體通常是資源本身的 JSON 表示法。通常用於 POST、PATCH 和 PUT 作業。

  • 位置：HTTP 酬載內 (網址中不會顯示)。
  • 語法：格式為 JSON 物件。
  • 對應：在 google.api.http 註解中定義。
    • body: "*" 表示整封郵件都是內文。
    • body: "resource_name" 表示只有 proto 中的特定欄位是主體。
  • 最佳用途：複雜物件、巢狀訊息和機密資料。

語法範例：

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"
}

混合型案例

在符合 AIP-134 規範的 Update 方法或 PATCH 作業中，這兩者都會用到。 網址包含資源名稱，主體包含更新的資源資料，而查詢參數 (通常是 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 指引 用於搜尋、篩選和讀取作業。 用於寫入作業。
瀏覽權限 顯示在瀏覽器記錄和伺服器記錄中。 網址中不會顯示。
複雜度 僅限平面或重複結構。 支援深層巢狀 JSON 物件。
編碼 必須經過網址編碼 (例如空格會變成 %20)。 標準 JSON 編碼。

日期

Google Health API 中的所有日期均以 YYYY-MM-DD 格式顯示。營養資訊 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 使用者 ID

使用者透過 Google OAuth 2.0 同意後，權杖回應不會包含 Fitbit 或 Google 使用者 ID。如要取得使用者 ID，請呼叫 getIdentity 端點。getIdentity 傳回 Fitbit 舊版使用者 ID 和 Google 使用者 ID。

建議您在新使用者透過 OAuth 同意後，立即呼叫 getIdentity 端點並儲存兩個使用者 ID。這可讓整合作業具備回溯和前向相容性。

例如：

要求

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 端點。系統會自動透過對帳端點，在同步處理批次和多個錄製裝置中，移除重疊的時間間隔，並傳回適合用於算繪活動時間軸和計算時長的連續授權串流。

如要瞭解連線裝置產生重疊間隔的原因，以及 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。
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 第一方來源。包括實體追蹤裝置記錄、「健康資料同步」資料，以及透過第一方應用程式 (例如 Fitbit 應用程式或 Google Fit) 手動輸入的任何資料。

如要從特定資料來源系列取得已對帳的資料串流，請使用 dataSourceFamily 查詢參數呼叫 reconcile 端點。

舉例來說，下列 GET 要求會擷取 2026 年 3 月 3 日之後的睡眠記錄：

要求

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 端點，並在 JSON 要求主體中傳遞 dataSourceFamily 欄位。

下列 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 範圍內以使用者實際時間 (世界標準時間) 為準的資料點匯總。

呼叫 rollUp 端點時，請提供代表必要時間範圍和 windowSize 的要求主體。請注意以下對 windowSize 的要求：

  • 時間範圍下限：windowSize 時間長度必須至少為 1 秒 ("1s")。如果時間長度小於 1 秒、為零或負數，系統會拒絕並傳回 400 Bad Request (INVALID_ROLLUP_WINDOW)。
  • 儲存空間解析度對齊：為避免匯總資料在子 bucket 間分布不均，請選擇大於或等於資料類型基礎儲存空間解析度的 windowSize (例如 1 分鐘步長間隔的 "60s")。詳情請參閱「匯總視窗大小和基礎儲存空間解析度」。

舉例來說，如要以 1 分鐘間隔彙整步數 (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"
      }
    },
...
  ]
}

彙整單日或多日的資料

如要匯總單日或多日資料 (即 windowSize)，請使用 dailyRollUp 端點。在要求主體中，提供所需間隔的半開半閉民用時間範圍。視資料類型而定，您會收到間隔內的總和或平均值。

例如：

要求

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)

每個值區都會從範圍開頭依序開始。如果新增另一個全尺寸視窗會超出要求結束時間，最後一個視窗會在範圍結束時間遭到截斷 (夾住)。

分組的運作方式

如果要求使用無法整除的範圍匯總，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. 值區 1： [10:00:00, 10:05:00) - 時間長度：5 分鐘 (全螢幕)
  2. 值區 2： [10:05:00, 10:10:00) - 時間長度：5 分鐘 (完整視窗)
  3. 值區 3 (已截斷)： [10:10:00, 10:12:00) - 時間長度：2 分鐘 (在 range.endTime 截斷)

對匯總值的影響

由於最終時間範圍的持續時間較短，因此在截斷的資料桶中，加總指標 (例如步數總和或計數) 會因時間軌跡較短而偏低。

如果使用者在這 12 分鐘內以每分鐘 100 步的穩定速度行走：

  • 第 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 會依時間倒序傳回結果，因此截斷的 bucket 會顯示在傳回清單的第一個元素中：

{
  "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 (1 秒以上)，但不同資料類型會以不同的取樣率或間隔時間，在基礎儲存空間中記錄及保存測量結果。舉例來說，穿戴式裝置的體能活動指標 (例如 steps、distance、active-minutes 和 active-energy-burned) 通常會以 1 分鐘 (60s) 為間隔記錄。

匯總間隔資料類型時，rollUp 端點會將每個記錄的資料點放入包含該資料點 startTime 的 bucket。API 不會將間隔資料切片、內插或分配到子間隔值區。

如果您指定的 windowSize 小於基礎資料儲存間隔 (例如，要求以 1 分鐘間隔儲存 steps 的 10 秒視窗)：

  1. 與間隔的 startTime 相符的第一個子區間 (例如 10:00:00 至 10:00:10) 會收到該分鐘累積的總數 (例如該分鐘記錄的所有 100 步)。
  2. 由於這些時間範圍內沒有間隔開始，因此該分鐘內其餘的子時間範圍 (10:00:10 至 10:00:20、10:00:20 至 10:00:30 等) 不會收到任何資料點。

這會導致「尖峰」資料，整個間隔的值都集中在第一個子視窗中。

如要取得平均分配且有意義的匯總資料，請一律將 windowSize 設為等於或大於目標資料類型基礎儲存空間解析度的時間長度 (例如，steps 的 60s 或更大)。如要瞭解各資料類型的儲存空間解析度和建議的最小匯總視窗，請參閱 Google Health API 資料類型參考資料。

更新使用者的健康資料

使用 patch 端點更新使用者的健康資料。

patch 端點會根據要求網址中指定的 ID，更新現有記錄。提供先前插入的資料點 ID。API 會覆寫現有記錄。

資料點的時間間隔時間戳記 (startTime 和 endTime) 也可由記錄擁有者更新，或從上游平台 (例如「健康資料同步」) 傳播。如要進一步瞭解時間戳記可變動性，請參閱資料管理指南。如需更新間隔時間戳記的範例，請參閱「更新現有資料的間隔時間戳記」。

資料點 ID 的使用時機

在下列情況中，資料點 ID 至關重要：

  • 指定更新：如要更新特定評估，請在 patch 要求中提供其 ID。
  • 刪除：保留 ID 可讓應用程式稍後使用 batchDelete 端點刪除記錄。

以下是範例：使用者在「Scales R Us」公司的「HumanScale」體重計上更新體脂肪讀數。使用者在 2026 年 3 月 10 日的體脂肪讀數為 20%：

要求

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。只有記錄的原始建立者或擁有者可以修改記錄的欄位。應用程式無法編輯自己未建立的資料點。

如要瞭解時間戳記可變動性、健康資料同步的上游更新，以及快取影響，請參閱資料管理指南。

以下範例說明擁有者應用程式如何使用 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
      }
    }
  }
}

記錄食物

如要記錄食物項目，請向 nutrition-log dataPoints 端點傳送 POST 要求。要求主體包含具有 nutritionLog 物件的 DataPoint。 詳情請參閱營養指南。

例如：

要求

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)，查詢日期範圍會根據資料類型受到限制：
    • calories-in-heart-rate-zone、heart-rate、active-minutes 和 total-calories 的範圍上限為 14 天。
    • 所有其他匯總資料類型的日期範圍上限為 90 天。

視應用程式需要的歷來資料量而定，如要擷取整個資料集，必須依序逐頁分頁。設計應用程式的資料同步程序時，請將這點納入考量。

為確保最佳效能並避免發生 API 錯誤，查詢歷來資料時請遵循下列準則：

分階段同步處理資料 (熱載入與冷載入)

  • 初始「熱」載入：在主要載入序列期間，只擷取並算繪最近 7 到 14 天的資料。這樣一來，使用者就能立即查看資料，不必等待長時間執行的查詢。
  • 背景「冷」載入：主要 UI 算繪完成後，將較舊的歷來資料擷取作業委派給非同步、低優先順序佇列或背景程序。

匯總查詢的查詢區塊

  • 由於匯總和每日匯總端點會強制執行日期範圍上限 (視資料類型而定，為 14 或 90 天)，因此您必須將大型歷來匯總查詢，分解為這些限制內較小的連續間隔。
  • 請安全地批次處理或依序執行這些子查詢，以免超出並行限制，並維持穩定的 UI 進度指標。

運用預先匯總的匯總資料

重新架構總覽資訊主頁和趨勢圖表，改用預先匯總的摘要端點 (例如 DailyRollUpDataPoints)。這會大幅減少後端的運算負荷，以及用戶端的網路傳輸時間。

彈性錯誤處理 (智慧重試)

  • 遇到速率限制 (429 Too Many Requests) 和伺服器閘道逾時 (504 Gateway Timeout) 時，請嚴格處理指數輪詢。切勿立即重試大型失敗的酬載。即時重試會加劇後端壅塞，並導致系統效能下降。