Google Health API は、exercise セッション データタイプを使用して、ユーザーのワークアウト セッションとエクササイズ履歴を追跡します。セッションは、アクティビティのメタデータ、一時停止イベントと再開イベント、ラップまたはスプリット、概要指標をバンドルするコンテナとして機能します。
アプリでワークアウトを読み取り、書き込み、構造化して、ユーザーに最適なエクスペリエンスを提供する方法を理解します。
サポートされるデータタイプ
この API は、ワークアウトとアクティビティ セッションをトラッキングするための次のデータタイプをサポートしています。
| データ型 | 利用可能な オペレーション |
スコープ |
|---|---|---|
|
エクササイズ
dataType:
exercisefilter parameter: exercise
レコードタイプ: セッション
対応デバイス
|
list、get、reconcile、create、update、batchDelete | .activity_and_fitness.readonly.activity_and_fitness.writeonly |
関連するテレメトリー データタイプ
ワークアウト セッションでは exercise データ型をコンテナとして使用しますが、ウェアラブル デバイスはセッション中に詳細な高頻度テレメトリーも記録します。Google Health API では、これらの詳細なイントラデイ テレメトリー データタイプは読み取り専用であり、独自の REST エンドポイントを介して直接作成または変更することはできません。REST API を介してワークアウト セッションを書き込む場合は、exercise データポイントの metricsSummary オブジェクト内でワークアウトの集計指標を渡します。
次の表は、exercise.metricsSummary 内のサマリー フィールドを、そのワークアウトの時間枠でクエリできる、対応する読み取り専用のイントラデイ テレメトリー データ型にマッピングしたものです。
概要フィールド（metricsSummary） |
イントラデイ テレメトリー データタイプの名前 | API テレメトリー データタイプ ID（読み取り専用） | フィルタ フィールド（?filter=） |
必要な読み取り OAuth スコープ |
|---|---|---|---|---|
caloriesKcal |
アクティブ消費カロリー | active-energy-burned |
active_energy_burned.interval.start_time |
activity_and_fitness.readonly |
distanceMillimeters |
距離 | distance |
distance.interval.start_time |
activity_and_fitness.readonly |
steps |
手順 | steps |
steps.interval.start_time |
activity_and_fitness.readonly |
averageHeartRateBeatsPerMinute |
心拍数 | heart-rate |
heart_rate.sample_time.physical_time |
health_metrics_and_measurements.readonly |
activeZoneMinutes |
アクティブ ゾーン時間 | active-zone-minutes |
active_zone_minutes.interval.start_time |
activity_and_fitness.readonly |
以降のセクションでは、REST 表現の例、GPS ルートの処理、統合ガイドラインなど、exercise データ型の技術的な詳細について説明します。
ワークアウト セッション
毎日のアクティビティやワークアウトを exercise セッションのデータポイントとして書き込みます。各データポイントは、セッション全体を記述し、イベント間隔（一時停止や再開アクションなど）を詳細に示し、要約指標（全体的な距離、歩数、平均心拍数など）を提供します。
セッション属性
エクササイズのデータポイントを構成する際は、次のコア コンポーネントを確認してください。
- セッション時間（
interval）: ワークアウト セッション全体の開始時間と終了時間、およびその時点で有効なタイムゾーン オフセット。 - アクティビティ タイプ（
exerciseType）: 実行されたアクティビティのカテゴリ（RUNNING、WALKING、BIKING、AEROBIC_WORKOUTなど）。身体トレーニングの正確なタイプを指定します。 - 表示名（
displayName）: ワークアウト セッションのユーザー フレンドリーな名前。REST API を介して作成されると、サーバーはexerciseTypeのローカライズされた表示名（RUNNINGの"Run"など）を入力します。 - アクティブな時間（
activeDuration）: ワークアウトの実際のアクティブな時間。一時停止の間隔は除きます。標準の形式ではDuration形式（例:"1800s"）が使用されます。サーバーでは、activeDurationはセッションintervalからexerciseEventsのPAUSE/RESUMEまたはAUTO_PAUSE/AUTO_RESUMEの間隔を引いて計算されます。
サマリー指標
metricsSummary ネストされたオブジェクトには、エクササイズ セッションの全期間にわたって計算された合計指標と平均指標が含まれます。
caloriesKcal: ワークアウト中の総アクティブ消費カロリー。キロカロリー（kcal）単位で測定されます。distanceMillimeters: 走行した合計距離。単位間で高い精度を維持するため、ミリメートル単位で測定されます。steps: エクササイズ中の合計歩数。averageHeartRateBeatsPerMinute: セッションのアクティブな時間（分）におけるユーザーの平均心拍数。activeZoneMinutes: ワークアウト中に獲得したアクティブ ゾーン時間の累計。averageSpeedMillimetersPerSecond: 平均移動速度（ミリメートル/秒）。averagePaceSecondsPerMeter: セッションのアクティブな時間（分）の平均ペース（秒/メートル）。elevationGainMillimeters: セッション中の合計獲得標高。
ラップとスプリット
サポートされているデバイスから同期されたラップ（トラックランやプールスイミングなど）を含むワークアウトの場合、splitSummaries はセッションをラップまたはスプリットごとに分割します。
各スプリットには次のものが含まれます。
- 特定の
startTimeとendTime。 - 実際のラップタイムを表す
activeDuration。 - そのセグメントのみを対象とする
metricsSummary。 - スプリットの境界を定義する
splitType（DISTANCE、DURATION、MANUALなど）。
エクササイズ イベント
アクティブな時間を正確に計算するには、exerciseEvents を使用して状態遷移（手動または自動の一時停止イベントなど）を追跡します。
各イベントには、タイムスタンプ（eventTime）とタイプが含まれます。
START/STOP: ユーザーが明示的に記録を開始または停止したときの境界タイムスタンプを示します。PAUSE/RESUME: セッションが手動で一時停止または再開された日時を示します。AUTO_PAUSE/AUTO_RESUME: センサーによる自動一時停止 / 再開を示します。
ワークアウト セッションを書き込む
ワークアウト セッションを作成、更新、インポートするには、exercise データ型コレクションにデータポイントを書き込みます。create dataPoints エンドポイントを使用します。
REST 表現の例
次の例は、POST メソッドを使用してワークアウト セッションを書き込む方法を示しています。
リクエスト
POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer access-token
Content-Type: application/json
{
"dataSource": {
"recordingMethod": "ACTIVELY_MEASURED",
"platform": "GOOGLE_WEB_API"
},
"exercise": {
"interval": {
"startTime": "2026-04-20T08:00:00Z",
"startUtcOffset": "0s",
"endTime": "2026-04-20T08:35:00Z",
"endUtcOffset": "0s"
},
"exerciseType": "RUNNING",
"activeDuration": "1800s",
"metricsSummary": {
"caloriesKcal": 380.0,
"distanceMillimeters": 5000000.0,
"steps": "6200",
"averageHeartRateBeatsPerMinute": "148",
"averagePaceSecondsPerMeter": 0.36
},
"exerciseEvents": [
{
"eventTime": "2026-04-20T08:15:00Z",
"eventUtcOffset": "0s",
"exerciseEventType": "PAUSE"
},
{
"eventTime": "2026-04-20T08:20:00Z",
"eventUtcOffset": "0s",
"exerciseEventType": "RESUME"
}
]
}
}レスポンス
{
"done": true,
"response": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
"name": "users/999298779973222220/dataTypes/exercise/dataPoints/3054085373369111216",
"dataSource": {
"recordingMethod": "ACTIVELY_MEASURED",
"application": {
"googleWebClientId": "438076457939-example.apps.googleusercontent.com"
},
"platform": "GOOGLE_WEB_API"
},
"exercise": {
"interval": {
"startTime": "2026-04-20T08:00:00Z",
"startUtcOffset": "0s",
"endTime": "2026-04-20T08:35:00Z",
"endUtcOffset": "0s"
},
"exerciseType": "RUNNING",
"metricsSummary": {
"caloriesKcal": 380,
"distanceMillimeters": 5000000,
"steps": "6200",
"averagePaceSecondsPerMeter": 0.36,
"averageHeartRateBeatsPerMinute": "148"
},
"exerciseMetadata": {},
"displayName": "Run",
"activeDuration": "1800s",
"exerciseEvents": [
{
"eventTime": "2026-04-20T08:15:00Z",
"eventUtcOffset": "0s",
"exerciseEventType": "PAUSE"
},
{
"eventTime": "2026-04-20T08:20:00Z",
"eventUtcOffset": "0s",
"exerciseEventType": "RESUME"
}
],
"updateTime": "2026-04-20T08:35:10.123456Z",
"createTime": "2026-04-20T08:35:10.123456Z"
}
}
}GPS ルートと位置情報の追跡
この API は、基本的なセッションの概要を exercise データポイント内に直接保存しますが、詳細な位置情報の履歴と GPS ルート座標は別のストリームとして処理します。
屋外セッションの詳細なルートデータをダウンロードするには、exportExerciseTcx カスタム メソッドを呼び出します。このエンドポイントは、業界標準の Training Center XML（TCX）形式でルートを返します。
GPS ルートをエクスポートする
リクエスト
GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints/exercise-data-point-id:exportExerciseTcx?alt=media Authorization: Bearer access-token
レスポンス
Content-Type: application/tcx+xml と、ファイルを保存するようブラウザに指示するヘッダーを含む HTTP ペイロード。
<?xml version="1.0" encoding="UTF-8"?>
<TrainingCenterDatabase xmlns="http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2">
<Activities>
<Activity Sport="Running">
<Id>2026-04-20T08:00:00Z</Id>
<Lap StartTime="2026-04-20T08:00:00Z">
<TotalTimeSeconds>1800</TotalTimeSeconds>
<DistanceMeters>5000</DistanceMeters>
<Calories>380</Calories>
<Intensity>Active</Intensity>
<TriggerMethod>Manual</TriggerMethod>
<Track>
<Trackpoint>
<Time>2026-04-20T08:00:00Z</Time>
<Position>
<LatitudeDegrees>37.7749</LatitudeDegrees>
<LongitudeDegrees>-122.4194</LongitudeDegrees>
</Position>
<AltitudeMeters>15.0</AltitudeMeters>
<DistanceMeters>0.0</DistanceMeters>
</Trackpoint>
</Track>
</Lap>
</Activity>
</Activities>
</TrainingCenterDatabase>必要なスコープとロケーション
GPS ルートと位置情報のトラッキング機能を使用するには、アプリで次の OAuth スコープをリクエストする必要があります。
- 読み取り:
https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly - 書き込み:
https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly - 読み取り:
https://www.googleapis.com/auth/googlehealth.location.readonly
ガイドライン
ワークアウト トラッキングをアプリに統合する際は、以下の設計と実装のガイドラインに沿ってください。
アクティブな時間と合計時間
速度またはペースの指標を計算するには、startTime と endTime の差ではなく、常に activeDuration を使用します。これにより、一時停止した間隔が指標に影響することを防ぎます。
たとえば、ユーザーが 8:00 にワークアウトを開始し、8:35 に終了した場合、ワークアウトの合計経過時間は 2,100 秒になります。ユーザーがワークアウトを 5 分間（300 秒）一時停止し、exerciseEvents に PAUSE イベントと RESUME イベントを含めた場合、アクティブな時間は "1800s"（2,100 - 300）です。API は、アクティブな時間を使用して平均を計算し、合計距離を 2,100 ではなく 1,800 秒で割ります。
速度とペースの計算
Google Health API は、標準的な数式を使用して速度とペースを計算します。
- 速度 =
distance / time(hour) - ペース =
time(seconds) / distance
リクエストで指定された Accept-Language ヘッダーによって、距離の単位が決まります。
位置情報を早めにリクエストする
アプリでワークアウトのルートをマッピングする場合は、アクティビティとフィットネスのスコープに加えて、位置情報の利用許可と Google Health の location スコープをリクエストします。GPS エクササイズを確認する際に、アプリが位置情報のスコープを必要とする理由をユーザーに説明します。
アプリが位置情報のスコープ（https://www.googleapis.com/auth/googlehealth.location.readonly）をリクエストすると、Google OAuth によってユーザーに同意プロンプトが表示されます。この権限は、ルート オーバーレイのレンダリングと GPS トラック ファイル（TCX）のエクスポートに必要であることをユーザーに説明します。ユーザーがアクティビティ スコープを付与し、位置情報の利用許可を拒否した場合、exportExerciseTcx は認可エラーを返します。ただし、metricsSummary のセッション集計にはアクセスできます。
ウェブフックを使用したリアルタイム同期
exercise データタイプに登録して、新しいワークアウト データが利用可能になったときに、Webhook を使用してバックエンドに通知します。これにより、ワークアウト後のエクスペリエンスをリアルタイムでトリガーできます。
サーバーが Webhook 通知を受信すると、更新されたワークアウトの healthUserId と常用時間間隔（civilIso8601TimeInterval）が含まれます。サーバーは、204 No Content を使用して通知をすぐに確認し、ペイロードを非同期で処理して、exercise.interval.civil_start_time フィルタを使用して調整済みの exercise エンドポイントをクエリする必要があります（exercise は civil_start_time によるフィルタリングのみをサポートしています）。
GET https://health.googleapis.com/v4/users/healthUserId/dataTypes/exercise/dataPoints:reconcile?filter=exercise.interval.civil_start_time >= "2026-04-20T08:00:00" AND exercise.interval.civil_start_time < "2026-04-20T10:00:00"
サブスクリプションの設定方法については、Webhook サブスクリプションをご覧ください。
一貫性のある指標を維持する
完全なワークアウト エクスペリエンスを提供するには、exercise セッションを書き込むときに概要指標を含め、詳細グラフをレンダリングするときに期間フィルタを使用して読み取り専用のテレメトリー エンドポイントをクエリします。
ワークアウトの概要指標を書き込む（書き込みパス）
完了したワークアウトを Google Health API にインポートまたは書き込む場合は、exercise データポイントの metricsSummary オブジェクト内に、ワークアウトの集計テレメトリー指標（steps、caloriesKcal、distanceMillimeters、averageHeartRateBeatsPerMinute、averagePaceSecondsPerMeter）を含めます。
POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
グラフの詳細データをクエリする（読み取りパス）
特定のセッションのワークアウト ダッシュボードまたはグラフを作成するには、そのワークアウトの時間枠の調整済みテレメトリー エンドポイントをクエリします。
civil_start_timeフィルタを使用してexerciseエンドポイントからワークアウト セッションを取得し、そのintervalとmetricsSummaryを取得します。GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints:reconcile?filter=exercise.interval.civil_start_time >= "2026-04-20T00:00:00" AND exercise.interval.civil_start_time < "2026-04-21T00:00:00"
セッションの
interval.startTimeとinterval.endTimeを使用して、その物理的な時間枠のテレメトリー エンドポイントをクエリします。exerciseMetadata.hasGpsがtrueの場合は、exportExerciseTcxを呼び出してルート座標をダウンロードします。