엔드포인트

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

REST API 규칙

Google Health API는 Google API 개선 제안 (AIP) 표준, 특히 AIP-127 (HTTP 및 gRPC 트랜스코딩) 및 AIP-131~ AIP-135 (표준 메서드)를 따릅니다. 이러한 표준은 프로토 메시지에서 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"은 프로토의 특정 필드만 본문임을 의미합니다.
  • 가장 적합한 경우: 복잡한 객체, 중첩된 메시지, 민감한 데이터

구문 예시:

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가 포함되지 않습니다. 사용자 ID를 가져오려면 getIdentity 엔드포인트를 호출합니다. getIdentity 는 Fitbit 기존 사용자 ID와 Google 사용자 ID를 모두 반환합니다.

OAuth를 통해 새 사용자가 동의하는 즉시 getIdentity 엔드포인트를 호출하고 두 사용자 ID를 모두 저장하는 것이 좋습니다. 이렇게 하면 통합에서 이전 버전과의 호환성 및 향후 호환성이 제공됩니다.

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

요청

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

응답

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

하루 종일 수집된 시간 내 또는 세부 데이터 가져오기

특정 데이터 유형의 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"
}

간격 시민 시작 시간으로 데이터 필터링

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/2515055256096816351/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 엔드포인트를 사용하여 조정된 스트림에서 "데이터 소스 패밀리"별로 데이터를 가져옵니다.

다음은 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 endpoint를 사용하여 사용자의 실제 시간 (UTC)을 기준으로 datetime 범위에서 초 단위의 창을 기준으로 데이터 포인트의 집계를 반환합니다.

rollUp 엔드포인트를 호출할 때는 사용자의 시민 시간으로 필요한 날짜 범위를 나타내는 요청 본문을 제공해야 합니다. 예를 들면 다음과 같습니다.

요청

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

{
  "range": {
    "startTime": "2026-02-17T17:00:00Z",
    "endTime": "2026-02-17T17:59:59Z"
  },
  "windowSize": "30s"
}

응답

{
  "rollupDataPoints": [
    {
      "startTime": "2026-02-17T17:55:00Z",
      "endTime": "2026-02-17T17:55:30Z",
      "steps": {
        "countSum": "41"
      }
    },
    {
      "startTime": "2026-02-17T17:54:00Z",
      "endTime": "2026-02-17T17:54:30Z",
      "steps": {
        "countSum": "31"
      }
    },
...
  ]
}

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

dailyRollUp 엔드포인트는 하루 또는 여러 날에 걸쳐 데이터를 집계하려는 경우에 사용해야 합니다. windowSize 요청 본문에서 필요한 간격의 닫힌-열린 시민 시간 범위를 제공합니다. 데이터 유형에 따라 간격의 합계 또는 평균을 받게 됩니다.

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

요청

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": 2,
        "day": 26
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    },
    "end": {
      "date": {
        "year": 2026,
        "month": 2,
        "day": 26
      },
      "time": {
        "hours": 23,
        "minutes": 59,
        "seconds": 59,
        "nanos": 0
      }
    }
  },
  "windowSizeDays": 1
}

응답

{
  "rollupDataPoints": [
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 2,
          "day": 26
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 2,
          "day": 26
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "3822"
      }
    }
  ]
}

사용자의 건강 데이터 삽입 또는 업데이트

patch 엔드포인트를 사용하여 사용자의 Fitbit 앱 데이터를 삽입하거나 업데이트합니다.

다음은 사용자가 'Scales R Us'라는 회사에서 'HumanScale'이라는 체중계로 체지방을 기록한 예입니다. 사용자의 새 체지방 측정값은 2026-03-10의 경우 20% 입니다.

요청

PATCH https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints/1234567890
Authorization: Bearer access-token
content-length: 329

{
  "name": "bodyFatName",
  "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/2515055256096816351/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
    }
  }
}

사용자 건강 데이터 삭제

사용자의 Fitbit 앱 데이터 배열을 삭제하려면 batchDelete endpoint를 사용합니다.

다음은 사용자가 이전에 체중계로 체지방을 기록했지만 기록을 삭제하려는 예입니다. 원래 삽입 작업의 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/2515055256096816351/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

응답

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
  }
}
이전
클라이언트 라이브러리
다음
범용 링크 및 앱 링크