Разработка функций для отслеживания сна с помощью Google Health API

Google Health API предоставляет типы данных, которые отслеживают характер сна пользователя, включая продолжительность, качество и физиологические показатели во время отдыха. Эти показатели помогают приложениям предоставлять статистику о восстановлении, гигиене сна и долгосрочных тенденциях в отношении здоровья.

Физиологические показатели, такие как вариабельность сердечного ритма (ВСР), уровень кислорода в крови (SpO2) и частота дыхания, регистрируются именно во время сна, поскольку тело находится в стабильном состоянии покоя. Это позволяет API зафиксировать базовые показатели вегетативной и дыхательной систем пользователя без влияния дневных стрессоров, физической активности или меняющихся условий окружающей среды.

Изучите различия между этими типами данных, чтобы определить, какие показатели подходят для вашего приложения.

Поддерживаемые типы данных

API поддерживает следующие типы данных для отслеживания сна:

Таблица. Типы данных о сне в Google Health API
Тип данных Доступные
операции		 Область действия
Вариабельность сердечного ритма за день
dataType: daily-heart-rate-variability
filter parameter: daily_heart_rate_variability
Тип записи: ежедневно.

Совместимые устройства
список, сверка .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Ежедневный уровень кислорода в крови
dataType: daily-oxygen-saturation
filter parameter: daily_oxygen_saturation
Тип записи: ежедневно.

Совместимые устройства
список, сверка .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Ежедневная частота дыхания
dataType: daily-respiratory-rate
filter parameter: daily_respiratory_rate
Тип записи: ежедневно.

Совместимые устройства
список, сверка .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Отклонения температуры во время сна по дням
dataType: daily-sleep-temperature-derivations
filter parameter: daily_sleep_temperature_derivations
Тип записи: ежедневно.

Совместимые устройства
список, сверка .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Вариабельность сердечного ритма
dataType: heart-rate-variability
filter parameter: heart_rate_variability
Тип записи: Sample.

Совместимые устройства
список, сверка .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Уровень кислорода в крови
dataType: oxygen-saturation
filter parameter: oxygen_saturation
Тип записи: Sample.
Разрешение хранилища: 1 минута.

Совместимые устройства
список, сверка .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Сводка о частоте дыхания во время сна
dataType: respiratory-rate-sleep-summary
filter parameter: respiratory_rate_sleep_summary
Тип записи: Пример

Совместимые устройства
список, сверка .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Сон
dataType: sleep
filter parameter: sleep
Тип записи: сеанс.

Совместимые устройства
list, get, reconcile, create, update, batchDelete .sleep.readonly
.sleep.writeonly

Сеансы сна и короткие пробуждения

Сеанс сна (Sleep) представляет собой отдельное событие сна, например ночной сон или дневной сон. Она включает подробную разбивку неперекрывающихся фаз сна, а также короткие интервалы перехода к бодрствованию, известные как короткие пробуждения.

  • Сеанс сна (Sleep). Представляет собой отдельное событие сна (интервалы стадий LIGHT, DEEP, REM, AWAKE), которое разделяет непрерывную временную шкалу основного отдыха.
  • Краткие пробуждения (shortAwakenings). Краткие переходы в состояние бодрствования или пробуждения во время отдыха. В отличие от стандартных интервалов фаз AWAKE (которые делят непрерывную последовательность фаз сна без перекрытия), короткие пробуждения – это отдельные сегменты, которые могут перекрываться с окружающими фазами сна. Они позволяют получить подробную информацию о беспокойстве и микропробуждениях, не нарушая основную структуру фаз сна.
  • Пробуждения ночью. Пробуждения ночью (например, чтобы попить воды) определяются с помощью датчиков на устройстве (акселерометра, гироскопа и счетчика шагов). Приложения могут обнаруживать ночные пробуждения, фильтруя stages по интервалам с type: "AWAKE" (используется в журналах сна CLASSIC и STAGES) или проверяя outOfBedSegments.

Пример

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

Как создать сеанс сна

Чтобы создать запись о сеансе сна, отправьте запрос POST к конечной точке элементов данных sleep. Ответ содержит поле name с data-point-id, которое можно использовать в запросе Update (Patch) или Delete.

Запрос

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

Ответ

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

Показатели эффективности сна и задержки

Помимо фаз сна и физиологических показателей, API предоставляет ключевые показатели, которые количественно определяют качество сна и его начало. Эффективность сна и задержка его начала – это стандартные клинические показатели, которые описывают, насколько эффективно пользователь отдыхает по сравнению с общим временем, проведенным в постели. Они позволяют оценить гигиену сна и качество отдыха.

Оценка эффективности сна

Эффективность сна – это стандартный показатель, определяемый как доля времени, проведенного во сне, по отношению к общему времени, проведенному в постели. API вычисляет эффективность сна по следующей формуле:

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

Оценка эффективности рассчитывается непосредственно перед разделением на уровни (стадии) сна. Общее количество минут сна, возвращаемое в ответе API (в поле summary.minutesAsleep), отражает окончательный результат после вычисления уровней сна.

Если пользователь или исследователь вручную изменит время начала или окончания сна в журнале сна, API пересчитает оценку эффективности сна и скорректирует разделы фаз в соответствии с данными датчиков, записанными в пределах новых границ времени отхода ко сну и пробуждения.

Задержка начала сна

Задержка засыпания – это время, прошедшее с момента, когда пользователь намеревается заснуть (начало времени "в постели" или "выключение света"), до момента засыпания.

Для автоматически созданных журналов (metadata.manuallyEdited – false) summary.minutesToFallAsleep по умолчанию имеет значение "0", поскольку явное намерение заснуть не было зарегистрировано. Если время начала сна в кровати записано или изменено вручную (metadata.manuallyEdited равно true), API вычисляет и заполняет summary.minutesToFallAsleep вместе с summary.minutesAfterWakeUp.

Рекомендации по исследованию и ручному ведению журнала

Когда участники вручную записывают или корректируют время начала и окончания сна:

  1. Обновление границ времени в постели изменяет interval (и summary.minutesInSleepPeriod).
  2. Уровни сна и разделы стадий автоматически корректируются для оценки данных датчиков в новом окне.
  3. Оценка эффективности сна, summary.minutesToFallAsleep и summary.minutesAfterWakeUp пересчитываются на основе обновленного временного окна.

Отклонения температуры во время сна за день

Ежедневные отклонения температуры во время сна показывают, насколько температура кожи пользователя во время сна отличается от базовой. Обычно эти данные регистрируются один раз в день после основного сеанса сна.

частота дыхания;

Частота дыхания – это количество вдохов в минуту. Во время сна это ключевой показатель для мониторинга качества сна и потенциальных нарушений. API поддерживает выборку частоты дыхания (respiratory-rate), ежедневные отчеты о сне (daily-respiratory-rate) и отчеты о сне на уровне сеанса (respiratory-rate-sleep-summary).

Вариабельность сердечного ритма (ВСР)

ВСР — это изменения интервала между сердечными ритмами. Это ключевой показатель состояния вегетативной нервной системы. Высокая ВСР во время сна обычно указывает на лучшее восстановление и готовность, а низкая может свидетельствовать о стрессе или перетренированности. API поддерживает выборку ВСР (heart-rate-variability) и ежедневные сводки (daily-heart-rate-variability).

уровень кислорода в крови;

Насыщение крови кислородом (SpO2) – это процентное соотношение насыщенного кислородом гемоглобина к общему количеству гемоглобина в крови. Мониторинг SpO2 во время сна помогает выявить потенциальные нарушения дыхания и подтверждает, поддерживает ли пользователь адекватный уровень кислорода в течение ночи. API поддерживает выборку SpO2 (oxygen-saturation) и ежедневные сводки (daily-oxygen-saturation).

Когда вы запрашиваете данные oxygen-saturation с точностью до минуты, Google Health API возвращает только подтвержденные значения и отфильтровывает недействительные измерения, вызванные движением руки, неплотным прилеганием устройства к запястью или низкой достоверностью датчика (менее 50 %), а также показания, смежные с шумом движения. Поскольку недействительные минуты исключаются, поминутный охват может быть неполным, а временные метки могут иметь пропуски. И oxygen-saturation, и daily-oxygen-saturation используют одни и те же подтвержденные показания. Подробные сведения о критериях проверки см. в разделе Фильтрация и достоверность данных SpO2 на уровне минут.

Целостное представление о здоровье сна и восстановлении

Хотя каждый показатель предоставляет конкретную информацию, они тесно взаимосвязаны и вместе дают целостное представление о восстановлении пользователя. Фазы сна (поверхностный, глубокий, быстрый) обеспечивают структурную основу отдыха, а физиологические маркеры, такие как ВСР и SpO2, указывают на то, как организм физически реагирует на этот отдых. Например, высококачественный сеанс сна с оптимальной продолжительностью глубокого сна часто коррелирует с более высокой ВСР, что указывает на эффективное восстановление вегетативной нервной системы.

В сочетании с частотой дыхания и температурой во время сна эти данные позволяют приложениям выявлять потенциальные нарушения. Внезапный скачок частоты дыхания или отклонение температуры во время сна могут объяснить, почему пользователь провел меньше времени в восстановительных стадиях. Анализируя эти типы данных в тандеме, разработчики могут предоставить комплексную оценку гигиены сна и долгосрочных тенденций в отношении здоровья.

Правила

При интеграции показателей сна в приложение следуйте этим рекомендациям:

  • Сведения о сеансе. Чтобы показать фазы сна пользователя (поверхностный, глубокий, быстрый, бодрствование) и короткие пробуждения, запросите тип данных sleep.
  • Пробуждения ночью. Чтобы отслеживать пробуждения ночью без необработанных потоков данных датчиков, проверьте интервалы фаз sleep и отфильтруйте элементы с type: "AWAKE" (для журналов сна STAGES и CLASSIC) или проверьте outOfBedSegments.
  • Задержка и эффективность. Используйте summary.minutesToFallAsleep и формулу эффективности сна для анализа задержки сна. Обратите внимание, что поле summary.minutesToFallAsleep заполняется, когда журналы сна редактируются вручную (metadata.manuallyEdited – true) или регистрируются явным образом.
  • Физиологический мониторинг. Для расширенного мониторинга здоровья объедините данные сеанса сна с физиологическими показателями и показателями восстановления, такими как respiratory-rate-sleep-summary, daily-sleep-temperature-derivations, daily-heart-rate-variability и daily-oxygen-saturation.
  • Согласование. Используйте операцию reconcile, чтобы объединить пересекающиеся журналы сна с разных устройств (например, носимого устройства и датчика матраса) в одну основную запись сна.

Рассчитывать общую продолжительность глубокого сна

Чтобы рассчитать общее время, которое пользователь провел в фазе глубокого сна за определенную ночь:

  1. Запросите тип данных sleep для указанного диапазона дат.
  2. Просмотрите список стадий и определите интервалы, в которых type – это DEEP.
  3. Рассчитайте продолжительность (время окончания – время начала) для каждого интервала глубокого сна и сложите их.

Полученная сумма представляет собой общую физическую продолжительность глубокого сна за этот сеанс.

Назад
Этапы
Далее
Женское здоровье