重要提示：自 2026 年 9 月 30 日起，我们已停止对旧版 Fitbit Web API 的支持。2026 年 11 月 2 日，旧版 Fitbit Web API 和 Fitbit OAuth 端点将停用，并且将不再运行或与 Fitbit 用户同步数据。如需在此日期之后继续访问用户的数据，请迁移到 Google Health API。如需迁移指南，请参阅 Fitbit Web API 迁移指南。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

端点

本页面简要介绍了 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 参数搭配使用，可按民用时间或时间间隔过滤数据。

重要提示：如果数据类型包含多个字词，则数据类型标识符的格式会有所不同。在端点中，数据类型名称必须采用烤串命名法，例如 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": ""
}

按数据源系列进行过滤和汇总

数据源系列是数据源（例如智能手表、移动应用或手动条目）的逻辑分组。借助该 API，您可以隔离或汇总来自特定类型来源（例如，实体穿戴式设备与手动条目）的数据。

reconcile、rollUp 和 dailyRollUp 端点都支持 dataSourceFamily 参数。传递机制取决于端点：

端点（HTTP 方法）	机制
`reconcile` (GET)	将 `dataSourceFamily` 作为网址查询参数传递。
`rollUp`（投放后）	在 JSON 请求正文中将 `dataSourceFamily` 作为字段传递。
`dailyRollUp`（投放后）	在 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 健身）手动记录的所有条目。

如需从特定数据源系列获取经过校准的数据流，请使用 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) 返回用户实际时间（采用世界协调时间 [UTC]）中 datetime 范围内的数据点汇总。

调用 rollUp 端点时，请提供表示所需闭开时间 range 和 windowSize（至少 "1s"）的请求正文。如需详细了解 windowSize 要求、存储分辨率对齐、分桶规则以及请求和响应示例，请参阅“汇总数据”指南中的按物理时间间隔汇总。

汇总单日或多日的数据

使用 dailyRollUp 端点汇总单日或多日 (windowSizeDays) 的数据。在请求正文中提供所需时间间隔的闭开民用时间 range。根据数据类型，端点会返回每个时间段内的总和或平均值。

如需详细了解每日汇总行为、民用时间处理、每次请求的范围限制以及请求和响应示例，请参阅“汇总数据”指南中的跨日历日汇总。

更新用户的健康数据

使用 patch 端点更新用户的健康数据。

patch 端点会根据请求网址中指定的标识符更新现有记录。提供之前插入的数据点的标识符。API 会覆盖现有记录。

数据点的间隔时间戳（startTime 和 endTime）也可以由记录的所有者更新，或从健康数据共享等上游平台传播。如需详细了解时间戳可变性，请参阅数据管理指南。如需查看更新间隔时间戳的示例，请参阅更新现有数据的间隔时间戳。

何时使用数据点标识符

在以下情况下，数据点标识符至关重要：

有针对性的更新：如需更新特定测量，请在 patch 请求中提供其标识符。
删除：保留标识符可让您的应用稍后使用 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
    }
  }
}

更新现有数据的时间间隔时间戳

如需更新现有数据点的时间间隔时间戳（REST JSON 载荷中的 startTime 和 endTime，或 gRPC 中的 start_time 和 end_time），请向数据点的资源 URI 发送 PATCH 请求。只有记录的原始创建者或所有者才能修改其字段。应用无法修改其未创建的数据点。

如需了解时间戳可变性、健康数据共享的上游更新以及缓存影响，请参阅数据管理指南。

以下示例演示了所有者应用如何使用 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 天的数据。这样可以确保用户立即看到数据，而无需等待长时间运行的查询。
后台“冷”加载：在主界面呈现后，将较旧的历史数据检索委托给异步、低优先级队列或后台进程。

查询分块以进行聚合

由于汇总和每日汇总端点会强制执行最大日期范围限制（14 天或 90 天，具体取决于数据类型），因此您必须将大型历史汇总查询拆分为这些限制范围内的较小连续时间间隔。
安全地对这些子查询进行批处理或排序，以遵守并发限制并保持稳定的界面进度指示器。

利用预汇总的汇总数据

重构概览信息中心和趋势图，以使用预先汇总的摘要端点（例如 DailyRollUpDataPoints）。这将大幅减少后端的计算开销以及到客户端的网络传输时间。

弹性错误处理（智能重试）

遇到速率限制 (429 Too Many Requests) 和服务器网关超时 (504 Gateway Timeout) 时，请实施严格的指数退避算法处理。切勿立即重试失败的大型载荷。即时重试会加剧后端拥塞并加剧系统性能下降。

客户端库

过滤条件

端点 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

REST API 惯例

查询参数

请求正文

混合情况

主要差异一览

日期

标头

API 任务索引

获取 Fitbit 或 Google 用户 ID

请求

响应 (200 OK)

响应 (400 ACCOUNT_NOT_LINKED)

获取全天收集的日内数据或详细数据

请求

响应

获取间隔数据的对账视图

原始列表

已协调

过滤数据

按数据源系列过滤

按间隔民用开始时间过滤数据

请求

响应

按样本观测物理时间过滤数据

请求

响应

按数据源系列进行过滤和汇总

支持的数据源系列

请求

响应

请求

响应

请求

响应

汇总一段时间内的数据点

汇总单日或多日的数据

更新用户的健康数据

何时使用数据点标识符

请求

响应

更新现有数据的时间间隔时间戳

请求

响应

记录食物

请求

响应

删除用户健康数据

请求

响应

查找设备信息

请求

响应

查询历史数据

分阶段数据同步（热加载与冷加载）

查询分块以进行聚合

利用预汇总的汇总数据

弹性错误处理（智能重试）

端点