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

L'API Google Health fournit des types de données qui permettent de suivre 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 insights 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 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.

Comprenez les différences entre ces types de données pour déterminer les métriques adaptées à votre application.

Types de données acceptés

L'API accepte les types de données suivants pour mesurer le sommeil :

Tableau : Types de données sur le 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
paramètre de filtre : daily_heart_rate_variability
Type d'enregistrement  : quotidien

Appareils compatibles

list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Saturation en oxygène quotidienne
dataType : daily-oxygen-saturation
paramètre de filtre : daily_oxygen_saturation
Type d'enregistrement  : quotidien

Appareils compatibles

list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Fréquence respiratoire quotidienne
dataType : daily-respiratory-rate
paramètre de filtre : daily_respiratory_rate
Type d'enregistrement  : quotidien

Appareils compatibles

list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Écarts quotidiens de température pendant le sommeil
dataType : daily-sleep-temperature-derivations
filter parameter : daily_sleep_temperature_derivations
Type d'enregistrement  : quotidien

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
Résolution de stockage  : 1 minute

Appareils compatibles

list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Résumé de la fréquence respiratoire pendant le sommeil
dataType : respiratory-rate-sleep-summary
paramètre de filtre : 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
paramètre de filtre : sleep
Type d'enregistrement  : Session

Appareils compatibles

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

Périodes de sommeil et courts réveils

Une période de sommeil (Sleep) représente un événement de sommeil distinct, comme une seule nuit de sommeil ou une sieste en journée. Il inclut une répartition détaillée des phases de sommeil qui ne se chevauchent pas, ainsi que de brefs intervalles de transition vers l'éveil, appelés "micro-réveils".

  • Période de sommeil (Sleep) : représente un événement de sommeil distinct (intervalles de phases LIGHT, DEEP, REM, AWAKE) qui partitionne la chronologie contiguë du repos principal.
  • Réveils courts (shortAwakenings) : brèves transitions vers l'éveil ou réveils qui se produisent pendant le repos. Contrairement aux intervalles de phase AWAKE standards (qui divisent la progression des phases de sommeil contiguës sans chevauchement), les réveils courts sont des segments distincts qui peuvent chevaucher les phases de sommeil environnantes. Ils offrent une visibilité précise sur l'agitation et les micro-réveils sans perturber la structure principale des phases de sommeil.
  • Réveils nocturnes : les réveils au milieu de la nuit (par exemple, pour boire de l'eau) sont identifiés par la fusion des capteurs de l'appareil (accéléromètre, gyroscope et nombre de pas). Les applications peuvent détecter les réveils nocturnes en filtrant stages pour les intervalles avec type: "AWAKE" (utilisé dans les journaux de sommeil CLASSIC et STAGES) ou en inspectant outOfBedSegments.

Exemple

{
  "name": "users/user-id/dataTypes/sleep/dataPoints/data-point-id",
  "sleep": {
    "interval": {
      "startTime": "2026-04-20T22:30:00Z",
      "startUtcOffset": "-14400s",
      "endTime": "2026-04-21T06:30:00Z",
      "endUtcOffset": "-14400s"
    },
    "type": "STAGES",
    "stages": [
      {
        "startTime": "2026-04-20T22:30:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-04-20T23:45:00Z",
        "endUtcOffset": "-14400s",
        "type": "LIGHT"
      },
      {
        "startTime": "2026-04-20T23:45:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-04-21T01:15:00Z",
        "endUtcOffset": "-14400s",
        "type": "DEEP"
      }
    ],
    "shortAwakenings": [
      {
        "startTime": "2026-04-20T23:10:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-04-20T23:11:30Z",
        "endUtcOffset": "-14400s",
        "type": "AWAKE"
      }
    ],
    "summary": {
      "minutesInSleepPeriod": "480",
      "minutesAsleep": "455",
      "minutesAwake": "25",
      "minutesToFallAsleep": "15",
      "minutesAfterWakeUp": "10"
    }
  }
}

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 l'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 d'efficacité et de 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é du sommeil et l'endormissement. 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 au temps total passé au lit, ce qui fournit des informations sur l'hygiène du sommeil et la qualité du 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 de phase en fonction des données des capteurs enregistrées dans les nouvelles limites d'heure de coucher et de 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 (metadata.manuallyEdited est false), summary.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 (metadata.manuallyEdited est true), l'API calcule et renseigne summary.minutesToFallAsleep ainsi que summary.minutesAfterWakeUp.

Conseils pour la recherche et l'enregistrement manuel

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

  1. La modification des limites de temps au lit modifie le interval (et le summary.minutesInSleepPeriod) de sommeil.
  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, summary.minutesToFallAsleep et summary.minutesAfterWakeUp sont recalculés en fonction de la nouvelle période.

Variations quotidiennes de la température pendant le sommeil

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

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 les exemples de fréquence respiratoire (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 dans le 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 indique 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ésumés quotidiens (daily-heart-rate-variability).

Saturation en oxygène

La saturation en oxygène (SpO2) représente le pourcentage d'hémoglobine saturée en oxygène par rapport à la quantité totale d'hémoglobine dans le sang. Le suivi de la SpO2 pendant le sommeil permet de détecter d'éventuels troubles respiratoires et de confirmer si l'utilisateur maintient des niveaux d'oxygène adéquats tout au long de la nuit. L'API est compatible avec les échantillons de SpO2 (oxygen-saturation) et les résumés quotidiens (daily-oxygen-saturation).

Lorsque vous interrogez oxygen-saturation au niveau de la minute, l'API Google Health ne renvoie que les points de données validés et filtre les mesures non valides causées par un mouvement du bras, un bracelet mal ajusté ou une faible confiance du capteur (inférieure à 50 %), ainsi que les relevés adjacents au bruit de mouvement. Étant donné que les minutes non valides sont exclues, la couverture au niveau des minutes peut être éparse et des écarts de code temporel sont attendus. oxygen-saturation et daily-oxygen-saturation s'appuient sur les mêmes lectures validées. Pour en savoir plus sur les critères de validation, consultez Filtrage de la SpO2 à la minute et validité des données.

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

Bien que chaque métrique fournisse des insights spécifiques, elles sont étroitement liées et offrent ensemble une vue globale de la récupération d'un utilisateur. Les phases de sommeil (léger, profond et paradoxal) constituent la base structurelle du repos, tandis que les marqueurs physiologiques tels que 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 un sommeil profond optimal est souvent corrélé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. Une augmentation soudaine de la fréquence respiratoire ou un écart de température 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 en tandem, 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 courts réveils, interrogez le type de données sleep.
  • Réveils nocturnes : pour suivre les réveils nocturnes sans flux de capteurs bruts, inspectez les intervalles de phase sleep et filtrez les éléments avec type: "AWAKE" (pour les journaux de sommeil STAGES et CLASSIC) ou inspectez outOfBedSegments.
  • Latence et efficacité : utilisez summary.minutesToFallAsleep et la formule d'efficacité du sommeil pour analyser la latence du sommeil. Notez que summary.minutesToFallAsleep est renseigné lorsque les journaux de sommeil sont modifiés manuellement (metadata.manuallyEdited est true) ou explicitement enregistrés.
  • Surveillance physiologique : pour une surveillance avancée de la santé, combinez les données de la période de sommeil avec des 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.
  • Rapprochement : utilisez l'opération reconcile pour vous assurer que les journaux de sommeil qui se chevauchent et proviennent de différents appareils (par exemple, un accessoire connecté et un capteur de matelas) sont fusionnés en un seul enregistrement de sommeil "principal".

Calculer le temps total en sommeil profond

Pour calculer la durée totale qu'un utilisateur a passée dans une 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.