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 參數，依民用時間或時間間隔篩選資料。

例如：

要求

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 端點，取得特定「資料來源系列」的資料。如要執行此操作，請將 dataSourceFamily 參數指定為查詢參數。

下表說明支援的 dataSourceFamily 選項：

選項 說明
users/me/dataSourceFamilies/all-sources 預設值。包含所有可用資料來源的資料。
users/me/dataSourceFamilies/google-wearables 包括 Google 和 Fitbit 智慧手環裝置 (例如 Fitbit 智慧手環和 Pixel Watch) 的資料。不含手動記錄的資料。
users/me/dataSourceFamilies/google-sources 包括 Google 第一方資料，例如追蹤裝置資料和手動記錄的資料。

以下範例只會篩選 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
    }
  }
}

記錄食物

如要記錄食物，請將 POST 要求傳送至 nutrition-log 資料點端點。要求主體包含具有 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/2515055256096816351/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/2515055256096816351/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 對應用程式可使用的歷史資料量沒有限制。

不過，查詢歷來資料時，仍須遵守標準的速率限制。為減少相對於這些限制的 API 呼叫次數，Google Health API 支援查詢特定日期範圍內的資料。請注意下列分頁和要求界線：

  • 每個端點每頁最多可傳回 10,000 個資料點。
  • 每個要求查詢的日期範圍必須介於 14 到 90 天之間。

視應用程式需要的歷來資料量而定，擷取整個資料集可能需要多個連續請求，並花費額外時間。設計應用程式的資料同步程序時，請將這點納入考量。

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

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

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

以時間為依據將查詢分塊

  • 請勿在單一 API 呼叫中要求多年或多月的時間範圍。 將大型歷史記錄查詢拆分成較小的連續間隔 (例如每個要求 1 週)。
  • 請安全地批次處理或依序執行這些子查詢，以遵守並行限制，並維持穩定的 UI 進度指標。

運用預先匯總的匯總資料

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

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

  • 遇到速率限制 (429 Too Many Requests) 和伺服器閘道逾時 (504 Gateway Timeout) 時，請嚴格處理指數輪詢。切勿立即重試大型失敗的酬載。即時重試會加劇後端壅塞，並導致系統效能進一步下降。
  • 如果查詢持續逾時，系統會自動改用較小的時間範圍 (例如將 1 週縮短為 3 天)。