立即開始遷移或開發新應用程式！如果應用程式的使用者人數超過 100 人，則可自 3 月 30 日起申請驗證。

為確保使用者享有順暢體驗，建議您等到2026 年 5 月底再正式推出整合服務，與舊版 Fitbit 帳戶淘汰作業同步。請注意，從現在到 5 月底，我們可能會根據開發人員的意見回饋進行重大變更。

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

依間隔民事開始時間篩選資料

使用 list 端點和 filter 參數，依民用時間或時間間隔篩選資料。

重要事項：如果資料類型包含多個字詞，資料類型 ID 的格式會有所不同。在端點中，資料類型名稱必須採用 Kebab case，例如 body-fat。不過，在篩選器參數中，資料型別名稱必須採用蛇形命名法，例如 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/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 年 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 端點，根據以秒為單位的時間範圍，傳回 datetime 範圍內 (以世界標準時間為準) 使用者實際時間的資料點匯總。

呼叫 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"
      }
    },
...
  ]
}

彙整單日或多日的資料

如要匯總單日或多日資料 (又稱 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"
      }
    }
  ]
}

插入或更新使用者的健康資料

使用 patch 端點插入或更新使用者的 Fitbit 應用程式資料。

以下範例說明使用者如何透過「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-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"
  }
}

用戶端程式庫

通用連結和應用程式連結

Endpoint 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

REST API 慣例

查詢參數

要求主體

混合型案例

主要差異一覽

日期

標頭

API 工作索引

取得 Fitbit 或 Google 使用者 ID

要求

回應

取得當天收集的當日或詳細資料

要求

回應

依間隔民事開始時間篩選資料

要求

回應

依樣本觀察的實際時間篩選資料

要求

回應

依資料來源 (例如穿戴式裝置) 篩選資料

要求

回應

匯總一段時間內的資料點

要求

回應

彙整單日或多日的資料

要求

回應

插入或更新使用者的健康資料

要求

回應

刪除使用者健康資料

要求

回應

Endpoint