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
무게 .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에서는 BMR을 active-energy-burned 데이터 유형 (기초 대사량을 제외한 활동 전용 칼로리 소모량을 추적함)에 추가하여 이를 재구성할 수 있습니다.
액티브존 미닛 액티브존 미닛
  active-zone-minutes
사용자의 활동 수준 변경사항을 포함합니다. 활동 수준
  activity-level 		특정 기간 동안 사용자의 활동 수준 (예: 앉아 있는 상태 또는 활동적인 상태)을 캡처합니다.
고도 고도
  altitude
활동 caloriesBMR개 기초 에너지 소모량
  basal-energy-burned 		특정 기간 동안 기초 대사율 (BMR)로 인해 소모된 칼로리입니다.
혈당 혈당
  blood-glucose
체지방 체지방
  body-fat
각 심박수 구간에서 caloriesOut 소요 심박수 구간별 칼로리 소모량
  calories-in-heart-rate-zone
체온 (심부) 심부 체온
  core-body-temperature
HRV 요약 일일 심박 변이도
  daily-heart-rate-variability
SpO2 요약 일일 산소 포화도
  daily-oxygen-saturation 		검증된 수면 측정값으로 계산된 혈중 산소 포화도 (SpO2) 통계의 일일 요약입니다.
안정 시 심박수 일일 안정 시 심박수
  daily-resting-heart-rate
피부 온도 일일 수면 온도 도출
  daily-sleep-temperature-derivations
거리 거리
  distance
심전도 (ECG) 심전도 (ECG)
  electrocardiogram
기록된 활동 운동
  exercise 		기록된 운동 또는 운동 세션으로, 시작/종료 시간, 활동 유형, 세션 측정항목이 포함됩니다.
층수 층수
  floors
음식 음식
  food
음식 측정 단위 음식 측정 단위
  food-measurement-unit
심박수 심박수
  heart-rate
HRV 장중 심박 변이도
  heart-rate-variability
불규칙한 심장 리듬 알림 (IRN) 불규칙한 심장 리듬 알림
  irregular-rhythm-notification
음식 기록 영양 기록
  nutrition-log
장중 SpO2 산소 포화도
  oxygen-saturation 		검증된 분 단위 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와 다릅니다.

산소 포화도 필터링

분 단위 혈중 산소 포화도 (oxygen-saturation)를 쿼리할 때 Google Health API는 기존 Fitbit Web API보다 더 엄격한 데이터 유효성 필터링을 적용합니다.

  • 기존 Fitbit Web API (v1 및 v3)는 센티널 값이 50%인 SpO2 샘플만 제외했습니다.
  • Google Health API (v4)는 검증 알고리즘에 의해 잘못된 것으로 신고된 모든 SpO2 샘플을 제외합니다. 팔 움직임이나 느슨한 손목 착용으로 인해 광학 센서 신호가 불안정해지거나, 신뢰도 점수가 50% 미만으로 떨어지거나, 잘못된 측정 전후 3분 동안 또는 유효한 구간이 연속 4분 미만으로 지속되는 경우 해당 시간은 잘못된 것으로 표시됩니다.

Google Health API는 50% 센티널 값뿐만 아니라 모든 잘못된 측정값을 삭제하므로 동일한 기간에 Fitbit Web API보다 더 적은 oxygen-saturation 데이터 포인트를 반환하며 분 단위 범위에 공백이 발생할 수 있습니다. 반환된 분 단위 측정값은 사용자의 daily-oxygen-saturation 수면 요약을 계산하는 데 사용되는 검증된 데이터 포인트와 일치합니다. 자세한 내용은 분 단위 SpO2 필터링 및 데이터 유효성을 참고하세요.

활동 수준, MET, 걸음 수 기준점

Google Health API에서 사용자의 분 단위 활동 수준은 신진대사해당치 (MET)와 걸음 수에서 파생됩니다.

활동 수준 심박수 기기 심박수 기능이 없는 기기
비활동적 1.5MET 이하 1.5MET 이하
가벼운 활동 1.5MET 초과 및 4.2MET 이하 1.5MET 초과 및 3.5MET 이하
보통 4.2MET 초과 및 6.0MET 미만
(매우 활동적 조건이 충족되지 않는 경우)		 3.5MET 초과 및 6.0MET 미만
(매우 활동적 조건이 충족되지 않는 경우)
매우 활발함 6.0MET 이상 또는 5.0MET 이상(분당 150걸음 이상) 6.0MET 이상 또는 5.0MET 이상(분당 150걸음 이상)

활동적 시간은 MODERATELY_ACTIVE 및 VERY_ACTIVE 시간의 합으로 구성됩니다. 하지만 고강도 활동 시간은 최소 10분 동안 연속으로 지속되는 경우에만 인정되며, 활동 강도가 낮은 시간은 최대 2분까지 허용됩니다.

비활동 시간(분) 및 수면

비활동 시간(분)에는 수면 시간이 포함되지 않습니다. 일일 롤업에서 비활동 시간은 하루 총 시간(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 데이터 유형을 노출하지 않으므로 애플리케이션은 해리스-베네딕트 공식을 사용하여 클라이언트 측에서 이를 계산해야 합니다. 자세한 내용은 Wikipedia의 해리스-베네딕트 방정식 도움말을 참고하세요.

이 계산을 수행하려면 다음 단계를 따르세요.

  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)

일일 총 에너지 소비량 (TDEE)

일일 총 에너지 소비량 (TDEE)은 하루에 소모하는 총 칼로리의 추정치로, BMR과 신체 활동을 모두 고려합니다. 사용자의 TDEE를 추정하려면 BMR 값에 라이프스타일에 해당하는 활동 계수를 곱합니다.

활동 수준 설명 배율
비활동적 운동을 거의 또는 전혀 하지 않음 BMR x 1.2
낮은 활동 수준 일주일에 1~3일 운동 BMR x 1.375
중간 활동 수준 일주일에 3~5일 운동 BMR x 1.55
매우 활발함 일주일에 6~7일 운동 BMR x 1.725
매우 높은 활동 수준 매우 힘든 운동 또는 육체 노동 BMR x 1.9

엔드포인트

REST 엔드포인트는 모든 데이터 유형에 일관된 문법을 채택합니다.

  • 서비스 엔드포인트: 기본 HTTP URL이 https://health.googleapis.com으로 변경됩니다.
  • 엔드포인트 문법: Google Health API는 지원되는 대부분의 데이터 유형에서 사용할 수 있는 제한된 수의 엔드포인트를 지원합니다. 이렇게 하면 모든 데이터 유형에 일관된 문법이 제공되고 엔드포인트를 더 쉽게 사용할 수 있습니다.
  • 사용자 식별자: 사용자 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 (Log | Summary | Daily Summary) - 하루 분량의 데이터를 요청하는 경우 windowSize이 1일인 dailyRollup 메서드
세분화된 데이터를 요청하는 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: 모든 정기 결제 나열