Endpoint

Questa pagina fornisce una panoramica delle convenzioni dell'API REST, insieme a un indice delle attività comuni dell'API Google Health ed esempi di ciascuna.

Convenzioni delle API REST

L'API Google Health segue gli standard delle proposte di miglioramento delle API Google (AIP), in particolare AIP-127 (transcodifica HTTP e gRPC) e AIP-131-AIP-135 (metodi standard). Questi standard definiscono il modo in cui i dati vengono mappati da un messaggio proto a una richiesta HTTP.

Parametri di query

I parametri di query vengono utilizzati quando i dati fanno parte dell'URL. Questo valore è principalmente per le richieste GET (recupero di una risorsa) o LIST (filtraggio/impaginazione), ma viene utilizzato anche per le operazioni DELETE.

  • Posizionamento: aggiunto all'URL dopo un ?.
  • Sintassi: coppie chiave-valore separate da &.
  • Mappatura: ogni campo nel messaggio di richiesta che non fa parte del modello di percorso URL viene mappato a un parametro di query.
  • Ideale per: tipi semplici (stringhe, numeri interi, enumerazioni) e campi ripetuti.

Sintassi di esempio:

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"

Corpo della richiesta

Il corpo della richiesta viene utilizzato quando i dati modificano lo stato di una risorsa o sono troppo grandi per un URL. Il corpo è in genere una rappresentazione JSON della risorsa stessa. In genere utilizzato per le operazioni POST, PATCH e PUT.

  • Posizionamento: all'interno del payload HTTP (non visibile nell'URL).
  • Sintassi: formattato come oggetto JSON.
  • Mappatura: definita nell'annotazione google.api.http.
    • body: "*" significa che l'intero messaggio è il corpo.
    • body: "resource_name" indica che solo un campo specifico del proto è il corpo.
  • Ideale per: oggetti complessi, messaggi nidificati e dati sensibili.

Sintassi di esempio:

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

Lo scenario ibrido

In un metodo Update conforme ad AIP-134 o in un'operazione PATCH, vengono utilizzati entrambi. L'URL contiene il nome della risorsa, il corpo contiene i dati della risorsa aggiornati e un parametro di query (di solito update_mask) specifica i campi da modificare.

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

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

Differenze principali in sintesi

Funzionalità Parametri di query Corpo della richiesta
Indicazioni AIP Utilizzato per le operazioni di ricerca, filtro e lettura. Utilizzato per le operazioni di scrittura.
Visibilità Visibile nella cronologia del browser e nei log del server. Nascosto nell'URL.
complessità Limitato a strutture piatte o ripetute. Supporta oggetti JSON nidificati in profondità.
Codifica Deve essere codificato nell'URL (ad esempio, gli spazi diventano %20). Codifica JSON standard.

Date

Tutte le date nell'API Google Health vengono visualizzate nel formato YYYY-MM-DD. L'API Nutrition supporta lo standard ISO-8601 per i valori di data con le seguenti condizioni:

  • Un anno a 4 cifre YYYY
  • Valori dell'anno compresi nell'intervallo 0000-9999
  • Nessuna applicazione delle limitazioni della data di inizio implicite nello standard ISO-8601 o in altre epoche

Intestazioni

L'esecuzione degli endpoint dell'API Google Health richiede l'utilizzo delle intestazioni e del token di accesso appropriati. Per le richieste GET e POST è consigliata la seguente intestazione:

Authorization: Bearer access-token
Accept: application/json

Indice delle attività API

Questa sezione fornisce un indice delle attività comuni dell'API Google Health ed esempi di ciascuna.

Ottenere l'ID utente Fitbit o Google

Dopo che un utente ha dato il consenso tramite Google OAuth 2.0, la risposta del token non contiene l'ID utente Fitbit o Google. Per ottenere l'ID utente, chiama l'endpoint getIdentity. getIdentity restituisce sia l'ID utente Fitbit legacy sia l'ID utente Google.

Ti consigliamo di chiamare l'endpoint getIdentity e memorizzare entrambi gli ID utente non appena un nuovo utente fornisce il consenso tramite OAuth. Ciò garantisce la compatibilità con le versioni precedenti e future dell'integrazione.

Ad esempio:

Richiesta

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

Risposta

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

Visualizzare dati intragiornalieri o dettagliati raccolti durante una giornata

Utilizza l'endpoint list per un tipo di dati specifico per ottenere dati intraday o dettagliati raccolti durante il giorno negli intervalli supportati per quel tipo di dati.

Ad esempio:

Richiesta

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

Risposta

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

Filtra i dati in base all'ora di inizio civile di un intervallo

Utilizza l'endpoint list con un parametro filter per filtrare i dati in base all'ora civile o a un intervallo.

Ad esempio:

Richiesta

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

Risposta

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

Filtrare i dati in base all'ora fisica di un'osservazione di esempio

Utilizza l'endpoint list con un parametro filter per filtrare i dati in base all'ora fisica di osservazione del campione.

Ad esempio:

Richiesta

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

Risposta

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

Filtrare i dati in base a origini dati come i dispositivi indossabili

Utilizza l'endpoint reconcileper ottenere i dati di una "famiglia di origini dati" in uno stream riconciliato.

Ecco un esempio di filtro del sonno registrato dal tracker solo per il giorno successivo al 3 marzo 2026:

Richiesta

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

Risposta

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

Aggrega i punti dati in un intervallo di tempo

Utilizza l'endpoint rollUpper restituire l'aggregazione dei punti dati in base a una finestra in secondi, nell'intervallo datetime in base all'ora fisica degli utenti (in UTC).

Quando chiami l'endpoint rollUp, devi fornire il corpo della richiesta che rappresenta l'intervallo di date richiesto nell'ora civile dell'utente. Ad esempio:

Richiesta

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

Risposta

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

Aggrega i dati per un singolo giorno o più giorni

L'endpoint dailyRollUp deve essere utilizzato quando vuoi aggregare i dati in un singolo giorno o in più giorni, noto come windowSize. Fornisci l'intervallo di tempo civile chiuso-aperto per l'intervallo richiesto nel corpo della richiesta. A seconda del tipo di dati, riceverai la somma o la media nell'intervallo.

Ad esempio:

Richiesta

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
}

Risposta

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

Inserire o aggiornare i dati sulla salute di un utente

Utilizza l'endpoint patch per inserire o aggiornare i dati dell'app Fitbit di un utente.

Ecco un esempio in cui un utente ha registrato la propria percentuale di grasso corporeo su una bilancia chiamata "HumanScale" della società "Scales R Us". La nuova misurazione della percentuale di grasso corporeo dell'utente è 20% per la data 10/03/2026.

Richiesta

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

Risposta

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

Eliminare i dati sanitari dell'utente

Utilizza l'endpoint batchDelete per eliminare un array di dati dell'app Fitbit di un utente.

Ecco un esempio in cui un utente ha registrato in precedenza la propria percentuale di grasso corporeo su una bilancia, ma vuole eliminare il record. Utilizzando user-id e data-point-id dell'azione di inserimento originale:

Richiesta

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

Risposta

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

Eseguire query sui dati storici

Uno dei vantaggi principali dell'API Google Health è la possibilità di monitorare le prestazioni di un utente e i suoi parametri vitali per lunghi periodi di tempo. Puoi eseguire query sui dati di un utente a partire dal momento in cui sono stati registrati. L'API non impone limitazioni o restrizioni alla quantità di dati storici che la tua applicazione può utilizzare.

Tuttavia, l'esecuzione di query sui dati storici è ancora regolata dai limiti di frequenza standard. Per ridurre il numero di chiamate API rispetto a questi limiti, l'API Google Health supporta l'esecuzione di query sui dati in un intervallo di date. Tieni presente i seguenti limiti di paginazione e richieste:

  • Ogni endpoint restituisce una dimensione massima della pagina di 10.000 punti dati per pagina.
  • Gli intervalli di date delle query sono limitati a un periodo compreso tra 14 e 90 giorni per richiesta.

A seconda del volume di dati storici di cui ha bisogno la tua applicazione, il recupero dell'intero set di dati potrebbe richiedere più richieste sequenziali e richiedere più tempo. Tienilo presente quando progetti la procedura di sincronizzazione dei dati della tua applicazione.