使用 Google Health API 開發營養和飲水體驗

Google Health API 提供資料類型，可追蹤使用者的營養和水分攝取。這些類型可讓您記錄餐點、參考食物資料庫中的食物、追蹤營養素數量，以及記錄液體攝取量。

支援的資料類型

表格：Google Health API 營養資料類型
資料類型 可用的
作業		 範圍
食物
dataType： food
篩選器參數： food
記錄類型： 飲食
 list、get .nutrition.readonly
.nutrition.writeonly
食物計量單位
dataType： food-measurement-unit
篩選器參數： food_measurement_unit
記錄類型： 飲食

相容裝置
list、get .nutrition.readonly
.nutrition.writeonly
飲水量記錄
dataType： hydration-log
篩選器參數： hydration_log
記錄類型： 工作階段
 list、get、reconcile、rollup、dailyRollup、create、update、batchDelete .nutrition.readonly
.nutrition.writeonly
營養記錄
dataType： nutrition-log
篩選器參數： nutrition_log
記錄類型： 工作階段

相容裝置
list、get、reconcile、rollup、dailyRollup、create、update、batchDelete .nutrition.readonly
.nutrition.writeonly

營養記錄

營養記錄代表使用者記錄的食物。建立營養記錄的方式有兩種，取決於食物類型：

  1. 辨識出的食物：將 food 欄位設為參照現有的食物資源。系統會根據參照的食物，自動填入 nutrients、energy、energyFromFat、totalCarbohydrate、totalFat 和 foodDisplayName 欄位。建議優先使用這個方法。

  2. 匿名食物：手動設定 foodDisplayName 欄位，並提供 nutrients、energy、energyFromFat、totalCarbohydrate 和 totalFat 的值。建立匿名食物的營養記錄後，就無法編輯。

建立匿名食物的營養記錄

如要建立營養記錄項目，請將 POST 要求傳送至 nutrition-log dataPoints 端點。

要求

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-16T18:00:00Z",
      "endTime": "2026-06-16T18:30:00Z"
    },
    "foodDisplayName": "Grilled Chicken Breast",
    "mealType": "DINNER",
    "energy": {
      "kcal": 165
    },
    "totalCarbohydrate": {
      "grams": 0
    },
    "totalFat": {
      "grams": 3.6
    },
    "nutrients": [
      {
        "nutrient": "PROTEIN",
        "quantity": {
          "grams": 31
        }
      },
      {
        "nutrient": "SODIUM",
        "quantity": {
          "grams": 0.074
        }
      }
    ],
    "serving": {
      "amount": 1.0
    }
  }
}

回應

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/user-id/dataTypes/nutrition-log/dataPoints/data-point-id",
    "dataSource": {
      "recordingMethod": "UNKNOWN",
      "application": {
        "googleWebClientId": "google-web-client-id"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "nutritionLog": {
      "interval": {
        "startTime": "2026-06-16T18:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-06-16T18:30:00Z",
        "endUtcOffset": "0s",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 6,
            "day": 16
          },
          "time": {
            "hours": 18
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 6,
            "day": 16
          },
          "time": {
            "hours": 18,
            "minutes": 30
          }
        }
      },
      "energy": {
        "kcal": 165
      },
      "totalCarbohydrate": {
        "grams": 0
      },
      "totalFat": {
        "grams": 3.6
      },
      "nutrients": [
        {
          "quantity": {
            "grams": 31
          },
          "nutrient": "PROTEIN"
        },
        {
          "quantity": {
            "grams": 0.074
          },
          "nutrient": "SODIUM"
        }
      ],
      "mealType": "DINNER",
      "serving": {
        "amount": 1
      },
      "foodDisplayName": "Grilled Chicken Breast"
    }
  }
}

建立營養記錄，並列出辨識出的食物

如要從食物資料庫記錄食物項目，請將 food 欄位設為參照 Food 資源。API 會自動填入營養成分欄位。

要求

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"
    },
    "food": "users/me/dataTypes/food/dataPoints/food-id",
    "mealType": "LUNCH",
    "serving": {
      "amount": 1.0,
      "foodMeasurementUnit": "users/me/dataTypes/food-measurement-unit/dataPoints/food-measurement-unit-id"
    }
  }
}

回應

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/user-id/dataTypes/nutrition-log/dataPoints/data-point-id",
    "dataSource": {
      "recordingMethod": "UNKNOWN",
      "application": {
        "googleWebClientId": "google-web-client-id"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "nutritionLog": {
      "interval": {
        "startTime": "2026-06-16T12:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-06-16T12:30:00Z",
        "endUtcOffset": "0s",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 6,
            "day": 16
          },
          "time": {
            "hours": 12
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 6,
            "day": 16
          },
          "time": {
            "hours": 12,
            "minutes": 30
          }
        }
      },
      "energy": {
        "kcal": 95
      },
      "energyFromFat": {
        "kcal": 3
      },
      "totalCarbohydrate": {
        "grams": 25
      },
      "totalFat": {
        "grams": 0.3
      },
      "nutrients": [
        {
          "quantity": {
            "grams": 4.4,
            "userProvidedUnit": "GRAM"
          },
          "nutrient": "DIETARY_FIBER"
        },
        {
          "quantity": {
            "grams": 19,
            "userProvidedUnit": "GRAM"
          },
          "nutrient": "SUGAR"
        },
        {
          "quantity": {
            "grams": 0.5,
            "userProvidedUnit": "GRAM"
          },
          "nutrient": "PROTEIN"
        }
      ],
      "mealType": "LUNCH",
      "serving": {
        "amount": 1,
        "foodMeasurementUnit": "users/me/dataTypes/food-measurement-unit/dataPoints/food-measurement-unit-id"
      },
      "food": "users/user-id/dataTypes/food/dataPoints/food-id",
      "foodDisplayName": "Apple"
    }
  }
}

刪除營養記錄

如要刪除一或多個營養記錄項目，請傳送 POST 要求至 batchDelete 方法，並附上要移除的項目資源名稱。

要求：

POST https://health.googleapis.com/v4/users/me/dataTypes/nutrition-log/dataPoints:batchDelete
Authorization: Bearer access-token
Content-Type: application/json

{
  "names": [
    "users/me/dataTypes/nutrition-log/dataPoints/data-point-id"
  ]
}

營養記錄欄位

如需完整的欄位和說明清單，請參閱 NutritionLog。

能量

代表能量測量值，以千卡 (kcal) 為單位。詳情請參閱 EnergyQuantity。

{
  "kcal": 165
}

重量

代表重量測量值，以公克為單位。詳情請參閱 WeightQuantity。

{
  "grams": 27.3
}

營養素數量

代表特定營養素及其測量數量。詳情請參閱 NutrientQuantity。

{
  "nutrient": "PROTEIN",
  "quantity": {
    "grams": 31
  }
}

營養素值

如需支援的營養素類型完整清單，請參閱 Nutrient。

供應

代表營養記錄項目的份量資訊。詳情請參閱 Serving。

{
  "amount": 1.5
}

餐點類型值

如需支援餐點類型的完整清單，請參閱 MealType。

食物

「食物」是唯讀資料類型，代表食物資料庫中的食物項目。使用 list 和 get 作業瀏覽可用的食物，並擷取其營養資訊。

列出食物

如要列出食物，請向 food dataPoints 端點傳送 GET 要求：

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

食物測量單位

食物測量單位是唯讀資料類型，代表食物份量的測量單位 (例如「杯」、「湯匙」或「塊」)。

列出可用的測量單位

如要列出可用的測量單位，請按照下列步驟操作：

GET https://health.googleapis.com/v4/users/me/dataTypes/food-measurement-unit/dataPoints
Authorization: Bearer access-token
Accept: application/json

飲水量記錄

飲水量記錄代表使用者記錄的液體攝取量。與食物不同，食物會參照食物資料庫，並測量營養素或能量攝取量，而水分項目則會追蹤特定時間間隔內消耗的液體量。

建立飲水量記錄

如要建立水分攝取記錄項目，請將 POST 要求傳送至 hydration-log dataPoints 端點。所有體積數量都會轉換為 API 格式的毫升。

要求

POST https://health.googleapis.com/v4/users/me/dataTypes/hydration-log/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "hydrationLog": {
    "interval": {
      "startTime": "2026-06-16T14:00:00Z",
      "endTime": "2026-06-16T14:00:01Z"
    },
    "amountConsumed": {
      "milliliters": 500,
      "userProvidedUnit": "FLUID_OUNCE_US"
    }
  }
}

回應

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/user-id/dataTypes/hydration-log/dataPoints/data-point-id",
    "dataSource": {
      "recordingMethod": "UNKNOWN",
      "application": {
        "googleWebClientId": "google-web-client-id"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "hydrationLog": {
      "interval": {
        "startTime": "2026-06-16T14:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-06-16T14:00:01Z",
        "endUtcOffset": "0s",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 6,
            "day": 16
          },
          "time": {
            "hours": 14
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 6,
            "day": 16
          },
          "time": {
            "hours": 14,
            "seconds": 1
          }
        }
      },
      "amountConsumed": {
        "milliliters": 500,
        "userProvidedUnit": "FLUID_OUNCE_US"
      }
    }
  }
}

更新飲水量記錄

如要更新水分攝取記錄項目，請傳送 PATCH 要求至 hydration-log dataPoints 端點，並附上資料點 ID。

要求

PATCH https://health.googleapis.com/v4/users/me/dataTypes/hydration-log/dataPoints/data-point-id
Authorization: Bearer access-token
Content-Type: application/json

{
  "hydrationLog": {
    "interval": {
      "startTime": "2026-06-16T10:00:00Z",
      "endTime": "2026-06-16T10:00:01Z"
    },
    "amountConsumed": {
      "milliliters": 500
    }
  }
}

回應

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/user-id/dataTypes/hydration-log/dataPoints/data-point-id",
    "dataSource": {
      "recordingMethod": "UNKNOWN",
      "application": {
        "googleWebClientId": "google-web-client-id"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "hydrationLog": {
      "interval": {
        "startTime": "2026-06-16T10:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-06-16T10:00:01Z",
        "endUtcOffset": "0s",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 6,
            "day": 16
          },
          "time": {
            "hours": 10
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 6,
            "day": 16
          },
          "time": {
            "hours": 10,
            "seconds": 1
          }
        }
      },
      "amountConsumed": {
        "milliliters": 500
      }
    }
  }
}

刪除飲水量記錄

如要刪除一或多個水分攝取記錄項目，請將 POST 要求傳送至 batchDelete 方法。

要求

POST https://health.googleapis.com/v4/users/me/dataTypes/hydration-log/dataPoints:batchDelete
Authorization: Bearer access-token
Content-Type: application/json

{
  "names": [
    "users/me/dataTypes/hydration-log/dataPoints/data-point-id"
  ]
}

回應

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.BatchDeleteDataPointsResponse",
    "dataPoints": [
      {
        "name": "users/user-id/dataTypes/hydration-log/dataPoints/data-point-id",
        "dataSource": {
          "recordingMethod": "UNKNOWN",
          "application": {
            "googleWebClientId": "google-web-client-id"
          },
          "platform": "GOOGLE_WEB_API"
        },
        "hydrationLog": {
          "interval": {
            "startTime": "2026-06-16T14:00:00Z",
            "startUtcOffset": "0s",
            "endTime": "2026-06-16T14:00:01Z",
            "endUtcOffset": "0s",
            "civilStartTime": {
              "date": {
                "year": 2026,
                "month": 6,
                "day": 16
              },
              "time": {
                "hours": 14
              }
            },
            "civilEndTime": {
              "date": {
                "year": 2026,
                "month": 6,
                "day": 16
              },
              "time": {
                "hours": 14,
                "seconds": 1
              }
            }
          },
          "amountConsumed": {
            "milliliters": 500,
            "userProvidedUnit": "FLUID_OUNCE_US"
          }
        }
      }
    ]
  }
}

飲水量記錄欄位

如需完整的欄位和說明清單，請參閱 HydrationLog。

磁碟區數量

代表體積測量值，以毫升為單位。詳情請參閱 VolumeQuantity。

{
  "milliliters": 250,
  "userProvidedUnit": "MILLILITER"
}

體積單位值

如需支援的完整體積單位清單，請參閱 VolumeUnit。常見的值包括 MILLILITER、LITER、CUP_US 和 FLUID_OUNCE_US。

規範

  • 請盡可能使用辨識出的食物。API 會自動填入營養成分欄位，減少錯誤並確保與食品資料庫一致。
  • 建立後，無法更新從匿名食物建立的營養記錄。 如要修正匿名飲食記錄，請刪除並重新建立。
  • 與匿名食物營養記錄不同，水分攝取記錄項目完全可變動，建立後可使用 PATCH 要求更新。
  • nutrients 陣列中的所有營養素數量都以公克為測量單位。
  • energy 和 energyFromFat 欄位使用千卡 (kcal) 做為測量單位。
  • API 會將所有水分攝取量轉換為毫升，並儲存起來。VolumeQuantity 中的選用 userProvidedUnit 欄位僅用於用戶端面向使用者的顯示。
  • 直接向個別 hydration-log 資料點發出 HTTP DELETE 要求會傳回 404 Not Found。請使用 batchDelete 方法移除這些資源項目。
  • 水分攝取記錄會使用短時間間隔，其中 startTime 和 endTime 代表攝取液體的時間。
上一頁
健身
下一頁
操作步驟