API の仕様

API 仕様のセクションでは、認可スコープ、データ型定義、エンドポイント構造など、プラットフォームとの統合に不可欠な技術コンポーネントの詳細な概要を説明します。この API は、従来の Fitbit Web API の戦略的な進化を表しています。最新のインフラストラクチャで再構築され、より安定した一貫性のあるデベロッパー エクスペリエンスを実現しています。

スコープ

Google Health API スコープを使用するように、認可リクエストを更新する必要があります。スコープは、アプリが読み取りオペレーションまたは書き込みオペレーションをサポートするかどうかを定義します。スコープの実装の手順に沿って、必要なスコープのみをリクエストし、データを送信する場合にのみ書き込みアクセスを構成し、部分的な同意を適切に処理します。

Google Health API スコープは、https://www.googleapis.com/auth/googlehealth.{scope} で始まる HTTP URL です。例: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly

スコープ マッピング

Fitbit Web API のスコープと Google Health API のスコープのマッピングは次のとおりです。

表: Fitbit Web API から Google Health API へのスコープ マッピング
Fitbit Web API のスコープ Google Health API のスコープ
アクティビティ .activity_and_fitness.readonly
.activity_and_fitness.writeonly
blood_glucose .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
cardio_fitness .activity_and_fitness.readonly
.activity_and_fitness.writeonly
心電図 .ecg.readonly
心拍数 .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
irregular_rhythm_notifications .irn.readonly
ロケーション .location.readonly
栄養 .nutrition.readonly
.nutrition.writeonly
oxygen_saturation .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
プロフィール .profile.readonly
.profile.writeonly
respiratory_rate .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
設定 .settings.readonly
.settings.writeonly
sleep .sleep.readonly
.sleep.writeonly
温度 .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
weight .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly

データ型

以下に、Google Health API のデータタイプと、それらが Fitbit Web API にどのようにマッピングされるかを示します。

表: Fitbit Web API から Google Health API へのデータ型マッピング
Fitbit Web API のデータタイプ Google Health API のデータタイプ
  dataType		 説明
アクティビティのカロリー アクティブな消費エネルギー
  active-energy-burned 		活動期間中の消費カロリーを表します。その期間の BMR も含まれます。Google Health API では、active-energy-burned データタイプ（基礎代謝率を除く、アクティビティのみの消費カロリーを追跡）に BMR を追加することで、これを再構成できます。
アクティブ ゾーン時間 アクティブ ゾーン時間
  active-zone-minutes
ユーザーのアクティビティ レベルの変更が含まれます アクティビティ レベル
  activity-level 		特定の期間におけるユーザーのアクティビティ レベル（座りがち、アクティブなど）をキャプチャします。
高度 Altitude
  altitude
アクティビティ caloriesBMR 基礎消費エネルギー
  basal-energy-burned 		特定の期間における基礎代謝率（BMR）による消費カロリー。
血糖値 血糖値
  blood-glucose
体脂肪 体脂肪
  body-fat
各心拍ゾーンの滞在時間: caloriesOut 心拍ゾーン内のカロリー
  calories-in-heart-rate-zone
温度（コア） 深部体温
  core-body-temperature
HRV の概要 1 日の心拍変動
  daily-heart-rate-variability
血中酸素ウェルネスの概要 1 日の血中酸素ウェルネス
  daily-oxygen-saturation 		検証済みの睡眠測定値から計算された血中酸素飽和度（SpO2）の統計情報の 1 日の概要。
安静時の心拍数 1 日の安静時の心拍数
  daily-resting-heart-rate
皮膚温 毎日の睡眠時の体温の変動
  daily-sleep-temperature-derivations
距離 距離
  distance
心電図 心電図
  electrocardiogram
記録されたアクティビティ エクササイズ
  exercise 		記録されたワークアウトまたはエクササイズ セッション（開始/終了時刻、アクティビティの種類、セッション指標など）。
階数 階数
  floors
食べ物 食べ物
  food
食品の測定単位 食品の測定単位
  food-measurement-unit
心拍数 心拍数
  heart-rate
HRV イントラデイ 心拍変動
  heart-rate-variability
不整脈の通知 不整脈の通知
  irregular-rhythm-notification
食事の記録 栄養摂取量の記録
  nutrition-log
血中酸素ウェルネス（イントラデイ） 血中酸素
  oxygen-saturation 		検証済みの 1 分単位の SpO2 測定値のみを返し、モーション アーティファクトやセンサーの信頼性の低さにより無効とフラグが付けられた測定値は除外します。Fitbit Web API では 50% のセンチネル値のみが除外されていたため、Google Health API では同じ期間のデータポイントが少なくなります。詳細については、酸素飽和度のフィルタリングをご覧ください。
ユーザーがランニングしたときの最大酸素摂取量の値 ランニング時の最大酸素摂取量
  run-vo2-max
アクティビティ時系列（座りがち（分）） 座りっぱなしの時間
  sedentary-period
睡眠 睡眠
  sleep
手順 手順
  steps
アクティビティ時系列のストローク数（水泳） スイミングの長さのデータ
  swim-lengths-data
アクティビティ caloriesOut 総カロリー
  total-calories 		一定期間にユーザーが消費した消費カロリーの合計数。基礎代謝率と活動消費エネルギーを含みます。
最大酸素摂取量の値 最大酸素摂取量
  vo2-max
重量 重量
  weight

計算

Google Health API のマッピングとルールは、Fitbit Web API とは異なります。

血中酸素のフィルタリング

1 分単位の血中酸素飽和度（oxygen-saturation）をクエリする場合、Google Health API は以前の Fitbit Web API よりも厳格なデータ有効性フィルタを適用します。

  • 以前の Fitbit Web API（v1 と v3）では、センチネル値が 50% の SpO2 サンプルのみが除外されていました。
  • Google Health API（v4）は、検証アルゴリズムによって無効とフラグが付けられたすべての SpO2 サンプルを除外します。腕の動きや手首への緩い装着により光学センサーの信号が信頼できなくなった場合、信頼度スコアが 50% 未満に低下した場合、無効な測定の直前および直後の 3 分間、または有効な測定が 4 分未満しか続かなかった場合、その 1 分間は無効とマークされます。

Google Health API は、50% のセンチネル値だけでなく、無効な測定値をすべて削除するため、同じ期間の oxygen-saturation データポイントは Fitbit Web API よりも少なくなります。また、1 分ごとのカバレッジにギャップが生じることが予想されます。返される分単位の測定値は、ユーザーの daily-oxygen-saturation 睡眠のまとめの計算に使用される検証済みのデータポイントと一致します。詳細については、分単位の SpO2 フィルタリングとデータの妥当性を参照してください。

アクティビティ レベル、MET、歩数のしきい値

Google Health API では、ユーザーの 1 分ごとのアクティビティ レベルは、代謝当量（MET）と歩数から算出されます。

アクティビティ レベル 心拍数デバイス 心拍数測定機能のないデバイス
座りがち 1.5 METs 以下 1.5 METs 以下
低強度のアクティビティ 1.5 METs 超、4.2 METs 以下 1.5 METs 超、3.5 METs 以下
適度な運動 4.2 METs 超、6.0 METs 未満
（非常にアクティブの条件を満たしている場合を除く）		 > 3.5 METs かつ < 6.0 METs
（非常にアクティブの条件を満たしている場合を除く）
非常にアクティブ 6.0 METs 以上、または 5.0 METs 以上かつ 1 分あたり 150 歩以上の歩行 6.0 METs 以上、または 5.0 METs 以上かつ 1 分あたり 150 歩以上の歩行

アクティブな時間（分）は、MODERATELY_ACTIVE と VERY_ACTIVE の合計時間です。ただし、高強度の活動時間は、少なくとも 10 分間連続して行われた場合にのみカウントされます。この間、低強度の活動時間は最大 2 分間まで許容されます。

座りがちな時間と睡眠

座りっぱなしの時間に睡眠時間は含まれません。毎日のロールアップでは、1 日の合計時間（1,440 分）から睡眠時間とアクティブな時間（低強度、中強度、高強度）を差し引いて、座りっぱなしの時間が計算されます。

Sedentary Minutes = 1440 - Sleep Minutes - Lightly Active Minutes - Moderately Active Minutes - Very Active Minutes

ボディマス指数（BMI）

Google Health API には BMI データ型が組み込まれていないため、アプリは身長と体重の記録を使用してクライアントサイドでボディマス指数を計算する必要があります。

  1. 体重データ型の weightGrams フィールドから、ユーザーの体重をグラム単位で取得します。これをキログラム（1,000 で割る）またはポンド（453.59237 で割る）に変換します。
  2. 身長データタイプの heightMillimeters フィールドから、ユーザーの身長をミリメートル単位で取得します。これをメートル（1,000 で割る）またはインチ（25.4 で割る）に変換します。
  3. 次のいずれかの式を使用して BMI 値を計算します。
    • 指標の数式: BMI = weight (kg) / [height (m)]^2
    • ヤードポンド法の計算式: BMI = (weight (lbs) / [height (in)]^2) * 703

BMI の値は、次のカテゴリに対応しています。

体重カテゴリ BMI の範囲
低体重 18.5 未満
健康的な体重 18.5 ～ 24.9
太り気味 25 ～ 29.9
肥満 30 以上

基礎代謝率（BMR）

基礎代謝率（BMR）は、安静時に基本的な身体機能に必要な最小カロリー数です。Google Health API は組み込みの BMR データ型を公開していないため、アプリはハリス ベネディクトの式を使用してクライアントサイドで BMR を計算する必要があります。詳しくは、Wikipedia の Harris–Benedict equation の記事をご覧ください。

この計算を行うには:

  1. 体重データ型の weightGrams フィールドからユーザーの体重をグラム単位で取得し、キログラムに変換します（1,000 で割ります）。ポンドをキログラムに変換するには、2.2 で割ります。
  2. 身長データ型の heightMillimeters フィールドからユーザーの身長をミリメートル単位で取得し、センチメートル単位に変換します（10 で割ります）。インチをセンチメートルに変換するには、2.54 を掛けます。
  3. Profile リソースの age フィールドからユーザーの年齢（年単位）を取得します。
  4. Google Health API ではこのフィールドが公開されないため、生物学的性別を個別に取得します（たとえば、ユーザーにプロンプトを表示するか、独自のデータベースで管理します）。
  5. ユーザーの生物学的性別に基づいて、次のいずれかの式を使用します。
    • 男性: BMR = 66 + (13.7 x weight_kg) + (5 x height_cm) - (6.8 x age_years)
    • 女性: BMR = 655 + (9.6 x weight_kg) + (1.8 x height_cm) - (4.7 x age_years)

1 日の総エネルギー消費量（TDEE）

1 日の総エネルギー消費量（TDEE）は、1 日に消費するカロリーの合計の推定値です。これには、BMR と身体活動の両方が含まれます。ユーザーの TDEE を推定するには、BMR 値にライフスタイルに対応するアクティビティ係数を掛けます。

アクティビティ レベル 説明 乗数
座りがち 運動をほとんどまたはまったくしない。 BMR x 1.2
活動量が少ない 週に 1 ～ 3 日のエクササイズ。 BMR x 1.375
活動量が中程度 1 週間に 3 ～ 5 日のエクササイズ。 BMR x 1.55
非常に活発 1 週間に 6 ～ 7 日のエクササイズ。 BMR x 1.725
非常にアクティブ 非常に激しい運動や肉体労働。 BMR x 1.9

エンドポイント

REST エンドポイントは、すべてのデータ型に一貫した構文を採用しています。

  • サービス エンドポイント: ベース HTTP URL が https://health.googleapis.com に変更されます。
  • エンドポイントの構文: Google Health API は、サポートされているほとんどのデータ型で使用できる、限られた数のエンドポイントをサポートしています。これにより、すべてのデータ型に一貫した構文が提供され、エンドポイントが使いやすくなります。
  • ユーザー ID: エンドポイント構文でユーザー ID または me を指定する必要があります。me を使用すると、ユーザー ID はアクセス トークンから推測されます。

例: Google Health API を使用して呼び出された GET Profile エンドポイントの例を次に示します。

GET https://health.googleapis.com/v4/users/me/profile

エンドポイント マッピング

利用可能なデータタイプと、それらがサポートする API メソッドの一覧については、Google Health API のデータタイプの表をご覧ください。

Fitbit Web API エンドポイント タイプ Google Health API
GET（ログ | 概要 | 日次概要）で、1 日分のデータをリクエストする場合 dailyRollup メソッド（windowSize = 1 日）
GET（イントラデイ）: 詳細なデータをリクエストする場合 list メソッド
日付または間隔による GET（時系列） 期間を含む rollUp メソッドまたは dailyRollUp メソッド
GET（ログリスト） list メソッド
CREATE と UPDATE のログ patch メソッド
DELETE ログ batchDelete メソッド
GET Profile users.getProfile はユーザーの特定の情報を返します。
users.getSettings はユーザーの単位とタイムゾーンを返します。
プロフィールの更新 users.updateProfile はユーザーの特定の情報を変更します
users.updateSettings はユーザーの単位とタイムゾーンを変更します
ユーザー ID を取得する users.getIdentity は、ユーザーの以前の Fitbit ユーザー ID と Google ユーザー ID を返します。
デバイスを取得する users.pairedDevices は、ペア設定したデバイスのリストを返します。
サブスクリプションを作成する projects.subscribers.subscriptions.create がサブスクリプションを手動で作成する
サブスクリプションを削除する projects.subscribers.subscriptions.delete サブスクリプションを削除する
サブスクリプション リストを取得する projects.subscribers.subscriptions.list: すべてのサブスクリプションを一覧表示します。