Endpunkte

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

REST API-Konventionen

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

Suchparameter

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

  • Platzierung: 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.

Eine detaillierte Liste der Filterformate, Feldreferenzen, Validierungsregeln und Beispiele finden Sie im Leitfaden zum Filtern von Daten.

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 Anfragetext wird verwendet, wenn die Daten den Status einer Ressource ändern oder zu groß für eine URL sind. Der Text ist normalerweise eine JSON-Darstellung der Ressource selbst. Wird normalerweise für die Vorgänge POST, PATCH und PUT verwendet.

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

Ausführliche Richtlinien zu Rollup-Fenstergrößen, Bucketing-Regeln und Aggregationsbeispielen finden Sie im Leitfaden zu aggregierten 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-konformen Update-Methode oder einem PATCH-Vorgang werden beide verwendet. Die URL enthält den Ressourcennamen, der Text die aktualisierten Ressourcendaten und ein Suchparameter (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-Anleitung Wird für Such-, Filter- und Lesevorgänge verwendet. Wird für Schreibvorgänge verwendet.
Sichtbarkeit Sichtbar im Browserverlauf und in Server-Logs. In der URL ausgeblendet.
Komplexität Beschränkt auf flache oder wiederkehrende 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 mit den folgenden Bedingungen:

  • Ein vierstelliges Jahr YYYY
  • Jahreswerte im Bereich von 0000 bis 9999
  • Keine Erzwingung von Einschränkungen für das Startdatum, die sich aus dem ISO-8601-Standard oder einer anderen Epoche ergeben

Header

Für die Ausführung der Google Health API-Endpunkte sind die entsprechenden Header und Zugriffstokens 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 gängiger Google Health API-Aufgaben und Beispiele für jede Aufgabe.

Fitbit- oder Google-Nutzer-ID abrufen

Nachdem ein Nutzer seine Einwilligung über Google OAuth 2.0 erteilt hat, enthält die Tokenantwort nicht die Fitbit- oder Google-Nutzer-ID. Sobald mindestens ein Google Health-Bereich gewährt wurde, rufen Sie sofort nach dem Austausch des Autorisierungscodes den Endpunkt getIdentity auf, um sowohl legacyUserId als auch healthUserId abzurufen und zu prüfen, ob das Google-Konto des Nutzers mit Google Health verknüpft ist. Die alten Fitbit-Tokens bleiben aktiv, bis legacyUserId bestätigt wurde. Wenn das Konto noch nicht verknüpft ist, gibt getIdentity HTTP 400 Bad Request (status: "FAILED_PRECONDITION", ErrorInfo.reason: "ACCOUNT_NOT_LINKED", siehe Nicht verknüpfte Google-Konten verarbeiten) zurück.

Beispiel:

Anfrage

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

Antwort (200 OK)

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

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

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

Verwende den list-Endpunkt für einen bestimmten Datentyp, um Intraday- oder 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"
}

Abgeglichene Ansicht von Intervalldaten abrufen

Wenn du Intervalldaten ohne sich überschneidende Einträge oder Konflikte für verschiedene Geräte abrufen möchtest, rufe den reconcile-Endpunkt auf. Der Abgleichsendpunkt dedupliziert automatisch überlappende 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 Dauern eignet.

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

Im folgenden Beispiel wird die Antwort von list (gibt beide sich überschneidenden Datensätze zurück) mit der von reconcile (löst den Konflikt, indem der maßgebliche 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"
      }
    }
  ]
}

Beim Abgleich werden widersprüchliche Sitzungen aufgelöst, indem Duplikate entfernt und der maßgebliche Datensatz ausgewählt wird, anstatt eine künstliche Zeitunion (z. B. 11:00:00Z bis 11:50:00Z) zu erstellen. Die abgeglichene Antwort gibt den maßgeblichen Datenpunkt (7797422996486764704) mit dem ursprünglich aufgezeichneten Intervall (11:20:00Z bis 11:50:00Z) zurück, wodurch die Integrität der gemessenen Telemetrie und Messwerte dieser Sitzung gewahrt bleibt.

Daten filtern

Wenn Sie bestimmte Teilmengen von Datenpunktdatensätzen abrufen möchten, die Kriterien wie einem Zeitintervall, einem Datum oder einer Beobachtungszeit entsprechen, verwenden Sie den Endpunkt list oder reconcile mit einem filter-Parameter.

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

Nach Datenquellenfamilie filtern

Wenn du Daten von bestimmten Quelltypen isolieren oder aggregieren möchtest (z. B. physische Wearables im Vergleich zu manuellen Einträgen), verwende den Parameter dataSourceFamily.

Ausführliche 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 einem bürgerlichen Startzeitintervall 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 Beispielbeobachtung filtern

Verwenden Sie den Endpunkt list 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). Sie können damit Daten aus bestimmten Arten von Quellen isolieren oder aggregieren (z. B. physische 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 über alle registrierten selbst erhobenen Datenquellen und Drittanbieter-Datenquellen hinweg abgeglichen wurden. Bei dieser Option werden Daten aus Drittanbieter-Apps zurückgegeben (z. B. Schritte von der Smartwatch + Schritte aus der Drittanbieter-App + Schritte vom Smartphone + manuell hinzugefügte Schritte).
users/me/dataSourceFamilies/google-wearables Dazu gehören Daten, die von Google- und Fitbit-Trackern aufgezeichnet wurden (z. B. Fitbit-Wearables und die Pixel Watch). Manuell protokollierte Daten und vom Smartphone geschätzte Daten sind ausgeschlossen. Verwende diese Option, wenn deine Integration Rohsensortelemetrie erfordert, die direkt von Wearable-Hardware aufgezeichnet wird.
users/me/dataSourceFamilies/google-sources Umfasst eigene Google- und Fitbit-Quellen. Dazu gehören Daten von physischen Trackern, Daten von Health Connect und alle manuellen Einträge, die über eigene Apps wie die Fitbit App oder Google Fit erfasst wurden.

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

Mit der folgenden GET-Anfrage werden beispielsweise die vom Tracker aufgezeichneten Schlafdaten 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 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 Intraday-Schrittzahlen in stündlichen Intervallen (3600s) abgefragt, die ausschließlich von Wearables aggregiert werden:

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 aggregieren möchten, rufen Sie den Endpunkt dailyRollUp auf und übergeben Sie das Feld dataSourceFamily im Anfragetext.

In der folgenden Anfrage werden beispielsweise die täglichen Rollups für die Schritte des Nutzers berechnet, einschließlich aller Erstanbieterquellen von Google und Fitbit (Wearables und 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 aggregieren

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

Wenn Sie den Endpunkt rollUp aufrufen, geben Sie den Anfragetext an, der die erforderliche geschlossene/offene Zeit range und windowSize (mindestens "1s") darstellt. Detaillierte Richtlinien zu den Anforderungen für windowSize, zur Ausrichtung der Speicherauflösung, zu Bucketing-Regeln sowie Beispiele für Anfragen und Antworten finden Sie im Leitfaden zum Aggregieren von Daten unter Über physische Zeitintervalle aggregieren.

Daten für einen einzelnen Tag oder mehrere Tage aggregieren

Verwenden Sie den Endpunkt dailyRollUp, um Daten für einen einzelnen Tag oder mehrere Tage (windowSizeDays) zu aggregieren. Geben Sie im Anfragetext die geschlossene/offene bürgerliche Zeit range für das erforderliche Intervall an. Je nach Datentyp gibt der Endpunkt entweder die Summe oder den Durchschnitt für jedes Fenster zurück.

Weitere Informationen zum täglichen Aggregationsverhalten, zur Verarbeitung der bürgerlichen Zeit, zu Bereichsbeschränkungen pro Anfrage sowie Beispiele für Anfragen und Antworten finden Sie im Leitfaden zu aggregierten Daten unter Über Kalendertage hinweg aggregieren.

Gesundheitsdaten eines Nutzers aktualisieren

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

Der Endpunkt patch aktualisiert einen vorhandenen Eintrag anhand der in der Anfrage-URL angegebenen Kennung. Geben Sie die Kennung eines zuvor eingefügten Datenpunkts an. Die API überschreibt den vorhandenen Eintrag und gibt einen synchronen google.longrunning.Operation-Wrapper zurück.

Beim Erstellen (POST) oder Aktualisieren (PATCH) von Datenpunkten erfordern Stichproben-Datentypen (z. B. weight und body-fat) sampleTime.utcOffset, während Intervall-Datentypen (z. B. steps, sleep und exercise) interval.startUtcOffset und interval.endUtcOffset erfordern. Geben Sie diese Offsets als Dauer in Sekunden relativ zu UTC an, z. B. "-14400s" für UTC-4 oder "3600s" für UTC+1.

PATCH kann nicht zum Erstellen neuer Einträge verwendet werden. Wenn Sie einen neuen Eintrag einfügen möchten, finden Sie unter Lebensmittel protokollieren ein Beispiel für die Verwendung der Methode POST.

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

Wann die Datenpunkt-ID verwendet werden sollte

Die Datenpunkt-ID ist in den folgenden Szenarien wichtig:

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

Hier ist ein Beispiel, in dem ein Nutzer seinen Körperfettwert 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",
      "utcOffset": "-14400s"
    },
    "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",
        "utcOffset": "-14400s"
      },
      "percentage": 20
    }
  }
}

Intervallzeitstempel für vorhandene Daten aktualisieren

Wenn Sie die Intervallzeitstempel (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 erstellt haben.

Hintergrundinformationen zur Veränderbarkeit von Zeitstempeln, zu Upstream-Updates von Health Connect und zu den Auswirkungen des Cachings findest du im Leitfaden zum Datenmanagement.

Im folgenden Beispiel wird gezeigt, wie eine Inhaber-App die Intervallzeitstempel eines vorhandenen Flüssigkeitsaufnahmeprotokolls über den Endpunkt patch 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",
      "startUtcOffset": "-14400s",
      "endTime": "2026-09-03T10:19:59Z",
      "endUtcOffset": "-14400s"
    },
    "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",
        "startUtcOffset": "-14400s",
        "endTime": "2026-09-03T10:19:59Z",
        "endUtcOffset": "-14400s",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 6,
            "minutes": 5
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 6,
            "minutes": 19,
            "seconds": 59
          }
        }
      },
      "amountConsumed": {
        "milliliters": 350
      }
    }
  }
}

Lebensmittel protokollieren

Wenn du ein Lebensmittel protokollieren möchtest, sende eine POST-Anfrage an den nutrition-log-Endpunkt dataPoints. Der Anfragetext enthält ein DataPoint mit einem nutritionLog-Objekt. Weitere Informationen findest du im Leitfaden zur Ernährung.

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",
      "startUtcOffset": "3600s",
      "endTime": "2026-06-16T12:30:00Z",
      "endUtcOffset": "3600s"
    },
    "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": "3600s",
        "endTime": "2026-06-16T12:30:00Z",
        "endUtcOffset": "3600s"
      },
      "energy": {
        "kcal": 105
      },
      "totalCarbohydrate": {
        "grams": 27
      },
      "totalFat": {
        "grams": 0.3
      },
      "mealType": "LUNCH",
      "foodDisplayName": "Banana"
    }
  }
}

Gesundheitsdaten von Nutzern löschen

Verwenden Sie die Methode batchDelete mit {"names": [...]}, um ein Array von Datenpunkten eines Nutzers zu löschen. Es gibt keine HTTP-DELETE-Methode für Datenpunkte und batchDelete gibt einen synchronen google.longrunning.Operation-Wrapper zurück.

Hier ist ein Beispiel, bei dem ein Nutzer zuvor seinen Körperfettanteil auf einer Waage aufgezeichnet hat, den Eintrag aber löschen möchte. Verwenden Sie die user-id und die data-point-id aus der ursprünglichen Einfügeaktion:

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

Verwende 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 mobilen 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 Vitalwerte über einen längeren Zeitraum zu überwachen. Sie können die Daten eines Nutzers so weit zurück abfragen, wie sie aufgezeichnet wurden. Die API legt keine Beschränkungen für die Menge an Verlaufsdaten fest, die Ihre Anwendung nutzen kann.

Für das Abfragen von Verlaufsdaten unterliegt jedoch weiterhin den standardmäßigen Ratenbegrenzungen. Um die Systemstabilität zu gewährleisten und übermäßige Nutzlasten zu vermeiden, verwendet die Google Health API eine 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 Ergebnisseite bis zur maximalen Seitengröße für diesen Endpunkt zurück, zusammen mit einem nextPageToken. Sie müssen das 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 10 Jahre anfordert, gibt die API auf der ersten Seite trotzdem nur 25 Schlafeinheiten zurück.
  • Einschränkungen für den Zeitraum der Zusammenfassung: Für Endpunkte zur Datenzusammenfassung und -aggregation (z. B. rollUp und dailyRollUp) sind die Zeiträume für Abfragen je nach Datentyp eingeschränkt:
    • Ein maximaler Bereich 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 Umfang der Verlaufsdaten, die Ihre Anwendung benötigt, müssen Sie zum Abrufen des gesamten Datasets die Seiten nacheinander durchgehen. Berücksichtigen Sie dies beim Entwerfen des Datensynchronisierungsprozesses Ihrer Anwendung.

Beachten Sie die folgenden Richtlinien, wenn Sie Verlaufsdaten abfragen, um eine optimale Leistung zu erzielen und API-Fehler zu vermeiden:

Phasenweise Datensynchronisierung (warmes versus kaltes Laden)

  • Erstes „Hot“-Laden: Ruft nur die Daten der letzten 7–14 Tage ab und rendert sie während der primären Ladesequenz. So sehen Nutzer die Daten sofort, ohne auf langwierige Abfragen warten zu müssen.
  • „Kaltes“ Laden im Hintergrund: Delegieren Sie das Abrufen älterer Verlaufsdaten an eine asynchrone Warteschlange mit niedrigerer Priorität oder einen Hintergrundprozess, nachdem die primäre Benutzeroberfläche gerendert wurde.

Abfrage-Chunking für die Aggregation

  • Da für Rollup- und tägliche Rollup-Endpunkte ein maximales Datumsbereichslimit gilt (14 oder 90 Tage, je nach Datentyp), müssen Sie große historische Aggregationsabfragen in kleinere, aufeinanderfolgende Intervalle innerhalb dieser Limits aufteilen.
  • Fassen Sie diese Unterabfragen sicher in Batches oder Sequenzen zusammen, um die Limits für die Gleichzeitigkeit einzuhalten und die Fortschrittsanzeigen der Benutzeroberfläche stabil zu halten.

Vorab aggregierte Roll-ups nutzen

Strukturieren Sie Übersichts-Dashboards und Trenddiagramme so um, dass voraggregierte Zusammenfassungsendpunkte (z. B. DailyRollUpDataPoints) verwendet werden. Dadurch werden der Rechenaufwand im Backend und die Netzwerkübertragungszeit zum Client drastisch reduziert.

Ausfallsichere Fehlerbehandlung (intelligente Wiederholungsversuche)

  • Implementieren Sie eine strikte exponentielle Backoff-Verarbeitung, wenn Ratenbegrenzungen (429 Too Many Requests) und Server-Gateway-Zeitüberschreitungen (504 Gateway Timeout) auftreten. Wiederholen Sie große, fehlgeschlagene Nutzlasten nie sofort. Sofortige Wiederholungsversuche vervielfachen die Backend-Überlastung und verschlimmern die Systemverschlechterung.