엔드포인트

이 페이지에서는 REST API 규칙에 대한 개요와 일반적인 Google Health API 작업 색인 및 각 작업의 예시를 제공합니다.

REST API 규칙

Google Health API는 Google API 개선 제안서(AIP) 표준, 특히 AIP-127(HTTP 및 gRPC 트랜스코딩) 및 AIP-131~AIP-135(표준 메서드)를 따릅니다. 이러한 표준은 데이터가 proto 메시지에서 HTTP 요청으로 매핑되는 방식을 정의합니다.

쿼리 매개변수

쿼리 매개변수는 데이터가 URL의 일부인 경우에 사용됩니다. 이는 주로 GET 요청(리소스 가져오기) 또는 LIST 요청(필터링/페이지로 나누기)에 사용되지만 DELETE 작업에도 사용됩니다.

  • 게재위치: ? 뒤에 URL에 추가됩니다.
  • 문법: &로 구분된 키-값 쌍입니다.
  • 매핑: URL 경로 템플릿에 포함되지 않은 요청 메시지의 모든 필드는 쿼리 매개변수에 매핑됩니다.
  • 권장: 단순 유형(문자열, 정수, enum) 및 반복되는 입력란

필터 형식, 필드 참조, 검증 규칙, 예시의 자세한 목록은 데이터 필터링 가이드를 참조하세요.

문법 예시:

GET https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints?page_size=10&filter=data_type.interval.start_time >= "2025-10-01T00:00:00Z"

요청 본문

요청 본문은 데이터가 리소스 상태를 수정하거나 URL에 비해 너무 큰 경우에 사용됩니다. 본문은 일반적으로 리소스 자체의 JSON 표현입니다. 일반적으로 POST, PATCH, PUT 작업에 사용됩니다.

  • 게재위치: HTTP 페이로드 내부(URL에 표시되지 않음)
  • 문법: JSON 객체로 형식이 지정됩니다.
  • 매핑: google.api.http 주석에 정의됩니다.
    • body: "*"는 전체 메시지가 본문임을 의미합니다.
    • body: "resource_name"는 proto의 특정 필드만 본문임을 의미합니다.
  • 적합한 용도: 복잡한 객체, 중첩된 메시지, 민감한 정보

롤업 기간 크기, 버케팅 규칙, 집계 예시에 관한 자세한 가이드라인은 집계 데이터 가이드를 참고하세요.

문법 예시:

POST https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints:rollUp
Content-Type: application/json

{
  "range": {
    "startTime": "2025-11-05T00:00:00Z",
    "endTime": "2025-11-13T00:00:00Z"
  },
  "windowSize": "3600s"
}

하이브리드 사례

AIP-134를 준수하는 Update 메서드 또는 PATCH 작업에서는 둘 다 사용됩니다. URL에는 리소스 이름이 포함되고, 본문에는 업데이트된 리소스 데이터가 포함되며, 쿼리 매개변수(일반적으로 update_mask)는 변경할 필드를 지정합니다.

PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id
Content-Type: application/json

{
  "endpointUri": "https://myapp.com/new-webhooks/health"
}

주요 차이점 한눈에 보기

기능 쿼리 매개변수 요청 본문
AIP 가이드 검색, 필터링, 읽기 작업에 사용됩니다. 쓰기 작업에 사용됩니다.
공개 상태 브라우저 방문 기록 및 서버 로그에 표시됩니다. URL에서 숨겨집니다.
복잡성 평면 또는 반복 구조로 제한됩니다. 깊게 중첩된 JSON 객체를 지원합니다.
인코딩 URL로 인코딩되어야 합니다(예: 공백은 %20가 됨). 표준 JSON 인코딩입니다.

날짜

Google Health API의 모든 날짜는 YYYY-MM-DD 형식으로 표시됩니다. Nutrition API는 다음 조건의 날짜 값에 대해 ISO-8601 표준을 지원합니다.

  • 4자리 연도 YYYY
  • 0000~9999 범위의 연도 값
  • ISO-8601 표준 또는 기타 에포크에서 암시하는 시작일 제한이 적용되지 않음

헤더

Google Health API 엔드포인트를 실행하려면 적절한 헤더와 액세스 토큰을 사용해야 합니다. GET 및 POST 요청 모두에 다음 헤더를 사용하는 것이 좋습니다.

Authorization: Bearer access-token
Accept: application/json

API 작업 색인

이 섹션에서는 일반적인 Google Health API 작업의 색인과 각 작업의 예를 제공합니다.

Fitbit 또는 Google 사용자 ID 가져오기

사용자가 Google OAuth 2.0을 통해 동의하면 토큰 응답에 Fitbit 또는 Google 사용자 ID가 포함되지 않습니다. 승인 코드를 교환한 직후 getIdentity 엔드포인트를 호출하여 legacyUserId 및 healthUserId를 모두 가져오고 사용자의 Google 계정이 Google Health에 연결되어 있는지 확인합니다. 계정이 아직 연결되지 않은 경우 getIdentity는 400 Bad Request를 반환하고 이유로 ACCOUNT_NOT_LINKED를 반환합니다(연결되지 않은 Google 계정 처리 참고).

예를 들면 다음과 같습니다.

요청

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

응답(200 OK)

{
  "name": "users/me/identity",
  "legacyUserId": "A1B2C3",
  "healthUserId": "111111256096816351"
}

응답(400 ACCOUNT_NOT_LINKED)

{
  "error": {
    "code": 400,
    "message": "The account is not linked to Google Health.",
    "status": "FAILED_PRECONDITION",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "ACCOUNT_NOT_LINKED",
        "domain": "health.googleapis.com",
        "metadata": {
          "redirect_uri": "https://fitbit.google.com/auth/signup"
        }
      }
    ]
  }
}

하루 동안 수집된 일중 데이터 또는 세부 데이터 가져오기

특정 데이터 유형에 list 엔드포인트를 사용하여 해당 데이터 유형에 지원되는 간격으로 하루 동안 수집된 일중 또는 세부 데이터를 가져옵니다.

예를 들면 다음과 같습니다.

요청

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

응답

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "manufacturer": "",
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "steps": {
        "interval": {
          "startTime": "2026-03-04T07:05:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T07:06:00Z",
          "endUtcOffset": "0s",
          "civilStartTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 5
            }
          },
          "civilEndTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 6
            }
          }
        },
        "count": "40"
      }
    },
...
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuWjx5bmvy98zj85uG34tuMn16mu2pntsnZI32iqhq"
}

간격 데이터의 조정된 뷰 가져오기

중복 레코드나 멀티 디바이스 충돌 없이 인터벌 데이터를 가져오려면 reconcile 엔드포인트를 호출합니다. 조정 엔드포인트는 동기화 배치와 여러 기록 기기에서 중복되는 간격을 자동으로 중복 삭제하여 활동 타임라인을 렌더링하고 기간을 계산하는 데 적합한 신뢰할 수 있는 연속 스트림을 반환합니다.

연결된 기기에서 중복 간격이 생성되는 이유와 list 및 reconcile 간의 운영 비교에 관한 배경 정보는 데이터 관리 가이드를 참고하세요.

다음 예에서는 겹치는 운동 세션이 두 개 있는 사용자에 대해 list(겹치는 두 레코드를 모두 반환)과 reconcile(신뢰할 수 있는 레코드를 반환하여 충돌을 해결)의 응답을 비교합니다.

원시 목록

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer access-token
Accept: application/json
 
{
  "dataPoints": [
    {
      "name": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:20:00Z",
          "endTime": "2026-09-03T11:50:00Z"
        },
        "exerciseType": "RUNNING"
      }
    },
    {
      "name": "users/111111256096816351/dataTypes/exercise/dataPoints/4389052750481144696",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:00:00Z",
          "endTime": "2026-09-03T11:30:00Z"
        },
        "exerciseType": "RUNNING"
      }
    }
  ]
}

조정됨

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints:reconcile
Authorization: Bearer access-token
Accept: application/json
 
{
  "dataPoints": [
    {
      "dataPointName": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:20:00Z",
          "endTime": "2026-09-03T11:50:00Z"
        },
        "exerciseType": "RUNNING"
      }
    }
  ]
}

조정은 인공 시간 합집합(예: 11:00:00Z~11:50:00Z)을 합성하는 대신 중복 삭제하고 공신력 있는 레코드를 선택하여 충돌하는 세션을 해결합니다. 조정된 응답은 원래 기록된 간격(11:20:00Z~11:50:00Z)과 함께 성공한 데이터 포인트(7797422996486764704)를 반환하여 해당 세션의 측정된 원격 분석 및 측정항목의 무결성을 유지합니다.

데이터 필터링

시간 간격, 날짜 또는 관찰 시간과 같은 기준과 일치하는 데이터 포인트 레코드의 특정 하위 집합을 가져오려면 filter 매개변수와 함께 list 또는 reconcile 엔드포인트를 사용합니다.

자세한 가이드라인, 형식 규칙, 검증 오류, 쿼리 예시는 데이터 필터링 가이드를 참고하세요.

데이터 소스 계열로 필터링

특정 유형의 소스(예: 실제 웨어러블 기기 및 수동 입력)에서 데이터를 격리하거나 집계하려면 dataSourceFamily 매개변수를 사용하세요.

reconcile, rollUp, dailyRollUp의 자세한 가이드라인, 지원되는 계열, 요청 및 응답 예시는 데이터 필터링 가이드의 데이터 소스 계열별 필터링을 참조하세요.

간격 시작 시간(현지 시간)을 기준으로 데이터 필터링

filter 매개변수와 함께 list 엔드포인트를 사용하여 민간 시간 또는 간격으로 데이터를 필터링합니다.

예를 들면 다음과 같습니다.

요청

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints?filter=steps.interval.civil_start_time >= "2026-03-04T00:00:00"
Authorization: Bearer access-token
Accept: application/json

응답

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "manufacturer": "",
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "steps": {
        "interval": {
          "startTime": "2026-03-04T07:05:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T07:06:00Z",
          "endUtcOffset": "0s",
          "civilStartTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 5
            }
          },
          "civilEndTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 6
            }
          }
        },
        "count": "40"
      }
...
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuQjp5bml1bZ4ve2dhNmZvMnt4Yn7qIGQhbHN3YQ"
}

샘플 관찰 물리적 시간으로 데이터 필터링

filter 매개변수와 함께 list 엔드포인트를 사용하여 샘플 관찰 물리적 시간으로 데이터를 필터링합니다.

예를 들면 다음과 같습니다.

요청

GET https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints?filter=body_fat.sample_time.physical_time >= "2026-03-01T00:00:00Z"
Authorization: Bearer access-token
Accept: application/json

응답

{
  "dataPoints": [
    {
      "name": "users/123456789/dataTypes/body-fat/dataPoints/1234567890",
      "dataSource": {
        "recordingMethod": "UNKNOWN",
        "application": {
          "packageName": "",
          "webClientId": "",
          "googleWebClientId": "google-web-client-id"
        },
        "platform": "GOOGLE_WEB_API"
      },
      "bodyFat": {
        "sampleTime": {
          "physicalTime": "2026-03-10T10:00:00Z",
          "utcOffset": "0s",
          "civilTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 10
            },
            "time": {
              "hours": 10
            }
          }
        },
        "percentage": 20
      }
    }
  "nextPageToken": ""
}

데이터 소스 계열별로 필터링 및 집계

데이터 소스 제품군은 데이터 소스(예: 스마트시계, 모바일 앱, 수동 입력)의 논리적 그룹입니다. 이를 통해 특정 유형의 소스(예: 실제 웨어러블 기기 및 수동 입력)에서 데이터를 분리하거나 집계할 수 있습니다.

reconcile, rollUp, dailyRollUp 엔드포인트는 모두 dataSourceFamily 매개변수를 지원합니다. 전달 메커니즘은 엔드포인트에 따라 다릅니다.

엔드포인트(HTTP 메서드) 메커니즘
reconcile (GET) dataSourceFamily를 URL 쿼리 매개변수로 전달합니다.
rollUp (POST) dataSourceFamily를 JSON 요청 본문의 필드로 전달합니다.
dailyRollUp (POST) dataSourceFamily를 JSON 요청 본문의 필드로 전달합니다.

지원되는 데이터 소스 제품군

다음 표에서는 지원되는 dataSourceFamily 값을 설명합니다.

옵션 설명
users/me/dataSourceFamilies/all-sources 기본값. 등록된 모든 퍼스트 파티(1P) 및 서드 파티(3P) 데이터 소스에서 조정된 데이터 포인트를 반환합니다. 이 옵션을 사용하면 서드 파티 앱 데이터가 반환됩니다(예: 스마트시계 걸음 수 + 서드 파티 앱 걸음 수 + 휴대전화 걸음 수 + 수동 걸음 수).
users/me/dataSourceFamilies/google-wearables Google 및 Fitbit 트래커 기기(예: Fitbit 웨어러블 트래커, Pixel Watch)에서 기록한 데이터가 포함됩니다. 수동으로 기록된 데이터 및 휴대전화에서 추정한 데이터는 제외됩니다. 통합에 웨어러블 하드웨어에서 직접 기록한 원시 센서 원격 분석이 필요한 경우 이 옵션을 사용합니다.
users/me/dataSourceFamilies/google-sources 퍼스트 파티 Google 및 Fitbit 소스가 포함됩니다. 여기에는 실물 트래커 기기 기록, 헬스 커넥트의 데이터, 퍼스트 파티 앱(예: Fitbit 앱 또는 Google 피트니스)을 통해 수동으로 입력한 항목이 포함됩니다.

특정 데이터 소스 계열에서 조정된 데이터 스트림을 가져오려면 dataSourceFamily 쿼리 매개변수를 사용하여 reconcile 엔드포인트를 호출합니다.

예를 들어 다음 GET 요청은 2026-03-03 이후의 트래커 기록 수면을 가져옵니다.

요청

GET https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints:reconcile?dataSourceFamily=users/me/dataSourceFamilies/google-wearables&filter=sleep.interval.civil_end_time >= "2026-03-03"
Authorization: Bearer access-token
Accept: application/json

응답

{
  "dataPoints": [
    {
      "name": "users/2515055256096816351/dataTypes/sleep/dataPoints/2724123844716220216",
      "dataSource": {
        "recordingMethod": "DERIVED",
        "device": {
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "sleep": {
        "interval": {
          "startTime": "2026-03-03T20:57:30Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T04:41:30Z",
          "endUtcOffset": "0s"
        },
        "type": "STAGES",
        "stages": [
          {
            "startTime": "2026-03-03T20:57:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-03T20:59:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE",
            "createTime": "2026-03-04T04:43:40.937183Z",
            "updateTime": "2026-03-04T04:43:40.937183Z"
          },
          {
            "startTime": "2026-03-04T04:07:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-04T04:41:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE",
            "createTime": "2026-03-04T04:43:40.937183Z",
            "updateTime": "2026-03-04T04:43:40.937183Z"
          }
        ],
        "metadata": {
          "stagesStatus": "SUCCEEDED",
          "processed": true,
          "main": true
        },
        "summary": {
          "minutesInSleepPeriod": "464",
          "minutesAfterWakeUp": "0",
          "minutesToFallAsleep": "0",
          "minutesAsleep": "407",
          "minutesAwake": "57",
          "stagesSummary": [
            {
              "type": "AWAKE",
              "minutes": "56",
              "count": "12"
            },
            {
              "type": "LIGHT",
              "minutes": "198",
              "count": "19"
            },
            {
              "type": "DEEP",
              "minutes": "114",
              "count": "10"
            },
            {
              "type": "REM",
              "minutes": "94",
              "count": "4"
            }
          ]
        },
        "createTime": "2026-03-04T04:43:40.337983Z",
        "updateTime": "2026-03-04T04:43:40.937183Z"
      }
    }
  ],
  "nextPageToken": ""
}

특정 데이터 소스 계열로 제한된 특정 기간 크기에 대해 데이터 포인트를 집계하려면 rollUp 엔드포인트를 호출하고 JSON 요청 본문에 dataSourceFamily 필드를 전달합니다.

다음 POST 요청은 웨어러블 기기에서만 집계된 시간별 간격(3600s)의 일중 걸음 수를 쿼리합니다.

요청

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

{
  "range": {
    "startTime": "2026-07-29T00:00:00Z",
    "endTime": "2026-07-29T23:59:59Z"
  },
  "windowSize": "3600s",
  "dataSourceFamily": "users/me/dataSourceFamilies/google-wearables"
}

응답

{
  "rollupDataPoints": [
    {
      "startTime": "2026-07-29T08:00:00Z",
      "endTime": "2026-07-29T09:00:00Z",
      "steps": {
        "countSum": "1200"
      }
    },
    {
      "startTime": "2026-07-29T09:00:00Z",
      "endTime": "2026-07-29T10:00:00Z",
      "steps": {
        "countSum": "3450"
      }
    }
  ]
}

특정 소스 계열의 일일 데이터 포인트를 집계하려면 dailyRollUp 엔드포인트를 호출하고 요청 본문에 dataSourceFamily 필드를 전달합니다.

예를 들어 다음 요청은 모든 퍼스트 파티 Google 및 Fitbit 소스(웨어러블 + 수동 입력)를 포함하여 사용자의 걸음 수에 대한 일일 롤업을 계산합니다.

요청

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

{
  "range": {
    "start": {
      "date": {
        "year": 2026,
        "month": 7,
        "day": 28
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    },
    "end": {
      "date": {
        "year": 2026,
        "month": 7,
        "day": 30
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    }
  },
  "windowSizeDays": 1,
  "dataSourceFamily": "users/me/dataSourceFamilies/google-sources"
}

응답

{
  "rollupDataPoints": [
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "8430"
      }
    },
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "11245"
      }
    }
  ]
}

일정 기간 동안의 데이터 포인트 집계

rollUp 엔드포인트를 사용하여 사용자의 실제 시간(UTC)에서 datetime 범위에 걸쳐 초 단위(windowSize)의 기간을 기준으로 데이터 포인트의 집계를 반환합니다.

rollUp 엔드포인트를 호출할 때 필수 폐쇄-개방 시간 range 및 windowSize(최소 "1s")을 나타내는 요청 본문을 제공합니다. windowSize 요구사항, 저장소 해상도 정렬, 버케팅 규칙, 요청 및 응답 예시에 관한 자세한 가이드라인은 데이터 집계 가이드의 물리적 시간 간격에 따른 집계를 참고하세요.

하루 또는 여러 날에 걸쳐 데이터 집계

dailyRollUp 엔드포인트를 사용하여 하루 또는 여러 날(windowSizeDays)에 걸쳐 데이터를 집계합니다. 요청 본문에 필요한 간격의 폐쇄형-개방형 시민 시간 range을 제공합니다. 데이터 유형에 따라 엔드포인트는 각 기간의 합계 또는 평균을 반환합니다.

일일 집계 동작, 시민 시간 처리, 요청별 범위 제한, 요청 및 응답 예시에 관한 자세한 내용은 합산 데이터 가이드의 달력 일수 간 집계를 참고하세요.

사용자의 건강 데이터 업데이트

patch 엔드포인트를 사용하여 사용자의 건강 데이터를 업데이트합니다.

patch 엔드포인트는 요청 URL에 지정된 식별자를 기반으로 기존 레코드를 업데이트합니다. 이전에 삽입된 데이터 포인트의 식별자를 제공합니다. API가 기존 레코드를 덮어씁니다.

데이터 포인트의 간격 타임스탬프(startTime 및 endTime)는 레코드 소유자가 업데이트하거나 헬스 커넥트와 같은 업스트림 플랫폼에서 전파할 수도 있습니다. 타임스탬프 변경 가능성에 대한 자세한 내용은 데이터 관리 가이드를 참조하세요. 간격 타임스탬프 업데이트 예시는 기존 데이터의 간격 타임스탬프 업데이트를 참조하세요.

데이터 포인트 식별자를 사용해야 하는 경우

데이터 포인트 식별자는 다음 시나리오에서 필수입니다.

  • 타겟팅된 업데이트: 특정 측정을 업데이트하려면 patch 요청에 식별자를 제공합니다.
  • 삭제: 식별자를 유지하면 애플리케이션이 나중에 batchDelete 엔드포인트를 사용하여 레코드를 삭제할 수 있습니다.

다음은 사용자가 'Scales R Us' 회사의 'HumanScale'이라는 체중계에서 체지방 수치를 업데이트하는 예입니다. 2026년 3월 10일의 사용자 새 체지방 수치는 20% 입니다.

요청

PATCH https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints/1234567890
Authorization: Bearer access-token
Content-Type: application/json

{
  "name": "users/me/dataTypes/body-fat/dataPoints/1234567890",
  "dataSource": {
    "recordingMethod": "ACTIVELY_MEASURED",
    "device": {
      "formFactor": "SCALE",
      "manufacturer": "Scales R Us",
      "displayName": "HumanScale"
    }
  },
  "bodyFat": {
    "sampleTime": {
      "physicalTime": "2026-03-10T10:00:00Z"
    },
    "percentage": 20
  }
}

응답

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
    "name": "users/123456789/dataTypes/body-fat/dataPoints/1234567890",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "device": {
        "formFactor": "SCALE",
        "manufacturer": "Scales R Us",
        "displayName": "HumanScale"
      },
      "application": {
        "googleWebClientId": "618308034039.apps.googleusercontent.com"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "bodyFat": {
      "sampleTime": {
        "physicalTime": "2026-03-10T10:00:00Z"
      },
      "percentage": 20
    }
  }
}

기존 데이터의 간격 타임스탬프 업데이트

기존 데이터 포인트의 간격 타임스탬프(REST JSON 페이로드의 startTime 및 endTime 또는 gRPC의 start_time 및 end_time)를 업데이트하려면 데이터 포인트의 리소스 URI에 PATCH 요청을 보냅니다. 레코드의 원래 작성자 또는 소유자만 필드를 수정할 수 있습니다. 애플리케이션은 자신이 만들지 않은 데이터 포인트를 수정할 수 없습니다.

타임스탬프 변경 가능성, 헬스 커넥트의 업스트림 업데이트, 캐싱 영향에 관한 배경 정보는 데이터 관리 가이드를 참고하세요.

다음 예에서는 소유자 애플리케이션이 patch 엔드포인트를 사용하여 기존 수분 섭취량 로그의 간격 타임스탬프를 업데이트하는 방법을 보여줍니다.

요청

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

{
  "hydrationLog": {
    "interval": {
      "startTime": "2026-09-03T10:05:00Z",
      "endTime": "2026-09-03T10:19:59Z"
    },
    "amountConsumed": {
      "milliliters": 350
    }
  }
}

응답

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/111111256096816351/dataTypes/hydration-log/dataPoints/4093039283164890826",
    "hydrationLog": {
      "interval": {
        "startTime": "2026-09-03T10:05:00Z",
        "endTime": "2026-09-03T10:19:59Z",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 10,
            "minutes": 5
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 10,
            "minutes": 19,
            "seconds": 59
          }
        }
      },
      "amountConsumed": {
        "milliliters": 350
      }
    }
  }
}

음식 항목 기록하기

음식 항목을 기록하려면 nutrition-log dataPoints 엔드포인트에 POST 요청을 보냅니다. 요청 본문에는 nutritionLog 객체가 있는 DataPoint가 포함됩니다. 자세한 내용은 영양 가이드를 참고하세요.

예를 들면 다음과 같습니다.

요청

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"
    },
    "foodDisplayName": "Banana",
    "mealType": "LUNCH",
    "energy": {
      "kcal": 105
    },
    "totalCarbohydrate": {
      "grams": 27
    },
    "totalFat": {
      "grams": 0.3
    }
  }
}

응답

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/123456789/dataTypes/nutrition-log/dataPoints/567890",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "platform": "GOOGLE_WEB_API"
    },
    "nutritionLog": {
      "interval": {
        "startTime": "2026-06-16T12:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-06-16T12:30:00Z",
        "endUtcOffset": "0s"
      },
      "energy": {
        "kcal": 105
      },
      "totalCarbohydrate": {
        "grams": 27
      },
      "totalFat": {
        "grams": 0.3
      },
      "mealType": "LUNCH",
      "foodDisplayName": "Banana"
    }
  }
}

사용자 건강 데이터 삭제

batchDelete 메서드를 사용하여 사용자의 Fitbit 앱 데이터 배열을 삭제합니다.

다음은 사용자가 이전에 체중계에서 체지방을 기록했지만 기록을 삭제하려는 경우의 예입니다. 원래 삽입 작업의 user-id 및 data-point-id를 사용합니다.

요청

POST https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints:batchDelete
Authorization: Bearer access-token
Accept: application/json
content-length: 93

{
  "names": [
    "users/123456789/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

응답

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
  }
}

기기 정보 찾기

list 엔드포인트를 사용하여 사용자 계정에 페어링된 기기 목록을 가져옵니다. 여기에는 기기의 모델 정보(deviceVersion)와 Google Health 모바일 앱과 마지막으로 동기화된 시간(lastSyncTime)이 포함됩니다.

목록 구성 및 동기화 정보는 동기화 문제를 해결하거나 마지막 동기화 시간 이후의 이전 데이터를 가져오는 데 유용합니다.

예를 들면 다음과 같습니다.

요청

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

응답

{
  "pairedDevices": [
    {
      "name": "users/me/pairedDevices/123456",
      "deviceType": "TRACKER",
      "batteryStatus": "High",
      "batteryLevel": 88,
      "lastSyncTime": "2026-03-04T07:05:00Z",
      "deviceVersion": "Charge 6",
      "macAddress": "00:11:22:33:44:55",
      "features": [
        "STEPS",
        "HEART_RATE"
      ]
    }
  ]
}

이전 데이터 쿼리

Google Health API의 핵심 이점 중 하나는 장기간에 걸쳐 사용자의 성과를 추적하고 건강 상태를 모니터링할 수 있다는 것입니다. 사용자의 데이터는 기록된 시점까지 거슬러 올라가 쿼리할 수 있습니다. API는 애플리케이션에서 사용할 수 있는 이전 데이터의 양에 제한을 두지 않습니다.

하지만 이전 데이터 쿼리는 여전히 표준 비율 제한의 적용을 받습니다. 시스템 안정성을 관리하고 과도한 페이로드를 방지하기 위해 Google Health API는 엔드포인트별 페이지 크기로 자동 페이지 매김을 사용합니다. 다음 경계 및 동작을 참고하세요.

  • 자동 페이지로 나누기: 긴 기간의 데이터를 쿼리하는 경우 API는 해당 엔드포인트의 페이지 크기 한도까지의 첫 번째 결과 페이지와 nextPageToken만 반환합니다. 후속 페이지를 요청하려면 nextPageToken를 사용해야 합니다.
  • 가변 페이지 크기: 상한은 엔드포인트 및 데이터 유형에 따라 다릅니다. 대부분의 데이터 유형에서 페이지 크기는 최대 10,000개로 제한됩니다. 하지만 exercise 및 sleep와 같은 특정 데이터 유형의 경우 기본 및 최대 페이지 크기는 25로 제한됩니다. 예를 들어 클라이언트가 지난 10년 동안의 모든 수면 데이터를 요청하는 경우에도 API는 첫 페이지에 수면 세션 25개만 반환합니다.
  • 롤업 기간 제한: 데이터 롤업 및 집계 엔드포인트(예: rollUp 및 dailyRollUp)의 경우 쿼리 기간은 데이터 유형에 따라 제한됩니다.
    • calories-in-heart-rate-zone, heart-rate, active-minutes, total-calories의 최대 범위는 14일입니다.
    • 다른 모든 롤업 데이터 유형의 경우 최대 범위는 90일입니다.

애플리케이션에 필요한 이전 데이터의 양에 따라 전체 데이터 세트를 검색하려면 페이지를 순차적으로 페이지로 나누어야 합니다. 애플리케이션의 데이터 동기화 프로세스를 설계할 때 이 점을 염두에 두세요.

최적의 성능을 보장하고 API 오류를 방지하려면 이전 데이터를 쿼리할 때 다음 가이드라인을 따르세요.

단계별 데이터 동기화(핫 로드와 콜드 로드)

  • 초기 '핫' 로드: 기본 로드 시퀀스 중에 최근 7~14일의 데이터만 가져와 렌더링합니다. 이렇게 하면 사용자가 장기 실행 쿼리를 기다리지 않고도 데이터를 즉시 볼 수 있습니다.
  • I am going to provide a list of glossary for this session. Use these terms as references, but apply your own judgment based on the definitions provided. If a term doesn't fit the context, just ignore the suggestion. Source Term: historical data The definition is: Data collected in a past period of time. Translation under this definition: 이전 데이터 : 과거 데이터 Source Term: historical data The definition is: Statistics collected during advertising campaigns involving ad requests, bids, impressions, conversions etc. Used to optmize running ad campaigns. Translation under this definition: 이전 데이터 : 과거 데이터 Source Term: background process The definition is: A process that runs or takes place in the background. Translation under this definition: 백그라운드 프로세스

집계를 위한 쿼리 청킹

  • 롤업 및 일일 롤업 엔드포인트는 최대 기간 제한(데이터 유형에 따라 14일 또는 90일)을 적용하므로 대규모 과거 집계 쿼리를 이러한 제한 내에서 더 작은 순차적 간격으로 세분화해야 합니다.
  • 동시 실행 한도를 준수하고 안정적인 UI 진행률 표시기를 유지하기 위해 이러한 하위 쿼리를 안전하게 일괄 처리하거나 순차적으로 처리합니다.

사전 집계된 롤업 활용

사전 집계된 요약 엔드포인트(예: DailyRollUpDataPoints)를 사용하도록 개요 대시보드 및 추세 차트를 재구성합니다. 이렇게 하면 백엔드의 컴퓨팅 오버헤드와 클라이언트로의 네트워크 전송 시간이 크게 줄어듭니다.

복원력 있는 오류 처리(스마트 재시도)

  • 비율 제한(429 Too Many Requests) 및 서버 게이트웨이 제한 시간(504 Gateway Timeout)이 발생하면 엄격한 지수 백오프 처리를 구현합니다. 실패한 대규모 페이로드를 즉시 재시도하지 마세요. 즉시 재시도하면 백엔드 정체가 가중되고 시스템 성능 저하가 심화됩니다.
이전
클라이언트 라이브러리
다음
필터