Endpunkte

Auf dieser Seite finden Sie eine Übersicht über die REST API-Konventionen sowie einen Index der häufigsten Google Health API-Aufgaben und Beispiele für jede Aufgabe.

REST API-Konventionen

Die Google Health API entspricht den Google API Improvement Proposals (AIP), insbesondere AIP-127 (HTTP- und gRPC-Transcodierung) und AIP-131 bis AIP-135 (Standardmethoden). Diese Standards definieren, wie Daten aus einer Proto-Nachricht einer HTTP-Anfrage zugeordnet werden.

Suchparameter

Suchparameter werden verwendet, wenn die Daten Teil der URL sind. Dies gilt hauptsächlich für GET-Anfragen (Abrufen einer Ressource) oder LIST-Anfragen (Filtern/Paginierung), wird aber auch für DELETE-Vorgänge verwendet.

  • Placement: Wird nach einem ? an die URL angehängt.
  • Syntax: Schlüssel/Wert-Paare, die durch & getrennt sind.
  • Zuordnung: Jedes Feld in der Anfragenachricht, das nicht Teil der URL-Pfadvorlage ist, wird einem Suchparameter zugeordnet.
  • Am besten geeignet für: Einfache Typen (Strings, Ganzzahlen, Enums) und wiederkehrende Felder.

Beispielsyntax:

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"

Anfragetext

Der Anfragebody wird verwendet, wenn die Daten den Status einer Ressource ändern oder zu groß für eine URL sind. Der Textkörper ist in der Regel eine JSON-Darstellung der Ressource selbst. Wird in der Regel für die Vorgänge POST, PATCH und PUT verwendet.

  • Platzierung: Innerhalb der HTTP-Nutzlast (nicht in der URL sichtbar).
  • Syntax: Als JSON-Objekt formatiert.
  • Zuordnung: In der Annotation google.api.http definiert.
    • body: "*" bedeutet, dass die gesamte Nachricht der Textkörper ist.
    • body: "resource_name" bedeutet, dass nur ein bestimmtes Feld im Proto der Textkörper ist.
  • Am besten geeignet für: Komplexe Objekte, verschachtelte Nachrichten und sensible Daten.

Beispielsyntax:

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"
}

Der Hybridfall

In einer AIP-134-kompatiblen Update-Methode oder einem PATCH-Vorgang werden beide verwendet. Die URL enthält den Ressourcennamen, der Text enthält die aktualisierten Ressourcendaten und ein Abfrageparameter (normalerweise update_mask) gibt an, welche Felder geändert werden sollen.

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

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

Wichtige Unterschiede auf einen Blick

Funktion Suchparameter Anfragetext
AIP-Leitfaden Wird für Such-, Filter- und Lesevorgänge verwendet. Wird für Schreibvorgänge verwendet.
Sichtbarkeit Sichtbar im Browserverlauf und in Serverlogs. Die URL ist ausgeblendet.
Komplexität Beschränkt auf flache oder wiederholte Strukturen. Unterstützt tief verschachtelte JSON-Objekte.
Encoding Muss URL-codiert sein (z. B. werden Leerzeichen zu %20). Standard-JSON-Codierung.

Daten

Alle Datumsangaben in der Google Health API werden im Format YYYY-MM-DD angezeigt. Die Nutrition API unterstützt den ISO 8601-Standard für Datumswerte unter den folgenden Bedingungen:

  • Eine vierstellige Jahreszahl YYYY
  • Jahreswerte im Bereich von 0000 bis 9999
  • Keine Durchsetzung von Startdatumsbeschränkungen, die durch den ISO 8601-Standard oder eine andere Epoche impliziert werden

Header

Für die Ausführung der Google Health API-Endpunkte sind die entsprechenden Header und das Zugriffstoken erforderlich. Der folgende Header wird sowohl für GET- als auch für POST-Anfragen empfohlen:

Authorization: Bearer access-token
Accept: application/json

API-Aufgabenindex

In diesem Abschnitt finden Sie einen Index mit häufigen Google Health API-Aufgaben und Beispielen für jede Aufgabe.

Fitbit- oder Google-Nutzer-ID abrufen

Nachdem ein Nutzer über Google OAuth 2.0 zugestimmt hat, enthält die Tokenantwort nicht die Fitbit- oder Google-Nutzer-ID. Rufen Sie die Nutzer-ID über den Endpunkt getIdentity ab. getIdentity gibt sowohl die alte Fitbit-Nutzer-ID als auch die Google-Nutzer-ID zurück.

Wir empfehlen, dass Sie den getIdentity-Endpunkt aufrufen und beide Nutzer-IDs speichern, sobald ein neuer Nutzer über OAuth seine Einwilligung erteilt. So wird die Abwärts- und Vorwärtskompatibilität Ihrer Integration gewährleistet.

Beispiel:

Anfrage

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

Antwort

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

Tagesdaten oder detaillierte Daten abrufen, die im Laufe eines Tages erhoben wurden

Verwende den list-Endpunkt für einen bestimmten Datentyp, um detaillierte Daten abzurufen, die im Laufe des Tages in unterstützten Intervallen für diesen Datentyp erfasst wurden.

Beispiel:

Anfrage

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

Antwort

{
  "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"
}

Abgestimmte Ansicht von Intervall-Daten abrufen

Wenn Sie Intervalldaten ohne sich überschneidende Datensätze oder Konflikte für verschiedene Geräte abrufen möchten, rufen Sie den reconcile-Endpunkt auf. Der Abgleichsendpunkt dedupliziert automatisch sich überschneidende Intervalle über Synchronisierungsbatches und mehrere Aufzeichnungsgeräte hinweg und gibt einen autoritativen, kontinuierlichen Stream zurück, der sich für das Rendern von Aktivitätszeitachsen und das Berechnen von Zeiträumen eignet.

Hintergrundinformationen dazu, warum verbundene Geräte sich überschneidende Intervalle erzeugen, und ein operativer Vergleich zwischen list und reconcile finden Sie im Leitfaden zur Datenverwaltung.

Im folgenden Beispiel wird die Antwort von list (die beide sich überschneidenden Datensätze zurückgibt) mit der Antwort von reconcile (die den Konflikt löst, indem der autoritative Datensatz zurückgegeben wird) für einen Nutzer mit zwei sich überschneidenden Trainingseinheiten verglichen:

Rohliste

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"
      }
    }
  ]
}

Abgeglichen

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"
      }
    }
  ]
}

Bei der Abstimmung werden widersprüchliche Sitzungen bereinigt, indem Duplikate entfernt und der maßgebliche Datensatz ausgewählt wird, anstatt eine künstliche Zeitvereinigung zu erstellen (z. B. 11:00:00Z bis 11:50:00Z). Bei der abgestimmten Antwort wird der beste Datenpunkt (7797422996486764704) mit dem ursprünglich aufgezeichneten Intervall (11:20:00Z bis 11:50:00Z) zurückgegeben. So bleibt die Integrität der gemessenen Telemetrie und Messwerte dieser Sitzung erhalten.

Daten filtern

Wenn Sie bestimmte Teilmengen von Datenpunkt-Datensätzen abrufen möchten, die Kriterien wie ein Zeitintervall, ein Datum oder eine Beobachtungszeit erfüllen, verwenden Sie den Endpunkt list oder reconcile mit einem filter-Parameter.

Ausführliche Richtlinien, Formatierungsregeln, Validierungsfehler und Beispielabfragen finden Sie im Leitfaden zum Filtern von Daten.

Nach Datenquellenfamilie filtern

Wenn Sie Daten aus bestimmten Quelltypen isolieren oder zusammenfassen möchten (z. B. Daten von physischen Wearables im Vergleich zu manuellen Einträgen), verwenden Sie den Parameter dataSourceFamily.

Detaillierte Richtlinien, unterstützte Familien sowie Anfrage- und Antwortbeispiele für reconcile, rollUp und dailyRollUp finden Sie im Leitfaden zum Filtern von Daten unter Nach Datenquellenfamilie filtern.

Daten nach zivilrechtlicher Startzeit eines Intervalls filtern

Verwenden Sie den Endpunkt list mit dem Parameter filter, um Daten nach bürgerlicher Zeit oder einem Intervall zu filtern.

Beispiel:

Anfrage

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

Antwort

{
  "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"
}

Daten nach der physischen Zeit einer Stichprobenbeobachtung filtern

Verwenden Sie den list-Endpunkt mit dem Parameter filter, um Daten nach der physischen Zeit der Stichprobenbeobachtung zu filtern.

Beispiel:

Anfrage

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

Antwort

{
  "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": ""
}

Nach Datenquellenfamilie filtern und aggregieren

Eine Datenquellenfamilie ist eine logische Gruppierung von Datenquellen (z. B. Smartwatches, mobile Apps oder manuelle Einträge). So können Sie Daten aus bestimmten Quellen isolieren oder zusammenfassen, z. B. Daten von physischen Wearables im Vergleich zu manuellen Einträgen.

Die Endpunkte reconcile, rollUp und dailyRollUp unterstützen alle den Parameter dataSourceFamily. Der Übergabemechanismus hängt vom Endpunkt ab:

Endpunkt (HTTP-Methode) Mechanismus
reconcile (GET) Übergeben Sie dataSourceFamily als URL-Suchparameter.
rollUp (POST) Übergeben Sie dataSourceFamily als Feld im JSON-Anfragetext.
dailyRollUp (POST) Übergeben Sie dataSourceFamily als Feld im JSON-Anfragetext.

Unterstützte Datenquellenfamilien

In der folgenden Tabelle werden die unterstützten dataSourceFamily-Werte beschrieben:

Option Beschreibung
users/me/dataSourceFamilies/all-sources Standardwert: Gibt Datenpunkte zurück, die für alle registrierten Datenquellen für selbst erhobene Daten und Drittanbieterdaten abgeglichen wurden. Mit dieser Option werden Daten aus Drittanbieter-Apps zurückgegeben, z. B. Schritte von der Smartwatch, Schritte aus Drittanbieter-Apps, Schritte vom Smartphone und manuell eingegebene Schritte.
users/me/dataSourceFamilies/google-wearables Enthält Daten, die von Google- und Fitbit-Trackern (z. B. Fitbit-Wearables und Pixel Watch) aufgezeichnet wurden. Manuell erfasste Daten und vom Smartphone geschätzte Daten sind ausgeschlossen. Verwenden Sie diese Option, wenn für Ihre Integration rohe Sensortelemetriedaten erforderlich sind, die direkt von der Wearable-Hardware aufgezeichnet werden.
users/me/dataSourceFamilies/google-sources Beinhaltet selbst erhobene Daten von Google und Fitbit. Dazu gehören Aufzeichnungen von Tracker-Geräten, Daten von Health Connect und alle manuellen Einträge, die über Erstanbieter-Apps wie die Fitbit App oder Google Fit protokolliert wurden.

Wenn Sie einen abgeglichenen Datenstream aus einer bestimmten Datenquellenfamilie abrufen möchten, rufen Sie den reconcile-Endpunkt mit dem Abfrageparameter dataSourceFamily auf.

Mit der folgenden GET-Anfrage wird beispielsweise der von einem Tracker aufgezeichnete Schlaf für den Tag nach dem 03.03.2026 abgerufen:

Anfrage

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

Antwort

{
  "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": ""
}

Wenn Sie Datenpunkte über eine bestimmte Fenstergröße hinweg aggregieren möchten, die auf eine bestimmte Datenquellenfamilie beschränkt ist, rufen Sie den Endpunkt rollUp auf und übergeben Sie das Feld dataSourceFamily im JSON-Anfragetext.

Mit der folgenden POST-Anfrage werden die Anzahl der Schritte pro Stunde (3600s) für den aktuellen Tag abgefragt, die ausschließlich von Wearables erfasst wurden:

Anfrage

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"
}

Antwort

{
  "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"
      }
    }
  ]
}

Wenn Sie tägliche Datenpunkte für eine bestimmte Quellfamilie zusammenfassen möchten, rufen Sie den Endpunkt dailyRollUp auf und übergeben Sie das Feld dataSourceFamily im Anfragetext.

Im folgenden Beispiel werden die täglichen Zusammenfassungen für die Schritte des Nutzers berechnet, einschließlich aller Google- und Fitbit-Quellen von Erstanbietern (Wearables + manuelle Einträge):

Anfrage

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"
}

Antwort

{
  "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"
      }
    }
  ]
}

Datenpunkte über einen bestimmten Zeitraum hinweg aggregieren

Verwenden Sie den rollUp-Endpunkt, um die aggregierten Datenpunkte basierend auf einem Fenster in Sekunden über den datetime-Bereich basierend auf der physischen Zeit des Nutzers (in UTC) zurückzugeben.

Geben Sie beim Aufrufen des Endpunkts rollUp den Anfragetext an, der den erforderlichen Zeitraum und windowSize darstellt. Beachten Sie die folgenden Anforderungen für windowSize:

  • Mindestfenstergröße: Die Dauer von windowSize muss mindestens 1 Sekunde betragen ("1s"). Dauern unter einer Sekunde, Null oder negative Dauern werden mit 400 Bad Request (INVALID_ROLLUP_WINDOW) abgelehnt.
  • Abstimmung der Speicherauflösung: Damit aggregierte Daten nicht ungleichmäßig auf die Unter-Buckets verteilt werden, wählen Sie ein windowSize aus, das gleich oder größer als die zugrunde liegende Speicherauflösung des Datentyps ist (z. B. "60s" für 1-Minuten-Schrittintervalle). Weitere Informationen finden Sie unter Größe des Rollup-Fensters und zugrunde liegende Speicherauflösung.

Wenn Sie beispielsweise die Schrittanzahl in 1‑Minuten-Intervallen (60s) zusammenfassen möchten:

Anfrage

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": "60s"
}

Antwort

{
  "rollupDataPoints": [
    {
      "startTime": "2026-02-17T17:55:00Z",
      "endTime": "2026-02-17T17:56:00Z",
      "steps": {
        "countSum": "72"
      }
    },
    {
      "startTime": "2026-02-17T17:54:00Z",
      "endTime": "2026-02-17T17:55:00Z",
      "steps": {
        "countSum": "85"
      }
    },
...
  ]
}

Daten für einen oder mehrere Tage zusammenfassen

Der dailyRollUp-Endpunkt sollte verwendet werden, wenn Sie Daten für einen einzelnen Tag oder mehrere Tage, auch windowSize genannt, zusammenfassen möchten. Geben Sie im Anfragetext den zivilen Zeitraum für das erforderliche Intervall an, der auf der linken Seite geschlossen und auf der rechten Seite offen ist. Je nach Datentyp erhalten Sie entweder die Summe oder den Durchschnitt über das Intervall.

Beispiel:

Anfrage

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
}

Antwort

{
  "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"
      }
    }
  ]
}

Bucketing, wenn der Bereich kein Vielfaches der Fenstergröße ist

Wenn der angeforderte Bereich kein genaues Vielfaches von windowSize (oder windowSizeDays) ist, wird der letzte Bucket chronologisch am oberen Endpunkt des Bereichs abgeschnitten und umfasst einen Zeitraum, der kürzer als die Fenstergröße ist. Die API akzeptiert Ihre Anfrage ohne Änderungen und führt keine Rundungen, Zeitverschiebungen oder Dateninterpolationen durch.

Um den gesamten angeforderten Bereich abzudecken, wird die Gesamtzahl der Aggregationszeiträume mit der Deckenfunktion berechnet:

Number of windows = ceiling(Range duration / Window size)

Jeder Bucket beginnt sequenziell am Anfang Ihres Bereichs. Wenn das Hinzufügen eines weiteren Fensters in voller Größe über den angeforderten Endzeitpunkt hinausgehen würde, wird das letzte Fenster am Ende des Zeitraums abgeschnitten.

So funktioniert die Bucket-Erstellung

Wenn Sie Rollups mit nicht teilbaren Bereichen anfordern, gelten in der API die folgenden Regeln:

  • Die Einteilung in Buckets beginnt am Anfang des angeforderten Zeitraums (range.startTime oder range.start) und wird in Schritten entsprechend der Fenstergröße (windowSize oder windowSizeDays) fortgesetzt.
  • Der letzte chronologische Bucket wird am Ende des angeforderten Zeitraums (range.endTime oder range.end) begrenzt. Er umfasst also einen kürzeren Zeitraum als die angeforderte Fenstergröße.
  • Die zurückgegebenen RollupDataPoint- oder DailyRollupDataPoint-Objekte enthalten explizit eigene Start- und End-Zeitstempel, mit denen Sie die tatsächliche Dauer des gekürzten Bucket prüfen können.
  • Da die API zusammengefasste Daten in umgekehrt chronologischer Reihenfolge zurückgibt (neueste zuerst), wird der letzte chronologische Bucket (der abgeschnittene) als erstes Element (index 0) in der zurückgegebenen Liste angezeigt.

Szenario: 12-minütiger Bereich mit einem 5-minütigen Zeitfenster

Angenommen, ein Kunde fordert einen Rollup für einen Zeitraum von 12 Minuten mit einem windowSize von 5 Minuten an:

  • range.startTime: 10:00:00
  • range.endTime: 10:12:00 (Gesamtdauer: 12 Minuten)
  • windowSize: 5 minutes

Da 12 Minuten kein Vielfaches von 5 Minuten ist (12 = 5 * 2 + 2), akzeptiert die API die Anfrage und berechnet die Anzahl der Zeitfenster als ceiling(12 / 5) = 3.

Daraus ergeben sich die folgenden drei chronologischen Gruppen:

  1. Bucket 1:[10:00:00, 10:05:00) – Dauer: 5 Minuten (gesamtes Zeitfenster)
  2. Bucket 2:[10:05:00, 10:10:00) – Dauer: 5 Minuten (gesamtes Fenster)
  3. Bucket 3 (gekürzt): [10:10:00, 10:12:00) – Dauer: 2 Minuten (gekürzt bei range.endTime)

Auswirkungen auf aggregierte Werte

Da das endgültige Zeitfenster kürzer ist, sind additive Messwerte (z. B. die Summe oder Anzahl der Schritte) im gekürzten Bucket allein aufgrund des kürzeren Zeitraums niedriger.

Wenn ein Nutzer während des gesamten 12‑Minuten-Zeitraums mit einem gleichmäßigen Tempo von 100 Schritten pro Minute geht:

  • Bucket 1 (10:00–10:05): 500 Schritte (5 Minuten × 100 Schritte/Minute)
  • Bucket 2 (10:05–10:10): 500 Schritte (5 Minuten × 100 Schritte/Minute)
  • Bucket 3 (10:10–10:12): 200 Schritte (2 Minuten × 100 Schritte/Minute)

Beispiel für eine API-Antwort mit Sortierung

Da die API Ergebnisse in umgekehrt chronologischer Reihenfolge zurückgibt, wird der gekürzte Bucket als erstes Element in der zurückgegebenen Liste angezeigt:

{
  "rollupDataPoints": [
    {
      "startTime": "2026-08-20T10:10:00Z",
      "endTime": "2026-08-20T10:12:00Z",
      "steps": {
        "countSum": "200"
      }
    },
    {
      "startTime": "2026-08-20T10:05:00Z",
      "endTime": "2026-08-20T10:10:00Z",
      "steps": {
        "countSum": "500"
      }
    },
    {
      "startTime": "2026-08-20T10:00:00Z",
      "endTime": "2026-08-20T10:05:00Z",
      "steps": {
        "countSum": "500"
      }
    }
  ]
}

Größe des Rollup-Fensters und zugrunde liegende Speicherauflösung

Der rollUp-Endpunkt akzeptiert zwar jedes windowSize von mindestens 1 Sekunde, aber für verschiedene Datentypen werden Messungen mit unterschiedlichen Samplingraten oder Intervalllängen im zugrunde liegenden Speicher aufgezeichnet und beibehalten. Beispielsweise werden Messwerte für körperliche Aktivität, die von Wearables erfasst werden, wie steps, distance, active-minutes und active-energy-burned, in der Regel in 1-Minuten-Intervallen (60s) aufgezeichnet.

Beim Aggregieren von Intervalldatentypen platziert der rollUp-Endpunkt jeden aufgezeichneten Datenpunkt in den Bucket, der die startTime des Datenpunkts enthält. Die API unterteilt, interpoliert oder verteilt Intervall-Daten nicht auf Unterintervall-Buckets.

Wenn Sie ein windowSize angeben, das kleiner als das zugrunde liegende Datenspeicherintervall ist (z. B. wenn Sie ein 10-Sekunden-Fenster für steps anfordern, das in 1-Minuten-Intervallen gespeichert wird):

  1. Der erste Unter-Bucket, der dem startTime des Intervalls entspricht (z. B. 10:00:00 bis 10:00:10), erhält die gesamte kumulierte Anzahl der Minute (z. B. alle 100 Schritte, die in dieser Minute aufgezeichnet wurden).
  2. Die verbleibenden Unter-Buckets innerhalb derselben Minute (10:00:10 bis 10:00:20, 10:00:20 bis 10:00:30 usw.) enthalten keine Datenpunkte, da in diesen Zeiträumen kein Intervall beginnt.

Das führt zu „spitzenartigen“ Daten, bei denen der Wert des gesamten Intervalls im ersten untergeordneten Fenster konzentriert ist.

Damit Sie gleichmäßig verteilte und aussagekräftige Aggregate erhalten, legen Sie windowSize immer auf eine Dauer fest, die der zugrunde liegenden Speicherauflösung des Zieldatentyps entspricht oder größer ist (z. B. 60s oder größer für steps). Die Speicherauflösung und das empfohlene Mindestzeitfenster für die Zusammenfassung für jeden Datentyp finden Sie in der Referenz zu Google Health API-Datentypen.

Gesundheitsdaten eines Nutzers aktualisieren

Verwenden Sie den patch-Endpunkt, um die Gesundheitsdaten eines Nutzers zu aktualisieren.

Mit dem patch-Endpunkt wird ein vorhandener Datensatz anhand des in der Anfrage-URL angegebenen Bezeichners aktualisiert. Geben Sie die Kennung eines zuvor eingefügten Datenpunkts an. Die API überschreibt den vorhandenen Datensatz.

Die Intervall-Zeitstempel (startTime und endTime) eines Datenpunkts können auch vom Inhaber des Datensatzes aktualisiert oder von Upstream-Plattformen wie Health Connect übernommen werden. Weitere Informationen zur Unveränderlichkeit von Zeitstempeln finden Sie im Leitfaden zur Datenverwaltung. Ein Beispiel für das Aktualisieren von Intervall-Zeitstempeln finden Sie unter Intervall-Zeitstempel für vorhandene Daten aktualisieren.

Wann sollte der Datenpunkt-Identifier verwendet werden?

Die Datenpunkt-ID ist in den folgenden Szenarien unerlässlich:

  • Gezielte Aktualisierungen:Wenn Sie eine bestimmte Messung aktualisieren möchten, geben Sie die zugehörige ID in der patch-Anfrage an.
  • Löschungen:Wenn Sie die Kennung beibehalten, kann Ihre Anwendung den Datensatz später über den batchDelete-Endpunkt löschen.

Hier ein Beispiel dafür, wie ein Nutzer den Körperfettanteil auf einer Waage namens „HumanScale“ des Unternehmens „Scales R Us“ aktualisiert. Der neue Körperfettwert des Nutzers beträgt am 10.03.2026 20 %:

Anfrage

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
  }
}

Antwort

{
  "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
    }
  }
}

Zeitstempel für vorhandene Daten aktualisieren

Wenn Sie die Intervall-Zeitstempel (startTime und endTime in REST-JSON-Nutzlasten oder start_time und end_time in gRPC) eines vorhandenen Datenpunkts aktualisieren möchten, senden Sie eine PATCH-Anfrage an den Ressourcen-URI des Datenpunkts. Nur der ursprüngliche Ersteller oder Inhaber eines Datensatzes kann seine Felder ändern. Anwendungen können keine Datenpunkte bearbeiten, die sie nicht selbst erstellt haben.

Hintergrundinformationen zur Unveränderlichkeit von Zeitstempeln, Upstream-Updates von Health Connect und Auswirkungen des Caching finden Sie im Leitfaden zur Datenverwaltung.

Im folgenden Beispiel wird gezeigt, wie eine Inhaber-App die Zeitstempel für Intervalle eines vorhandenen Hydrierungsprotokolls über den patch-Endpunkt aktualisiert:

Anfrage

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
    }
  }
}

Antwort

{
  "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
      }
    }
  }
}

Lebensmittel protokollieren

Wenn Sie ein Lebensmittel protokollieren möchten, senden Sie eine POST-Anfrage an den Endpunkt nutrition-log dataPoints. Der Anfragetext enthält ein DataPoint-Objekt mit einem nutritionLog-Objekt. Weitere Informationen finden Sie im Ernährungsleitfaden.

Beispiel:

Anfrage

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
    }
  }
}

Antwort

{
  "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"
    }
  }
}

Gesundheitsdaten von Nutzern löschen

Verwende die Methode batchDelete, um ein Array mit Fitbit App-Daten eines Nutzers zu löschen.

Hier ist ein Beispiel dafür, wie ein Nutzer seinen Körperfettanteil löschen kann, den er zuvor auf einer Waage aufgezeichnet hat. user-id und data-point-id aus der ursprünglichen Einfügeaktion verwenden:

Anfrage

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"
  ]
}

Antwort

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

Geräteinformationen finden

Verwenden Sie den list-Endpunkt, um die Liste der Geräte abzurufen, die mit dem Konto eines Nutzers gekoppelt sind. Dazu gehören die Modellinformationen des Geräts (deviceVersion) und der Zeitpunkt der letzten Synchronisierung mit der Google Health App (lastSyncTime).

Die Listenkonfiguration und die Synchronisierungsinformationen sind nützlich, um Synchronisierungsprobleme zu beheben oder Verlaufsdaten seit der letzten Synchronisierung abzurufen.

Beispiel:

Anfrage

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

Antwort

{
  "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"
      ]
    }
  ]
}

Verlaufsdaten abfragen

Einer der Hauptvorteile der Google Health API ist die Möglichkeit, die Leistung eines Nutzers zu verfolgen und seine Vitalparameter über einen längeren Zeitraum zu überwachen. Sie können die Daten eines Nutzers abfragen, die bis zum Zeitpunkt der Aufzeichnung zurückreichen. Die API unterliegt keinen Einschränkungen hinsichtlich der Menge an Verlaufsdaten, die Ihre Anwendung nutzen kann.

Für das Abfragen von Verlaufsdaten gelten jedoch weiterhin die standardmäßigen Ratenbeschränkungen. Um die Systemstabilität zu gewährleisten und übermäßige Nutzlasten zu vermeiden, verwendet die Google Health API die automatische Paginierung mit endpunktspezifischen Seitengrößen. Beachten Sie die folgenden Grenzen und Verhaltensweisen:

  • Automatische Paginierung:Wenn Sie einen langen Zeitraum abfragen, gibt die API nur die erste Seite der Ergebnisse bis zur maximalen Seitengröße für diesen Endpunkt zurück, zusammen mit einem nextPageToken. Sie müssen nextPageToken verwenden, um nachfolgende Seiten anzufordern.
  • Variable Seitengrößen:Die Obergrenzen hängen vom Endpunkt und Datentyp ab. Bei den meisten Datentypen ist die Seitengröße auf maximal 10.000 begrenzt. Bei bestimmten Datentypen wie exercise und sleep ist die Standard- und maximale Seitengröße jedoch auf 25 begrenzt. Wenn ein Client beispielsweise alle Schlafdaten der letzten zehn Jahre anfordert, gibt die API auf der ersten Seite trotzdem nur 25 Schlafsitzungen zurück.
  • Einschränkungen für den Rollup-Zeitraum:Für Endpunkte für Daten-Rollup und ‑Aggregation (z. B. rollUp und dailyRollUp) sind Abfragezeiträume je nach Datentyp eingeschränkt:
    • Ein maximaler Zeitraum von 14 Tagen für calories-in-heart-rate-zone, heart-rate, active-minutes und total-calories.
    • Ein maximaler Zeitraum von 90 Tagen für alle anderen Rollup-Datentypen.

Je nach Menge der Verlaufsdaten, die Ihre Anwendung benötigt, müssen Sie die Seiten sequenziell durchlaufen, um das gesamte Dataset abzurufen. Berücksichtigen Sie dies beim Entwerfen des Datensynchronisierungsprozesses Ihrer Anwendung.

Damit Sie eine optimale Leistung erzielen und API-Fehler vermeiden, sollten Sie beim Abfragen von Verlaufsdaten die folgenden Richtlinien beachten:

Phasensynchronisierung von Daten (aktive und selten genutzte Daten)

  • Erster „Hot“-Load:Während der primären Ladesequenz werden nur die Daten der letzten 7–14 Tage abgerufen und gerendert. So können Nutzer Daten sofort sehen, ohne auf zeitaufwendige Abfragen warten zu müssen.
  • Kalter Hintergrund-Load:Das Abrufen älterer Verlaufsdaten wird nach dem Rendern der primären Benutzeroberfläche an eine asynchrone Warteschlange mit niedrigerer Priorität oder einen Hintergrundprozess delegiert.

Abfrage-Chunking für die Aggregation

  • Da für Rollup- und tägliche Rollup-Endpunkte ein maximaler Zeitraum gilt (je nach Datentyp 14 oder 90 Tage), müssen Sie umfangreiche Abfragen für historische Aggregationen in kleinere, sequenzielle Intervalle innerhalb dieser Grenzwerte aufteilen.
  • Führen Sie diese untergeordneten Anfragen in Batches oder sequenziell aus, um die Grenzwerte für die Parallelität einzuhalten und gleichmäßige Fortschrittsanzeigen in der Benutzeroberfläche zu erhalten.

Vorab aggregierte Roll-ups nutzen

Stellen Sie Übersichts-Dashboards und Trenddiagramme so um, dass vorab aggregierte Zusammenfassungsendpunkte wie DailyRollUpDataPoints verwendet werden. Dadurch wird der Rechenaufwand im Backend und die Netzwerkübertragungszeit zum Client drastisch reduziert.

Robuste Fehlerbehandlung (intelligente Wiederholungsversuche)

  • Implementieren Sie eine strikte Verarbeitung des exponentiellen Backoffs, wenn Ratenbeschränkungen (429 Too Many Requests) und Server-Gateway-Timeouts (504 Gateway Timeout) auftreten. Versuchen Sie niemals, große, fehlgeschlagene Nutzlasten sofort noch einmal zu senden. Durch sofortige Wiederholungsversuche wird die Überlastung des Backends verstärkt und die Systemleistung verschlechtert.
Zurück
Clientbibliotheken
Weiter
Filter