Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Google Health API로 운동 환경 개발

Google Health API는 exercise 세션 데이터 유형을 사용하여 사용자 운동 세션 및 운동 기록을 추적합니다. 세션은 활동 메타데이터, 일시중지 및 재개 이벤트, 랩 또는 스플릿, 요약 측정항목을 번들로 묶는 컨테이너 역할을 합니다.

애플리케이션에서 운동을 읽고 쓰고 구조화하여 사용자에게 최고의 환경을 제공하는 방법을 알아보세요.

지원되는 데이터 유형

API는 운동 및 활동 세션을 추적하기 위해 다음 데이터 유형을 지원합니다.

*표: Google Health API 운동 데이터 유형*
데이터 유형 `dataType` `filter` 매개변수	기록 유형	사용 가능한 작업	범위	웹훅 지원	True zeros 지원
운동 `exercise` `exercise`	세션	list, get, reconcile, create, update, batchDelete	activity_and_fitness

요약 필드 (`metricsSummary`)	일중 텔레메트리 데이터 유형 이름	API 텔레메트리 데이터 유형 ID
`caloriesKcal`	활동 에너지 소모량	`active-energy-burned`
`distanceMillimeters`	거리	`distance`
`steps`	단계	`steps`
`averageHeartRateBeatsPerMinute`	심박수	`heart-rate`
`activeZoneMinutes`	액티브존 미닛	`active-zone-minutes`

운동 세션

일일 활동 또는 운동을 exercise 세션 데이터 포인트로 작성합니다. 각 데이터 포인트는 전체 세션, 세부정보 이벤트 간격 (예: 일시중지 및 재개 작업)을 설명하고 요약 측정항목 (예: 전체 거리, 걸음 수, 평균 심박수)을 제공합니다.

세션 속성

운동 데이터 포인트를 구조화할 때는 다음 핵심 구성요소를 확인하세요.

세션 시간 (interval): 전체 운동 세션의 시작 시간과 종료 시간, 그리고 해당 시점에 활성 상태인 시간대 오프셋입니다.
활동 유형 (exerciseType): 실행된 활동의 카테고리입니다(예: RUNNING, WALKING, BIKING 또는 AEROBIC_WORKOUT). 정확한 유형의 신체 훈련을 지정합니다.
표시 이름 (displayName): 운동 세션의 사용자 친화적인 이름입니다 (예: '오후 트레일 러닝').
활성 시간 (activeDuration): 일시중지된 간격을 제외한 운동의 실제 활성 시간입니다. 표준 형식은 Duration 형식을 사용합니다 (예: "1800s").

요약 측정항목

metricsSummary 중첩 객체에는 운동 세션의 전체 기간에 걸쳐 계산된 총 측정항목과 평균 측정항목이 포함됩니다.

caloriesKcal: 운동 중에 소모된 총 활동 칼로리이며 킬로칼로리 (kcal)로 측정됩니다.
distanceMillimeters: 이동한 총 거리이며 단위 간 높은 정밀도를 유지하기 위해 밀리미터로 측정됩니다.
steps: 운동 중에 걸은 총 걸음 수입니다.
averageHeartRateBeatsPerMinute: 세션의 활동 시간 동안 사용자의 평균 심박수입니다.
activeZoneMinutes: 운동 중에 획득한 누적 액티브존 미닛입니다.
averageSpeedMillimetersPerSecond: 초당 평균 이동 속도(밀리미터)입니다.
averagePaceSecondsPerMeter: 세션의 활동 시간 동안의 평균 페이스이며 미터당 초로 측정됩니다.
elevationGainMillimeters: 세션 중 총 상승 고도입니다.

랩 및 스플릿

트랙 러닝 또는 수영장 수영과 같이 랩이 포함된 운동의 경우 splitSummaries를 사용합니다.

각 스플릿에는 다음이 포함됩니다.

특정 startTime 및 endTime.
실제 랩 시간을 나타내는 activeDuration.
해당 세그먼트로만 범위가 지정된 metricsSummary.
스플릿 경계 (예: DISTANCE, DURATION 또는 MANUAL)를 정의하는 splitType.

운동 이벤트

활성 시간을 정확하게 계산하려면 exerciseEvents를 사용하여 상태 전환 (예: 수동 또는 자동 일시중지 이벤트)을 추적합니다.

각 이벤트에는 타임스탬프 (eventTime)와 유형이 포함됩니다.

START / STOP: 사용자가 명시적으로 기록을 시작하거나 중지한 시점의 경계 타임스탬프를 나타냅니다.
PAUSE / RESUME: 세션이 수동으로 일시중지되거나 재개된 시점을 나타냅니다.
AUTO_PAUSE / AUTO_RESUME: 센서 기반 자동 일시중지/재개를 나타냅니다.

운동 세션 작성

운동 세션을 만들거나 업데이트하거나 가져오려면 exercise 데이터 유형 컬렉션에 데이터 포인트를 작성합니다. create 데이터 포인트 엔드포인트를 사용합니다.

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"
  },
  "exercise": {
    "interval": {
      "startTime": "2026-04-20T08:00:00Z",
      "startUtcOffset": "0s",
      "endTime": "2026-04-20T08:35:00Z",
      "endUtcOffset": "0s"
    },
    "exerciseType": "RUNNING",
    "displayName": "Morning Trail Run",
    "activeDuration": "1800s",
    "metricsSummary": {
      "caloriesKcal": 380.0,
      "distanceMillimeters": 5000000.0,
      "steps": "6200",
      "averageSpeedMillimetersPerSecond": 2777.78,
      "averagePaceSecondsPerMeter": 360.0,
      "averageHeartRateBeatsPerMinute": "148",
      "activeZoneMinutes": "30"
    },
    "exerciseMetadata": {
      "hasGps": true
    },
    "exerciseEvents": [
      {
        "eventTime": "2026-04-20T08:15:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "PAUSE"
      },
      {
        "eventTime": "2026-04-20T08:20:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "RESUME"
      }
    ],
    "splitSummaries": [
      {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:15:00Z",
        "endUtcOffset": "0s",
        "splitType": "DISTANCE",
        "metricsSummary": {
          "distanceMillimeters": 2500000.0,
          "caloriesKcal": 190.0
        }
      }
    ]
  }
}

응답

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
    "name": "users/me/dataTypes/exercise/dataPoints/morning-trail-run-123456",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "application": {
        "packageName": "com.example.workoutapp"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "exercise": {
      "interval": {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:35:00Z",
        "endUtcOffset": "0s"
      },
      "exerciseType": "RUNNING",
      "displayName": "Morning Trail Run",
      "activeDuration": "1800s",
      "metricsSummary": {
        "caloriesKcal": 380.0,
        "distanceMillimeters": 5000000.0,
        "steps": "6200",
        "averageSpeedMillimetersPerSecond": 2777.78,
        "averagePaceSecondsPerMeter": 360.0,
        "averageHeartRateBeatsPerMinute": "148",
        "activeZoneMinutes": "30"
      },
      "exerciseMetadata": {
        "hasGps": true
      },
      "exerciseEvents": [
        {
          "eventTime": "2026-04-20T08:15:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "PAUSE"
        },
        {
          "eventTime": "2026-04-20T08:20:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "RESUME"
        }
      ],
      "splitSummaries": [
        {
          "startTime": "2026-04-20T08:00:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-04-20T08:15:00Z",
          "endUtcOffset": "0s",
          "activeDuration": "900s",
          "splitType": "DISTANCE",
          "metricsSummary": {
            "distanceMillimeters": 2500000.0,
            "caloriesKcal": 190.0
          }
        }
      ]
    }
  }
}

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

인증 헤더에 필수 범위가 누락된 경우 Google Health API는 인증 오류를 반환합니다.

가이드라인

운동 추적을 앱에 통합할 때는 다음 설계 및 구현 가이드라인을 따르세요.

활성 시간과 총 시간

속도 또는 페이스 측정항목을 계산하려면 항상 startTime과 endTime의 차이 대신 activeDuration을 사용하세요. 이렇게 하면 일시중지된 간격으로 인해 측정항목이 왜곡되지 않습니다.

예를 들어 사용자가 08:00에 운동을 시작하고 08:35에 운동을 완료하면 운동의 총 경과 시간은 2,100초입니다. 사용자가 5분 (300초) 동안 운동을 일시중지한 경우 activeDuration을 "1800s" (2,100 - 300)로 설정합니다. API는 활성 시간을 사용하여 평균을 계산하며 총 거리를 2,100초가 아닌 1,800초로 나눕니다.

위치 요청 미리

앱이 운동 경로를 매핑하는 경우 활동 및 피트니스 범위 외에도 위치 권한과 Google Health location 범위를 요청합니다. GPS 운동을 검토할 때 앱에 위치 범위가 필요한 이유를 사용자에게 설명합니다.

앱이 위치 범위(https://www.googleapis.com/auth/googlehealth.location.readonly)를 요청하면 Google OAuth에서 사용자에게 동의 프롬프트를 표시합니다. 경로 오버레이를 렌더링하고 GPS 트랙 파일(TCX)을 내보내는 데 이 권한이 필요하다고 사용자에게 설명합니다. 사용자가 활동 범위를 부여하지만 위치 정보 액세스 권한을 거부하는 경우 exportExerciseTcx는 인증 오류를 반환하지만 metricsSummary에서 세션 집계에 계속 액세스할 수 있습니다.

웹훅을 사용한 실시간 동기화

새 운동 데이터를 사용할 수 있게 되면 웹훅을 사용하여 백엔드에 알리도록 exercise 데이터 유형을 구독합니다. 이렇게 하면 운동 후 환경을 실시간으로 트리거할 수 있습니다.

서버가 웹훅 알림을 수신하면 healthUserId와 운동의 특정 실제 시간 간격이 포함됩니다. 서버는 알림을 비동기적으로 처리한 후 새 exercise 데이터 포인트를 /users/me/dataTypes/exercise/dataPoints 엔드포인트에서 요청해야 합니다. 구독을 설정하는 방법에 관한 자세한 내용은 웹훅 구독을 참고하세요.

일관된 측정항목 유지

완전한 운동 경험을 제공하려면 앱이 전체 exercise 세션과 함께 고빈도 텔레메트리 데이터 포인트를 동기화해야 합니다. 이렇게 하면 사용자의 일일 총계, 과거 추세, 세부정보 차트가 완전히 정렬됩니다.

텔레메트리 및 세션 동기화 (쓰기 경로)

완료된 운동을 Google Health API로 가져오거나 작성할 때는 다단계 쓰기 패턴을 구현합니다.

세션 작성: POST /users/me/dataTypes/exercise/dataPoints에 데이터 포인트를 게시하여 요약 이벤트를 제출합니다.
시계열 간격 작성: 운동 중에 로깅된 세분화된 데이터 포인트 (예: 분당 걸음 수 또는 칼로리 소모 간격)를 각각의 컬렉션에 동시에 작성합니다.
- POST /users/me/dataTypes/steps/dataPoints
- POST /users/me/dataTypes/active-energy-burned/dataPoints
- POST /users/me/dataTypes/heart-rate/dataPoints

차트의 세부 데이터 쿼리 (읽기 경로)

특정 운동 세션의 과거 운동 대시보드 또는 실적 그래프를 렌더링할 때는 세션의 시간 창을 사용하여 세분화된 텔레메트리를 쿼리합니다.

세션 요약 쿼리: /users/me/dataTypes/exercise/dataPoints를 호출하여 전체 운동 세부정보와 최종 metricsSummary를 가져옵니다.
차트 측정항목 가져오기: 운동의 interval.startTime 및 interval.endTime을 검사합니다. 해당 특정 시간 창에 대해 텔레메트리 컬렉션에 보조 GET 호출을 실행합니다.
- GET /users/me/dataTypes/heart-rate/dataPoints?startTime=2026-04-20T08:00:00Z&endTime=2026-04-20T08:35:00Z
GPS 경로 가져오기: 세션의 메타데이터에 GPS 데이터가 있음이 표시되면 (exerciseMetadata.hasGps가 true), exportExerciseTcx 도우미 메서드를 호출하여 경로 좌표를 다운로드합니다.

칼로리 및 에너지