重要事項：2026 年 9 月 30 日起，我們將停止支援舊版 Fitbit Web API。2026 年 11 月 2 日起，舊版 Fitbit Web API 和 Fitbit OAuth 端點將關閉，不再運作或與 Fitbit 使用者同步資料。如要在上述日期後繼續存取使用者資料，請改用 Google Health API。如需遷移指南，請參閱「Fitbit Web API 遷移指南」。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

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 格式顯示。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 使用者 ID

使用者透過 Google OAuth 2.0 同意後，權杖回應不會包含 Fitbit 或 Google 使用者 ID。交換授權碼後，請立即呼叫 getIdentity 端點，擷取 legacyUserId 和 healthUserId，並確認使用者的 Google 帳戶已連結至 Google Health。如果帳戶尚未連結，getIdentity 會傳回 400 Bad Request，原因為 ACCOUNT_NOT_LINKED (請參閱「處理未連結的 Google 帳戶」)。

例如：

要求

GET https://health.googleapis.com/v4/users/me/identity
Authorization: Bearer access-token
Accept: application/json

回應 (200 OK)

{
  "name": "users/me/identity",
  "legacyUserId": "A1B2C3",
  "healthUserId": "111111256096816351"
}

回應 (400 ACCOUNT_NOT_LINKED)

{
  "error": {
    "code": 400,
    "message": "The account is not linked to Google Health.",
    "status": "FAILED_PRECONDITION",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "ACCOUNT_NOT_LINKED",
        "domain": "health.googleapis.com",
        "metadata": {
          "redirect_uri": "https://fitbit.google.com/auth/signup"
        }
      }
    ]
  }
}

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

使用特定資料類型的 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 參數，依民用時間或間隔篩選資料。

重要事項：如果資料類型有多個字詞，資料類型 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/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)	在 JSON 要求主體中，將 `dataSourceFamily` 做為欄位傳遞。
`dailyRollUp` (POST)	在 JSON 要求主體中，將 `dataSourceFamily` 做為欄位傳遞。

支援的資料來源系列

下表說明支援的 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-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 端點，並在 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 端點，根據以秒為單位的時間範圍 (windowSize)，傳回使用者實際時間 (世界標準時間) datetime 範圍內的資料點匯總。

呼叫 rollUp 端點時，請提供代表所需閉合時間 range 和 windowSize (至少 "1s") 的要求主體。如需 windowSize 需求、儲存空間解析度調整、分桶規則，以及要求和回應範例的詳細指南，請參閱「匯總資料」指南中的「匯總實體時間間隔」。

匯總單日或多日的資料

使用 dailyRollUp 端點匯總單日或多日 (windowSizeDays) 的資料。在要求主體中，提供所需時間間隔的閉開民用時間 range。端點會根據資料類型，傳回每個時間範圍的總和或平均值。

如要進一步瞭解每日匯總行為、民用時間處理、每個要求的範圍限制，以及要求和回應範例，請參閱「匯總資料」指南中的「匯總日曆日的資料」。

更新使用者的健康資料

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

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

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

資料點 ID 的使用時機

在下列情況下，資料點 ID 是不可或缺的：

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

以下範例說明使用者如何更新「Scales R Us」公司「HumanScale」體重計上的體脂肪讀數。使用者在 2026-03-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
    }
  }
}

更新現有資料的時間間隔時間戳記

如要更新現有資料點的時間間隔時間戳記 (REST JSON 酬載中的 startTime 和 endTime，或 gRPC 中的 start_time 和 end_time)，請將 PATCH 要求傳送至資料點的資源 URI。只有記錄的原始建立者或擁有者才能修改欄位。應用程式無法編輯非其建立的資料點。

如需時間戳記可變性、Health Connect 上游更新和快取影響的背景資訊，請參閱資料管理指南。

以下範例示範擁有者應用程式如何使用 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 要求。要求主體包含 DataPoint 和 nutritionLog 物件。詳情請參閱營養指南。

例如：

要求

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) 時，請實施嚴格的指數輪詢處理。請勿立即重試大型失敗酬載。立即重試會加劇後端壅塞，並加劇系統效能降低。

用戶端程式庫

篩選器

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

REST API 慣例

查詢參數

要求主體

混合案例

主要差異一覽

日期

標頭

API 工作索引

取得 Fitbit 或 Google 使用者 ID

要求

回應 (200 OK)

回應 (400 ACCOUNT_NOT_LINKED)

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

要求

回應

查看經過對帳的間隔資料

原始清單

已協調

篩選資料

依資料來源系列篩選

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

要求

回應

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

要求

回應

依資料來源系列篩選及匯總

支援的資料來源系列

要求

回應

要求

回應

要求

回應

匯總一段時間內的資料點

匯總單日或多日的資料

更新使用者的健康資料

資料點 ID 的使用時機

要求

回應

更新現有資料的時間間隔時間戳記

要求

回應

記錄食物

要求

回應

刪除使用者健康資料

要求

回應

查看裝置資訊

要求

回應

查詢歷來資料

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

查詢匯總資料區塊

運用預先匯總的匯總資料

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

Endpoint