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 di Google (AIP), in particolare AIP-127 (transcodifica HTTP e gRPC) e da AIP-131 ad 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 vale principalmente per le richieste GET (recupero di una risorsa) o LIST (filtro/paginazione), 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 dell'URL viene mappato a un parametro di query.
  • Ideale per: tipi semplici (stringhe, numeri interi, enum) e campi ripetuti.

Per un elenco dettagliato dei formati dei filtri, dei riferimenti ai campi, delle regole di convalida e degli esempi, consulta la guida ai dati dei filtri.

Esempio di sintassi:

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 è solitamente una rappresentazione JSON della risorsa stessa. In genere utilizzata 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 nel proto è il corpo.
  • Ideale per: oggetti complessi, messaggi nidificati e dati sensibili.

Per linee guida dettagliate sulle dimensioni delle finestre di aggregazione, sulle regole di bucketing e sugli esempi di aggregazione, consulta la guida ai dati aggregati.

Esempio di sintassi:

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

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

Riepilogo delle differenze principali

Funzionalità Parametri di query Corpo della richiesta
Indicazioni per l'AIP Utilizzato per operazioni di ricerca, filtro e lettura. Utilizzato per le operazioni di scrittura.
Visibilità Visibili nella cronologia di navigazione e nei log del server. Nascosto dall'URL.
complessità Limitato a strutture piatte o ripetute. Supporta oggetti JSON con nidificazione profonda.
Codifica Deve essere con codifica 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 un'altra epoca

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à dell'API

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

Ottieni l'ID utente Fitbit o Google

Dopo che un utente ha fornito il consenso dell'utente tramite Google OAuth 2.0, la risposta del token non contiene l'ID utente Fitbit o Google. Chiama l'endpoint getIdentity subito dopo aver scambiato il codice di autorizzazione per recuperare sia legacyUserId sia healthUserId e verifica che l'Account Google dell'utente sia collegato a Google Health. Se l'account non è ancora collegato, getIdentity restituisce 400 Bad Request con il motivo ACCOUNT_NOT_LINKED (consulta Gestisci gli Account Google non collegati).

Ad esempio:

Richiesta

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

Risposta (200 OK)

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

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

Ricevi dati infragiornalieri o dettagliati raccolti nel corso di una giornata

Utilizza l'endpoint list per un tipo di dati specifico per ottenere dati infragiornalieri o dettagliati raccolti nel corso della giornata 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"
}

Ottieni una visualizzazione riconciliata dei dati sugli intervalli

Per recuperare i dati sugli intervalli senza sovrapporre i record o i conflitti tra più dispositivi, chiama l'endpoint reconcile. L'endpoint di riconciliazione deduplica automaticamente gli intervalli sovrapposti tra i batch di sincronizzazione e più dispositivi di registrazione, restituendo uno stream autorevole e continuo adatto per il rendering delle cronologie delle attività e il calcolo delle durate.

Per informazioni sul motivo per cui i dispositivi connessi producono intervalli sovrapposti e un confronto operativo tra list e reconcile, consulta la guida alla gestione dei dati.

L'esempio seguente confronta la risposta di list (che restituisce entrambi i record sovrapposti) con reconcile (che risolve il conflitto restituendo il record autorevole) per un utente con due sessioni di allenamento sovrapposte:

Elenco non elaborato

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

Riconciliato

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

La riconciliazione risolve le sessioni in conflitto deduplicando e selezionando il record autorevole anziché sintetizzare un'unione temporale artificiale (ad esempio da 11:00:00Z a 11:50:00Z). La risposta riconciliata restituisce il punto dati vincente (7797422996486764704) con l'intervallo registrato originale (da 11:20:00Z a 11:50:00Z), preservando l'integrità della telemetria e delle metriche misurate della sessione.

Filtra dati

Per recuperare sottoinsiemi specifici di record di punti dati che corrispondono a criteri come un intervallo di tempo, una data o un'ora di osservazione, utilizza l'endpoint list o reconcile con un parametro filter.

Per linee guida dettagliate, regole di formattazione, errori di convalida ed esempi di query, consulta la guida ai dati dei filtri.

Filtra per famiglia di origini dati

Per isolare o aggregare i dati di tipi specifici di origini (ad esempio, dispositivi indossabili fisici rispetto a voci manuali), utilizza il parametro dataSourceFamily.

Per linee guida dettagliate, famiglie supportate ed esempi di richieste e risposte per reconcile, rollUp e dailyRollUp, consulta Filtra per famiglia di origini dati nella guida Filtra i dati.

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

Filtra 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 al tempo fisico 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/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": ""
}

Filtra e aggrega per famiglia di origini dati

Una famiglia di origini dati è un gruppo logico di origini dati (ad esempio smartwatch, app mobile o voci manuali). Consente di isolare o aggregare i dati di tipi specifici di origini (ad esempio, dispositivi indossabili fisici rispetto a voci manuali).

Gli endpoint reconcile, rollUp e dailyRollUp supportano tutti il parametro dataSourceFamily. Il meccanismo di trasmissione dipende dall'endpoint:

Endpoint (metodo HTTP) Meccanismo
reconcile (GET) Passa dataSourceFamily come parametro di query dell'URL.
rollUp (POST) Passa dataSourceFamily come campo nel corpo della richiesta JSON.
dailyRollUp (POST) Passa dataSourceFamily come campo nel corpo della richiesta JSON.

Famiglie di origini dati supportate

La tabella seguente descrive i valori dataSourceFamily supportati:

Opzione Descrizione
users/me/dataSourceFamilies/all-sources Valore predefinito. Restituisce i punti dati riconciliati in tutte le origini dati proprietari (1P) e di terze parti (3P) registrate. Con questa opzione verranno restituiti i dati delle app di terze parti (ad esempio, passi dello smartwatch + passi dell'app di terze parti + passi dello smartphone + passi manuali).
users/me/dataSourceFamilies/google-wearables Include i dati registrati dai tracker Google e Fitbit (come i tracker indossabili Fitbit e Pixel Watch). Sono esclusi i dati registrati manualmente e i dati stimati dallo smartphone. Utilizza questa opzione quando l'integrazione richiede la telemetria dei sensori non elaborata registrata direttamente dall'hardware indossabile.
users/me/dataSourceFamilies/google-sources Include fonti proprietarie di Google e Fitbit. Sono inclusi i record dei tracker fisici, i dati di Health Connect e le voci manuali registrate tramite app proprietarie (come l'app Fitbit o Google Fit).

Per ottenere uno stream di dati riconciliati da una famiglia di origini dati specifica, chiama l'endpoint reconcile con il parametro di query dataSourceFamily.

Ad esempio, la seguente richiesta GET recupera il sonno registrato dal tracker per il giorno successivo al 03/03/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": ""
}

Per aggregare i punti dati in una finestra di dimensioni specifiche limitata a una determinata famiglia di origini dati, chiama l'endpoint rollUp e passa il campo dataSourceFamily nel corpo della richiesta JSON.

La seguente richiesta POST esegue query sui conteggi dei passi di camminata infragiornalieri a intervalli orari (3600s), aggregati esclusivamente dai dispositivi indossabili:

Richiesta

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

Risposta

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

Per aggregare i punti dati giornalieri per una famiglia di origini specifica, chiama l'endpoint dailyRollUp e passa il campo dataSourceFamily nel corpo della richiesta.

Ad esempio, la seguente richiesta calcola i riepiloghi giornalieri dei passi dell'utente, incluse tutte le origini proprietarie di Google e Fitbit (dispositivi indossabili + voci manuali):

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

Risposta

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

Aggrega i punti dati in un intervallo di tempo

Utilizza l'endpoint rollUp per restituire l'aggregato di punti dati in base a una finestra in secondi (windowSize), in un intervallo datetime nell'ora fisica dell'utente (in UTC).

Quando chiami l'endpoint rollUp, fornisci il corpo della richiesta che rappresenta l'intervallo di tempo chiuso-aperto richiesto range e windowSize (almeno "1s"). Per linee guida dettagliate sui requisiti di windowSize, sull'allineamento della risoluzione dello spazio di archiviazione, sulle regole di bucketing e sugli esempi di richieste e risposte, consulta Aggrega in intervalli di tempo fisici nella guida ai dati aggregati.

Aggrega i dati di un singolo giorno o di più giorni

Utilizza l'endpoint dailyRollUp per aggregare i dati di un singolo giorno o di più giorni (windowSizeDays). Specifica l'ora civile chiusa-aperta range per l'intervallo richiesto nel corpo della richiesta. A seconda del tipo di dati, l'endpoint restituisce la somma o la media per ogni finestra.

Per informazioni dettagliate sul comportamento di aggregazione giornaliera, sulla gestione dell'ora civile, sui limiti degli intervalli per richiesta ed esempi di richieste e risposte, consulta Aggrega i dati in base ai giorni di calendario nella guida ai dati aggregati.

Aggiorna i dati sulla salute di un utente

Utilizza l'endpoint patch per aggiornare i dati sulla salute di un utente.

L'endpoint patch aggiorna un record esistente in base all'identificatore specificato nell'URL della richiesta. Fornisci l'identificatore di un punto dati inserito in precedenza. L'API sovrascrive il record esistente.

I timestamp dell'intervallo di un punto dati (startTime e endTime) possono anche essere aggiornati dal proprietario del record o propagati da piattaforme upstream come Health Connect. Per maggiori dettagli sulla mutabilità dei timestamp, consulta la guida alla gestione dei dati. Per un esempio di aggiornamento dei timestamp degli intervalli, consulta Aggiorna i timestamp degli intervalli per i dati esistenti.

Quando utilizzare l'identificatore del punto dati

L'identificatore del punto dati è essenziale nei seguenti scenari:

  • Aggiornamenti mirati: per aggiornare una misurazione specifica, fornisci il relativo identificatore nella richiesta patch.
  • Eliminazioni: la conservazione dell'identificatore consente alla tua applicazione di eliminare il record in un secondo momento utilizzando l'endpoint batchDelete.

Ecco un esempio in cui un utente aggiorna la lettura del grasso corporeo su una bilancia chiamata "HumanScale " dell'azienda "Scales R Us". La nuova lettura del grasso corporeo dell'utente è del 20% per la data 2026-03-10:

Richiesta

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

Risposta

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

Aggiorna i timestamp degli intervalli per i dati esistenti

Per aggiornare i timestamp dell'intervallo (startTime e endTime nei payload JSON REST o start_time e end_time in gRPC) di un punto dati esistente, invia una richiesta PATCH all'URI della risorsa del punto dati. Solo l'autore o il proprietario originale di un record può modificarne i campi. Le applicazioni non possono modificare i punti dati che non hanno creato.

Per informazioni sulla mutabilità dei timestamp, sugli aggiornamenti upstream da Health Connect e sulle implicazioni della memorizzazione nella cache, consulta la guida alla gestione dei dati.

L'esempio seguente mostra un'applicazione proprietaria che aggiorna i timestamp degli intervalli di un log di idratazione esistente utilizzando l'endpoint patch:

Richiesta

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

Risposta

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

Registra un alimento

Per registrare un alimento, invia una richiesta POST all'endpoint nutrition-log dataPoints. Il corpo della richiesta contiene un DataPoint con un oggetto nutritionLog. Per ulteriori informazioni, consulta la guida alla nutrizione.

Ad esempio:

Richiesta

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

Risposta

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

Elimina i dati sulla salute degli utenti

Utilizza il metodo batchDelete per eliminare un array di dati dell'app Fitbit di un utente.

Ecco un esempio in cui un utente ha registrato in precedenza il proprio grasso corporeo su una bilancia, ma vuole eliminare la registrazione. 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/123456789/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

Risposta

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

Trova le informazioni sul dispositivo

Utilizza l'endpoint list per recuperare l'elenco dei dispositivi accoppiati all'account di un utente. Sono incluse le informazioni sul modello del dispositivo (deviceVersion) e l'ultima volta che si è sincronizzato con l'app mobile Google Health (lastSyncTime).

Le informazioni sulla configurazione e sulla sincronizzazione dell'elenco sono utili per risolvere i problemi di sincronizzazione o per recuperare i dati storici dall'ultima sincronizzazione.

Ad esempio:

Richiesta

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

Risposta

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

Esegui query sui dati storici

Uno dei principali vantaggi 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 fino alla data di registrazione. 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 è comunque regolata dai limiti di frequenza standard. Per gestire la stabilità del sistema e prevenire payload eccessivi, l'API Google Health utilizza l'impaginazione automatica con dimensioni di pagina specifiche per l'endpoint. Tieni presente i seguenti limiti e comportamenti:

  • Impaginazione automatica: se esegui una query su un lungo intervallo di dati, l'API restituirà solo la prima pagina di risultati fino al limite di dimensioni della pagina per quell'endpoint, insieme a un nextPageToken. Devi utilizzare nextPageToken per richiedere le pagine successive.
  • Dimensioni delle pagine variabili: i limiti di limitazione dipendono dall'endpoint e dal tipo di dati. Per la maggior parte dei tipi di dati, le dimensioni delle pagine sono limitate a un massimo di 10.000. Tuttavia, per alcuni tipi di dati come exercise e sleep, la dimensione predefinita e massima della pagina è limitata a 25. Ad esempio, se un client richiede tutti i dati relativi al sonno degli ultimi 10 anni, l'API restituirà comunque solo 25 sessioni di sonno nella prima pagina.
  • Limitazioni relative all'intervallo di date di aggregazione: per gli endpoint di aggregazione e raggruppamento dei dati (come rollUp e dailyRollUp), gli intervalli di date delle query sono limitati in base al tipo di dati:
    • Un intervallo massimo di 14 giorni per calories-in-heart-rate-zone, heart-rate, active-minutes e total-calories.
    • Un intervallo massimo di 90 giorni per tutti gli altri tipi di dati aggregati.

A seconda del volume di dati storici richiesti dalla tua applicazione, il recupero dell'intero set di dati richiederà l'impaginazione sequenziale delle pagine. Tienilo presente quando progetti il processo di sincronizzazione dei dati della tua applicazione.

Per garantire un rendimento ottimale ed evitare errori dell'API, segui queste linee guida quando esegui query sui dati storici:

Sincronizzazione dei dati in fasi (caricamento parziale e completo)

  • Caricamento "hot" iniziale: recupera ed esegui il rendering solo dei dati degli ultimi 7-14 giorni durante la sequenza di caricamento principale. In questo modo, gli utenti visualizzano immediatamente i dati senza dover attendere query di lunga durata.
  • Caricamento "cold" in background: delega il recupero dei dati storici meno recenti a una coda asincrona con priorità inferiore o a un processo in background dopo il rendering della UI principale.

Suddivisione in blocchi delle query per l'aggregazione

  • Poiché gli endpoint di aggregazione e aggregazione giornaliera applicano un limite massimo per l'intervallo di date (14 o 90 giorni a seconda del tipo di dati), devi suddividere le query di aggregazione storiche di grandi dimensioni in intervalli sequenziali più piccoli entro questi limiti.
  • Esegui queste subquery in batch o in sequenza in modo sicuro per rispettare i limiti di contemporaneità e mantenere indicatori di avanzamento della UI costanti.

Sfrutta i rollup pre-aggregati

Ristruttura le dashboard di panoramica e i grafici delle tendenze per utilizzare endpoint di riepilogo pre-aggregati (come DailyRollUpDataPoints). In questo modo, l'overhead di calcolo sul backend e il tempo di trasferimento di rete al client verranno ridotti drasticamente.

Gestione degli errori resiliente (nuovi tentativi intelligenti)

  • Implementa una gestione rigorosa del backoff esponenziale quando si verificano limiti di frequenza (429 Too Many Requests) e timeout del gateway del server (504 Gateway Timeout). Non riprovare mai immediatamente a inviare payload di grandi dimensioni non riusciti. I nuovi tentativi istantanei moltiplicano la congestione del backend e aggravano il degrado del sistema.
Indietro
Librerie client
Avanti
Filtri