Na tej stronie znajdziesz omówienie konwencji interfejsu API typu REST oraz indeks typowych zadań interfejsu Google Health API i przykłady każdego z nich.
Konwencje API REST
Interfejs Google Health API jest zgodny ze standardami propozycji ulepszeń interfejsów API Google (AIP), a w szczególności z AIP-127 (transkodowanie HTTP i gRPC) oraz AIP-131–AIP-135 (metody standardowe). Te standardy określają, jak dane są mapowane z wiadomości protokołu na żądanie HTTP.
Parametry zapytania
Parametry zapytania są używane, gdy dane są częścią adresu URL. Dotyczy to głównie żądań GET (pobieranie zasobu) lub żądań LIST (filtrowanie/podział na strony), ale jest też używane w przypadku operacji DELETE.
- Miejsce docelowe: dołączone do adresu URL po znaku
?. - Składnia: pary klucz-wartość oddzielone znakiem
&. - Mapowanie: każde pole w wiadomości z żądaniem, które nie jest częścią szablonu ścieżki adresu URL, jest mapowane na parametr zapytania.
- Najlepsze w przypadku: prostych typów (ciągi znaków, liczby całkowite, wyliczenia) i pól powtarzanych.
Przykładowa składnia:
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"
Treść żądania
Treść żądania jest używana, gdy dane zmieniają stan zasobu lub są zbyt duże, aby można je było umieścić w adresie URL. Treść jest zwykle reprezentacją JSON samego zasobu. Zwykle używane w przypadku operacji POST, PATCH i PUT.
- Miejsce docelowe: w ładunku HTTP (niewidoczne w adresie URL).
- Składnia: sformatowana jako obiekt JSON.
- Mapowanie: zdefiniowane w adnotacji
google.api.http.body: "*"oznacza, że cała wiadomość jest treścią.body: "resource_name"oznacza, że tylko określone pole w protokole jest treścią.
- Najlepsze rozwiązanie w przypadku: złożonych obiektów, zagnieżdżonych wiadomości i danych wrażliwych.
Przykładowa składnia:
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"
}Przypadek hybrydowy
W metodzie zgodnej z AIP-134 Update lub w operacji PATCH używane są obie te wartości.
Adres URL zawiera nazwę zasobu, treść zawiera zaktualizowane dane zasobu, a parametr zapytania (zwykle update_mask) określa, które pola mają zostać zmienione.
PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id
Content-Type: application/json
{
"endpointUri": "https://myapp.com/new-webhooks/health"
}
Najważniejsze różnice w skrócie
| Funkcja | Parametry zapytania | Treść żądania |
|---|---|---|
| Wskazówki dotyczące programu AIP | Używane do wyszukiwania, filtrowania i operacji odczytu. | Używany w przypadku operacji zapisu. |
| Widoczność | Widoczne w historii przeglądarki i dziennikach serwera. | Ukryte w adresie URL. |
| Złożoność | Ograniczone do płaskich lub powtarzających się struktur. | Obsługuje głęboko zagnieżdżone obiekty JSON. |
| Kodowanie | Musi być zakodowany w formacie adresu URL (np. spacje stają się znakiem %20). |
Standardowe kodowanie JSON. |
Daty
Wszystkie daty w interfejsie Google Health API są wyświetlane w formacie YYYY-MM-DD. Interfejs Nutrition API obsługuje standard ISO 8601 w przypadku wartości daty pod tymi warunkami:
- Rok w formacie 4-cyfrowym.
YYYY - Wartości roku w zakresie 0000–9999
- Brak egzekwowania ograniczeń daty rozpoczęcia wynikających z normy ISO-8601 lub innej epoki.
Nagłówki
Wykonanie punktów końcowych interfejsu API Google Health wymaga użycia odpowiednich nagłówków i tokena dostępu. W przypadku żądań GET i POST zalecamy używanie tego nagłówka:
Authorization: Bearer access-token Accept: application/json
Indeks zadań interfejsu API
W tej sekcji znajdziesz indeks typowych zadań związanych z interfejsem Google Health API oraz przykłady każdego z nich.
Uzyskiwanie identyfikatora użytkownika Fitbita lub Google
Po wyrażeniu przez użytkownika zgody za pomocą Google OAuth 2.0 odpowiedź tokena nie zawiera identyfikatora użytkownika Fitbita ani Google. Aby uzyskać identyfikator użytkownika, wywołaj getIdentitypunkt końcowy. getIdentity
zwraca zarówno starszy identyfikator użytkownika Fitbita, jak i identyfikator użytkownika Google.
Zalecamy, aby po wyrażeniu przez nowego użytkownika zgody za pomocą protokołu OAuth wywołać punkt końcowy getIdentity i zapisać oba identyfikatory użytkownika. Zapewnia to zgodność wsteczną i przyszłą w integracji.
Na przykład:
Żądanie
GET https://health.googleapis.com/v4/users/me/identity Authorization: Bearer access-token Accept: application/json
Odpowiedź
{
"name": "users/me/identity",
"legacyUserId": "A1B2C3",
"healthUserId": "111111256096816351"
}uzyskiwać dane częściowe dotyczące danego dnia lub szczegółowe dane zebrane w ciągu dnia;
Użyj listpunktu końcowego dla konkretnego typu danych, aby uzyskać dane śróddzienne lub szczegółowe zebrane w ciągu dnia w obsługiwanych przedziałach dla tego typu danych.
Na przykład:
Żądanie
GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints Authorization: Bearer access-token Accept: application/json
Odpowiedź
{
"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"
}Filtrowanie danych według czasu rozpoczęcia przedziału czasu
Użyj punktu końcowego list z parametrem filter, aby filtrować dane według czasu cywilnego lub przedziału.
Na przykład:
Żądanie
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
Odpowiedź
{
"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"
}Filtrowanie danych według czasu fizycznego obserwacji próbki
Użyj punktu końcowego list z parametrem filter, aby filtrować dane według czasu fizycznego obserwacji próbki.
Na przykład:
Żądanie
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
Odpowiedź
{
"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": ""
}Filtrowanie danych według źródeł danych, takich jak urządzenia do noszenia
Użyj reconcilepunktu końcowego, aby pobrać dane według „rodziny źródeł danych” w uzgodnionym strumieniu.
Oto przykład filtrowania tylko snu zarejestrowanego przez tracker w dniu po 2026-03-03:
Żądanie
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
Odpowiedź
{
"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": ""
}Zbieranie punktów danych w określonym przedziale czasu
Użyj rollUp
punktu końcowego, aby zwrócić zagregowane punkty danych na podstawie okna w sekundach w zakresie datetime na podstawie czasu fizycznego użytkowników (w UTC).
Podczas wywoływania punktu końcowego rollUp musisz podać treść żądania
reprezentującą wymagany zakres dat w czasie cywilnym użytkownika. Na przykład:
Żądanie
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"
}Odpowiedź
{
"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"
}
},
...
]
}Łączenie danych z jednego lub wielu dni
dailyRollUpPunktu końcowego należy używać, gdy chcesz agregować dane z jednego lub kilku dni, czyli windowSize. W treści żądania podaj zakres czasu cywilnego zamknięty-otwarty
dla wymaganego przedziału. W zależności od typu danych otrzymasz sumę lub średnią z przedziału.
Na przykład:
Żądanie
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
}Odpowiedź
{
"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"
}
}
]
}Wstawianie lub aktualizowanie danych o zdrowiu użytkownika
Użyj patch punktu końcowego, aby wstawić lub zaktualizować dane aplikacji Fitbit użytkownika.
Oto przykład, w którym użytkownik zarejestrował poziom tkanki tłuszczowej na wadze „HumanScale” firmy „Scales R Us”. Nowy odczyt tkanki tłuszczowej użytkownika to 20% – data: 10 marca 2026 r.
Żądanie
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
}
}Odpowiedź
{
"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
}
}
}Usuwanie danych o zdrowiu użytkownika
Użyj batchDeletepunktu końcowego, aby usunąć tablicę danych aplikacji użytkownika z aplikacji Fitbit.
Oto przykład sytuacji, w której użytkownik wcześniej zarejestrował pomiar tkanki tłuszczowej na wadze, ale chce usunąć ten zapis. Używanie user-id i data-point-id z pierwotnej funkcji wstawiania:
Żądanie
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"
]
}Odpowiedź
{
"done": true,
"response": {
"@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
}
}