Développer des expériences de sommeil avec l'API Google Health

L'API Google Health fournit des types de données qui suivent les habitudes de sommeil d'un utilisateur, y compris la durée, la qualité et les métriques physiologiques pendant le repos. Ces métriques aident les applications à fournir des informations sur la récupération, l'hygiène du sommeil et les tendances de santé à long terme.

Les métriques physiologiques telles que la variabilité de la fréquence cardiaque (VFC), la saturation en oxygène (SpO2) et la fréquence respiratoire sont enregistrées spécifiquement pendant le sommeil, car le corps est dans un état stable et au repos. Cela permet à l'API de capturer une base de référence de la santé autonome et respiratoire de l'utilisateur sans l'interférence des facteurs de stress diurnes, de l'activité physique ou des conditions environnementales variables.

Comprendre les différences entre ces types de données vous aidera à déterminer les métriques qui conviennent à votre application.

Types de données acceptés

L'API est compatible avec les types de données suivants pour mesurer le sommeil :

Tableau : Types de données de sommeil de l'API Google Health
Type de données Opérations
disponibles		 Champ d'application
Variabilité quotidienne de la fréquence cardiaque
dataType : daily-heart-rate-variability
filter parameter : daily_heart_rate_variability
Type d'enregistrement  : "Tous les jours"

Appareils compatibles
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Saturation en oxygène quotidienne
dataType : daily-oxygen-saturation
filter parameter : daily_oxygen_saturation
Type d'enregistrement  : "Tous les jours"

Appareils compatibles
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Fréquence respiratoire quotidienne
dataType : daily-respiratory-rate
filter parameter : daily_respiratory_rate
Type d'enregistrement  : "Tous les jours"

Appareils compatibles
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Dérivations quotidiennes de la température de sommeil
dataType : daily-sleep-temperature-derivations
filter parameter : daily_sleep_temperature_derivations
Type d'enregistrement  : "Tous les jours"

Appareils compatibles
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Variabilité de la fréquence cardiaque
dataType : heart-rate-variability
filter parameter : heart_rate_variability
Type d'enregistrement  : Exemple

Appareils compatibles
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Saturation en oxygène
dataType : oxygen-saturation
filter parameter : oxygen_saturation
Type d'enregistrement  : Exemple

Appareils compatibles
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Résumé du sommeil avec la fréquence respiratoire
dataType : respiratory-rate-sleep-summary
filter parameter : respiratory_rate_sleep_summary
Type d'enregistrement  : Exemple

Appareils compatibles
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Sommeil
dataType : sleep
filter parameter : sleep
Type d'enregistrement  : session

Appareils compatibles
list, get, reconcile, create, update, batchDelete .sleep.readonly
.sleep.writeonly

Périodes de sommeil et brefs éveils

Une session de sommeil (Sleep) représente un événement de sommeil distinct, comme une nuit de sommeil ou une sieste. Il inclut une répartition détaillée des phases de sommeil non chevauchantes, ainsi que de brefs intervalles de transition vers l'éveil appelés "éveils brefs".

  • Session de sommeil (Sleep) : représente un événement de sommeil discret (intervalles de phases LIGHT, DEEP, REM et AWAKE) qui partitionne la chronologie continue du repos principal.
  • Éveils brefs (shortAwakenings) : brèves transitions ou éveils qui se produisent pendant le repos. Contrairement aux intervalles de phases AWAKE standards (qui divisent la progression des phases de sommeil contiguës et non chevauchantes), les brefs éveils sont des segments distincts qui peuvent se chevaucher avec les phases de sommeil environnantes. Elles offrent une visibilité précise sur l'agitation et les micro-éveils sans perturber la structure principale des phases de sommeil.
  • Éveils nocturnes : les éveils en milieu de nuit (par exemple, se lever pour boire de l'eau) sont identifiés par la fusion des capteurs sur l'appareil (accéléromètre, gyroscope et nombre de pas). Dans l'API Web, les applications peuvent détecter les éveils nocturnes en filtrant les intervalles marqués avec le niveau "wake" (sommeil classique) ou "awake" (sommeil par phases).

Exemple

{
  "name": "sleeps/12345",
  "startTime": "2026-04-20T22:30:00Z",
  "endTime": "2026-04-21T06:30:00Z",
  "sleepType": "STAGES",
  "minutesToFallAsleep": 15,
  "minutesAfterWakeup": 10,
  "sleepStages": [
    {
      "startTime": "2026-04-20T22:30:00Z",
      "endTime": "2026-04-20T23:45:00Z",
      "type": "LIGHT"
    },
    {
      "startTime": "2026-04-20T23:45:00Z",
      "endTime": "2026-04-21T01:15:00Z",
      "type": "DEEP"
    }
  ],
  "shortAwakenings": [
    {
      "startTime": "2026-04-20T23:10:00Z",
      "endTime": "2026-04-20T23:11:30Z",
      "type": "AWAKE"
    }
  ]
}

Créer une période de sommeil

Pour créer une entrée de période de sommeil, envoyez une requête POST au point de terminaison des points de données sleep. La réponse inclut le champ name contenant le data-point-id, qui peut être utilisé dans une requête Update (Patch) ou Delete.

Requête

POST https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "sleep": {
    "interval": {
      "startTime": "2026-06-07T22:00:00Z",
      "startUtcOffset": "-14400s",
      "endTime": "2026-06-08T06:00:00Z",
      "endUtcOffset": "-14400s"
    },
    "type": "STAGES",
    "stages": [
      {
        "startTime": "2026-06-07T22:00:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-07T22:30:00Z",
        "endUtcOffset": "-14400s",
        "type": "LIGHT"
      },
      {
        "startTime": "2026-06-07T22:30:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-07T23:45:00Z",
        "endUtcOffset": "-14400s",
        "type": "DEEP"
      },
      {
        "startTime": "2026-06-07T23:45:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-08T02:15:00Z",
        "endUtcOffset": "-14400s",
        "type": "LIGHT"
      },
      {
        "startTime": "2026-06-08T02:15:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-08T02:45:00Z",
        "endUtcOffset": "-14400s",
        "type": "REM"
      },
      {
        "startTime": "2026-06-08T02:45:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-08T05:15:00Z",
        "endUtcOffset": "-14400s",
        "type": "LIGHT"
      },
      {
        "startTime": "2026-06-08T05:15:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-08T06:00:00Z",
        "endUtcOffset": "-14400s",
        "type": "REM"
      }
    ]
  }
}

Réponse

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/user-id/dataTypes/sleep/dataPoints/data-point-id",
    "sleep": {
      "interval": {
        "startTime": "2026-06-07T22:00:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-08T06:00:00Z",
        "endUtcOffset": "-14400s"
      },
      "type": "STAGES",
      "stages": [
        {
          "startTime": "2026-06-07T22:00:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-07T22:30:00Z",
          "endUtcOffset": "-14400s",
          "type": "LIGHT"
        },
        {
          "startTime": "2026-06-07T22:30:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-07T23:45:00Z",
          "endUtcOffset": "-14400s",
          "type": "DEEP"
        },
        {
          "startTime": "2026-06-07T23:45:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-08T02:15:00Z",
          "endUtcOffset": "-14400s",
          "type": "LIGHT"
        },
        {
          "startTime": "2026-06-08T02:15:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-08T02:45:00Z",
          "endUtcOffset": "-14400s",
          "type": "REM"
        },
        {
          "startTime": "2026-06-08T02:45:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-08T05:15:00Z",
          "endUtcOffset": "-14400s",
          "type": "LIGHT"
        },
        {
          "startTime": "2026-06-08T05:15:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-08T06:00:00Z",
          "endUtcOffset": "-14400s",
          "type": "REM"
        }
      ]
    }
  }
}

Métriques sur l'efficacité et la latence du sommeil

En plus des phases de sommeil et des métriques physiologiques, l'API fournit des métriques clés qui quantifient la qualité et le début du sommeil. L'efficacité du sommeil et la latence d'endormissement sont des métriques cliniques standards qui décrivent l'efficacité du repos d'un utilisateur par rapport à son temps total passé au lit. Elles fournissent des informations sur l'hygiène du sommeil et le repos.

Score d'efficacité du sommeil

L'efficacité du sommeil est une métrique standard définie comme la proportion de temps passé à dormir par rapport au temps total passé au lit. L'API calcule l'efficacité du sommeil à l'aide de la formule suivante :

Sleep Efficiency Score = round( (Total Minutes Asleep / Total Minutes In Bed) * 100 )

Le score d'efficacité est calculé juste avant la répartition des niveaux de sommeil (phases). Le nombre total de minutes de sommeil renvoyé dans la réponse de l'API (dans le champ summary.minutesAsleep) reflète le résultat final après le calcul des niveaux de sommeil.

Si un utilisateur ou un chercheur modifie manuellement l'heure de début ou de fin d'un journal de sommeil, l'API recalcule le score d'efficacité du sommeil et ajuste les partitions des phases en fonction des données de capteur enregistrées dans les nouvelles limites de l'heure du coucher et de l'heure du réveil.

Latence d'endormissement

La latence d'endormissement mesure le temps écoulé entre le moment où un utilisateur a l'intention de s'endormir (le début de la période "au lit" ou "lumières éteintes") et le moment où il s'endort.

Pour les journaux générés automatiquement à l'aide de la détection automatique (auto_detect), minutesToFallAsleep est défini par défaut sur 0, car aucune intention explicite de s'endormir n'a été enregistrée. Lorsque les heures de début au lit sont enregistrées ou modifiées manuellement (en convertissant le journal en manual), l'API calcule et renseigne minutesToFallAsleep ainsi que minutesAfterWakeup.

Conseils pour la recherche et la journalisation manuelle

Lorsque les participants enregistrent manuellement ou ajustent les heures de début et de fin du temps passé au lit :

  1. La modification des limites du lit change l'intervalle timeInBed.
  2. Les niveaux de sommeil et les partitions de phases s'ajustent automatiquement pour évaluer les données des capteurs dans la nouvelle fenêtre.
  3. Le score d'efficacité du sommeil, minutesToFallAsleep et minutesAfterWakeup, sont recalculés en fonction de la nouvelle fenêtre temporelle.

Dérivations de la température de sommeil quotidienne

Les dérivations quotidiennes de la température pendant le sommeil mesurent la variation de la température cutanée d'un utilisateur pendant le sommeil par rapport à sa température de référence. Ces données sont généralement communiquées une fois par jour après une période de sommeil importante.

Fréquence respiratoire

La fréquence respiratoire mesure le nombre de respirations par minute de l'utilisateur. Pendant le sommeil, il s'agit d'une métrique clé pour surveiller la qualité du sommeil et les perturbations potentielles. L'API est compatible avec la fréquence respiratoire échantillonnée (respiratory-rate), les résumés quotidiens (daily-respiratory-rate) et les résumés du sommeil au niveau de la session (respiratory-rate-sleep-summary).

Variabilité de la fréquence cardiaque (VFC)

La VFC mesure la variation de temps entre deux battements de cœur. Il s'agit d'un indicateur clé de l'état du système nerveux autonome. Une VFC élevée pendant le sommeil signifie généralement une meilleure récupération et une meilleure aptitude, tandis qu'une VFC faible peut indiquer un stress ou un surentraînement. L'API est compatible avec les échantillons de VFC (heart-rate-variability) et les récapitulatifs quotidiens (daily-heart-rate-variability).

Saturation en oxygène (SpO2)

La SpO2 représente le pourcentage d'hémoglobine saturée en oxygène par rapport à la quantité totale d'hémoglobine dans le sang. Il est essentiel de surveiller la SpO2 pendant le sommeil pour détecter d'éventuels troubles respiratoires et s'assurer que l'utilisateur maintient un niveau d'oxygène adéquat tout au long de la nuit. L'API est compatible avec les exemples de SpO2 (oxygen-saturation) et les récapitulatifs quotidiens (daily-oxygen-saturation).

Vue globale de la qualité du sommeil et de la récupération

Bien que chaque métrique fournisse des informations spécifiques, elles sont profondément liées et offrent ensemble une vue holistique de la récupération d'un utilisateur. Les phases de sommeil (léger, profond, paradoxal) constituent la base structurelle du repos, tandis que les marqueurs physiologiques comme la VFC et la SpO2 indiquent comment le corps réagit physiquement à ce repos. Par exemple, une période de sommeil de haute qualité avec une phase de sommeil profond optimale est souvent associée à une VFC plus élevée, ce qui indique une récupération efficace du système nerveux autonome.

En combinant ces données avec les dérivations de la fréquence respiratoire et de la température pendant le sommeil, les applications peuvent identifier les perturbations potentielles. Un pic soudain de la fréquence respiratoire ou une variation de la température du corps pendant le sommeil peuvent expliquer pourquoi un utilisateur a passé moins de temps dans les phases de sommeil réparateur. En analysant ces types de données ensemble, les développeurs peuvent fournir une évaluation complète de l'hygiène du sommeil et des tendances de santé à long terme.

Consignes

Lorsque vous intégrez des métriques de sommeil dans votre application, suivez ces consignes :

  • Détails de la session : pour afficher les phases de sommeil d'un utilisateur (léger, profond, paradoxal, éveillé) et les brefs réveils, interrogez le type de données sleep.
  • Éveils nocturnes : pour suivre les événements d'éveil en milieu de nuit sans flux de capteurs bruts, inspectez les intervalles de l'étape sleep et filtrez les éléments dont le type d'étape est AWAKE (ou wake pour les journaux de sommeil classiques).
  • Latence et efficacité : utilisez minutesToFallAsleep et la formule d'efficacité du sommeil pour analyser la latence du sommeil. Notez que minutesToFallAsleep est renseigné lorsque les journaux de sommeil sont modifiés manuellement ou enregistrés explicitement.
  • Surveillance physiologique : pour une surveillance avancée de la santé, combinez les données de la période de sommeil avec les métriques physiologiques et de récupération telles que respiratory-rate-sleep-summary, daily-sleep-temperature-derivations, daily-heart-rate-variability et daily-oxygen-saturation.
  • Réconciliation : utilisez l'opération reconcile pour vous assurer que les journaux de sommeil qui se chevauchent provenant de différents appareils (par exemple, un wearable et un capteur de matelas) sont fusionnés en un seul enregistrement de sommeil "principal".

Calculer le temps total de sommeil profond

Pour calculer la durée totale pendant laquelle un utilisateur a été en phase de sommeil profond réparateur pour une nuit spécifique :

  1. Interrogez le type de données sleep pour la période spécifiée.
  2. Parcourez la liste des étapes et identifiez les intervalles où type est DEEP.
  3. Calculez la durée (heure de fin - heure de début) de chaque intervalle de sommeil profond et additionnez-les.

La somme obtenue correspond à la durée physique totale du sommeil profond pour cette session.

Précédent
Étapes