Especificaciones de la API

En la sección Especificación de la API, se proporciona una descripción general detallada de los componentes técnicos esenciales para la integración en la plataforma, incluidos los permisos de autorización, las definiciones de tipos de datos y las estructuras de los extremos. Esta API representa una evolución estratégica de la API web de Fitbit heredada, que se volvió a compilar en una infraestructura moderna para garantizar una experiencia de desarrollador más estable y coherente.

Permisos

Debes actualizar tu solicitud de autorización para usar los permisos de la API de Google Health. Los permisos definen si tu app admite operaciones de lectura o escritura. Sigue las instrucciones de implementación de permisos, que especifican que solo se deben solicitar los permisos necesarios, configurar el acceso de escritura solo cuando se envían datos y controlar el consentimiento parcial de forma correcta.

Los permisos de la API de Google Health son una URL HTTP que comienza con https://www.googleapis.com/auth/googlehealth.{scope}. Por ejemplo, https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly

Asignaciones de permisos

A continuación, se muestra cómo se asignan los permisos de la API web de Fitbit a los permisos de la API de Google Health:

Tabla: Asignaciones de permisos de la API web de Fitbit a la API de Google Health
Permisos de la API web de Fitbit Permisos de la API de Google Health
actividad .activity_and_fitness.readonly
.activity_and_fitness.writeonly
blood_glucose .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
cardio_fitness .activity_and_fitness.readonly
.activity_and_fitness.writeonly
Electrocardiograma .ecg.readonly
Frecuencia cardíaca .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
irregular_rhythm_notifications .irn.readonly
ubicación .location.readonly
nutrición .nutrition.readonly
.nutrition.writeonly
oxygen_saturation .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
perfil .profile.readonly
.profile.writeonly
respiratory_rate .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
configuración .settings.readonly
.settings.writeonly
sleep .sleep.readonly
.sleep.writeonly
temperatura .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
peso .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly

Tipos de datos

A continuación, se incluye una lista de los tipos de datos de la API de Google Health y cómo se asignan a la API web de Fitbit.

Tabla: Asignaciones de tipos de datos de la API web de Fitbit a la API de Google Health
Tipo de datos de la API web de Fitbit Tipo de datos de la API de Google Health
  dataType
Descripción
Calorías por actividad Gasto calórico por actividad
  active-energy-burned
Representa las calorías quemadas durante los períodos de actividad, incluida la BMR de esos períodos. En la API de Google Health, esto se puede reconstruir agregando la TMB al tipo de datos active-energy-burned (que hace un seguimiento de las calorías quemadas solo durante la actividad, sin incluir la tasa basal).
Minutos en zona activa Minutos en zona activa
  active-zone-minutes
Contiene cambios en los niveles de actividad del usuario. Nivel de actividad
  activity-level
Captura el nivel de actividad del usuario (como sedentario o activo) durante un período específico.
Elevación Altitud
  altitude
Actividad caloriesBMR Gasto calórico basal
  basal-energy-burned
Son las calorías quemadas debido a la tasa metabólica basal (BMR) durante un período específico.
Glucemia Glucemia
  blood-glucose
Grasa corporal Grasa corporal
  body-fat
caloriesOut en cada zona de frecuencia cardíaca Calorías en la zona de frecuencia cardíaca
  calories-in-heart-rate-zone
Temperatura (principal) Temperatura corporal central
  core-body-temperature
Resumen de la VFC Variabilidad de la frecuencia cardíaca diaria
  daily-heart-rate-variability
Resumen de SpO2 Saturación de oxígeno diaria
  daily-oxygen-saturation
Es un resumen diario de las estadísticas de saturación de oxígeno en sangre (SpO2) calculadas a partir de mediciones de sueño validadas.
Frecuencia cardíaca en reposo Frecuencia cardíaca en reposo diaria
  daily-resting-heart-rate
Temperatura cutánea Variaciones diarias de la temperatura durante el sueño
  daily-sleep-temperature-derivations
Distancia Distancia
  distance
Electrocardiograma (ECG) Electrocardiograma (ECG)
  electrocardiogram
Actividad registrada Ejercicio
  exercise
Son los entrenamientos o las sesiones de ejercicio registrados, que incluyen las horas de inicio y finalización, los tipos de actividad y las métricas de la sesión.
Pisos Pisos
  floors
Comida Alimentos
  food
Unidad de medida de alimentos Unidad de medida de alimentos
  food-measurement-unit
Frecuencia cardíaca Frecuencia cardíaca
  heart-rate
VFC intradía Variabilidad de la frecuencia cardíaca
  heart-rate-variability
Notificaciones de arritmias (IRN) Notificación de arritmias
  irregular-rhythm-notification
Registro de alimentos Registro de nutrición
  nutrition-log
SpO2 intradía Saturación de oxígeno
  oxygen-saturation
Muestra solo las mediciones de SpO2 validadas a nivel de minuto y excluye las lecturas marcadas como no válidas debido a artefactos de movimiento o baja confianza del sensor. Debido a que la API web de Fitbit solo excluyó el valor de centinela del 50%, la API de Google Health devuelve menos datos para el mismo período. Para obtener más detalles, consulta Filtrado de la saturación de oxígeno.
Valor de VO2 máx. cuando el usuario corre VO2 máx. en carreras
  run-vo2-max
Minutos de tiempo sedentario de la serie temporal de actividad Período sedentario
  sedentary-period
Sueño Sueño
  sleep
Pasos Pasos
  steps
Brazadas de natación de la serie temporal de actividad Datos de largos de natación
  swim-lengths-data
Actividad caloriesOut Calorías totales
  total-calories
Es la cantidad total de calorías quemadas por un usuario durante un período, incluida la tasa metabólica basal y la energía activa quemada.
Valor de VO2 máx. VO2 máx.
  vo2-max
Peso Peso
  weight

Cálculos

Las asignaciones y reglas de la API de Google Health difieren de las de la API web de Fitbit.

Filtrado de la saturación de oxígeno

Cuando se consulta la saturación de oxígeno en sangre por minuto (oxygen-saturation), la API de Google Health aplica un filtrado de validez de datos más estricto que la API web de Fitbit heredada:

  • La API web de Fitbit heredada (v1 y v3) solo excluía las muestras de SpO2 con un valor de centinela del 50%.
  • La API de Google Health (v4) excluye todas las muestras de SpO2 que el algoritmo de validación marca como no válidas. Un minuto se marca como no válido cuando el movimiento del brazo o un ajuste flojo en la muñeca hacen que la señal del sensor óptico no sea confiable, cuando la puntuación de confianza cae por debajo del 50%, durante los 3 minutos inmediatamente anteriores y posteriores a una lectura no válida, o cuando un tramo válido dura menos de 4 minutos consecutivos.

Debido a que la API de Google Health quita todas las mediciones no válidas en lugar de solo el valor centinela del 50%, devuelve menos datos de oxygen-saturation que la API web de Fitbit para el mismo período, y se esperan brechas en la cobertura minuto a minuto. Las lecturas por minuto que se devuelven se alinean con los datos validados que se usan para calcular el resumen de sueño daily-oxygen-saturation del usuario. Para obtener más información, consulta Filtrado de SpO2 por minuto y validez de los datos.

Nivel de actividad, MET y umbrales de pasos

En la API de Google Health, el nivel de actividad minuto a minuto de un usuario se deriva de su equivalente metabólico de actividad (MET) y su recuento de pasos.

Nivel de actividad Dispositivos de frecuencia cardíaca Dispositivos que no miden la frecuencia cardíaca
Sedentario ≤1.5 MET ≤1.5 MET
Actividad ligera >1.5 MET y ≤4.2 MET >1.5 MET y ≤3.5 MET
Moderadamente activo >4.2 MET y <6.0 MET
(a menos que se cumplan las condiciones de Muy activo)
> 3.5 MET y < 6.0 MET
(a menos que se cumplan las condiciones de Muy activo)
Muy activo ≥6.0 MET o ≥5.0 MET con una frecuencia de 150 pasos por minuto o más ≥6.0 MET o ≥5.0 MET con una frecuencia de 150 pasos por minuto o más

Los minutos de actividad consisten en una combinación de minutos de MODERATELY_ACTIVE y VERY_ACTIVE. Sin embargo, un minuto de actividad intensa solo se acredita si se produce durante una racha continua de al menos 10 minutos, lo que permite, como máximo, intervalos de 2 minutos de menor actividad.

Minutos de sedentarismo y sueño

Los minutos de sedentarismo no incluyen el tiempo de sueño. En los resúmenes diarios, los minutos de sedentarismo se calculan restando los minutos de sueño y los minutos de actividad (actividad ligera, actividad moderada y actividad intensa) de los minutos totales del día (1,440 minutos):

Sedentary Minutes = 1440 - Sleep Minutes - Lightly Active Minutes - Moderately Active Minutes - Very Active Minutes

Índice de masa corporal (IMC)

Debido a que la API de Google Health no expone un tipo de datos de IMC integrado, las aplicaciones deben calcular el índice de masa corporal del cliente con los registros de altura y peso:

  1. Recupera el peso del usuario en gramos del campo weightGrams en el tipo de datos Peso. Convierte este valor en kilogramos (divide por 1,000) o libras (divide por 453.59237).
  2. Recupera la altura del usuario en milímetros del campo heightMillimeters en el tipo de datos Altura. Convierte este valor en metros (divídelo por 1,000) o en pulgadas (divídelo por 25.4).
  3. Usa una de las siguientes fórmulas para calcular el valor del IMC:
    • Fórmula de la métrica: BMI = weight (kg) / [height (m)]^2
    • Fórmula imperial: BMI = (weight (lbs) / [height (in)]^2) * 703

height.heightMillimeters se serializa como una cadena JSON int64 (como "1750"), y la lectura de los registros de height de usuarios existentes que no creó tu app requiere health_metrics_and_measurements.readonly además de health_metrics_and_measurements.writeonly cuando se registra el peso.

Los valores de IMC resultantes corresponden a las siguientes categorías:

Categoría de peso Rango de IMC
Bajo peso Menos de 18.5
Peso saludable De 18.5 a 24.9
Sobrepeso De 25 a 29.9
Obese 30 o superior

Tasa metabólica basal (BMR)

La tasa metabólica basal (BMR) es la cantidad mínima de calorías que se necesitan para las funciones corporales básicas en reposo. Debido a que la API de Google Health no expone un tipo de datos de TMB integrado, las aplicaciones deben calcularlo en el cliente con la fórmula de Harris-Benedict. Consulta el artículo sobre la ecuación de Harris-Benedict en Wikipedia para obtener más información.

Para realizar este cálculo, haz lo siguiente:

  1. Recupera el peso del usuario en gramos del campo weightGrams en el tipo de datos Weight y conviértelo en kilogramos (divídelo por 1,000). Para convertir libras en kilogramos, divide por 2.2.
  2. Recupera la altura del usuario en milímetros del campo heightMillimeters en el tipo de datos Altura y conviértela en centímetros (divídela por 10). Para convertir pulgadas en centímetros, multiplica por 2.54.
  3. Recupera la edad del usuario en años del campo age en el recurso Profile.
  4. Recupera el sexo biológico de forma independiente (por ejemplo, solicitándoselo al usuario o manteniéndolo en tu propia base de datos), ya que la API de Google Health no expone este campo.
  5. Usa una de las siguientes fórmulas según el sexo biológico del usuario:
    • Hombres: BMR = 66 + (13.7 x weight_kg) + (5 x height_cm) - (6.8 x age_years)
    • Mujeres: BMR = 655 + (9.6 x weight_kg) + (1.8 x height_cm) - (4.7 x age_years)

Gasto energético diario total (TDEE)

El gasto energético diario total (TDEE) es una estimación de la cantidad total de calorías que una persona quema en un día, lo que incluye tanto la BMR como la actividad física. Para estimar el TDEE del usuario, multiplica el valor de la BMR por un factor de actividad que corresponda a su estilo de vida:

Nivel de actividad Descripción Multiplicador
Sedentario Poco o ningún ejercicio BMR x 1.2
Actividad ligera De 1 a 3 días de ejercicio por semana BMR x 1.375
Moderadamente activo De 3 a 5 días de ejercicio por semana BMR x 1.55
Muy activo De 6 a 7 días de ejercicio por semana. BMR x 1.725
Nivel muy alto de actividad Ejercicio muy intenso o trabajo físico BMR x 1.9

Extremos

Los extremos de REST adoptan una sintaxis coherente para todos los tipos de datos.

  • Extremo de servicio: La URL HTTP base cambia a https://health.googleapis.com.
  • Sintaxis de los extremos: La API de Google Health admite una cantidad limitada de extremos, que pueden usar la mayoría de los tipos de datos admitidos. Esto proporciona una sintaxis coherente para todos los tipos de datos y hace que los extremos sean más fáciles de usar.
  • Identificador de usuario: Se debe especificar el ID de usuario o me en la sintaxis del extremo. Cuando se usa me, el ID del usuario se infiere del token de acceso.

Ejemplo: Este es un ejemplo del extremo GET Profile al que se llama con la API de Google Health

GET https://health.googleapis.com/v4/users/me/profile

Asignaciones de extremos

Consulta la tabla Tipos de datos de la API de Google Health para obtener una lista de los tipos de datos disponibles y los métodos de la API que admiten.

Tipo de endpoint de la API web de Fitbit API de Google Health
GET (Log | Summary | Daily Summary) en el que solicitas un solo día de datos Método dailyRollUp (POST .../dataPoints:dailyRollUp) con windowSizeDays: 1
GET (Intraday) en el que solicitas datos detallados Método list
GET (series temporales) por fecha o intervalo Método rollUp o dailyRollUp que incluye un período
GET (Log List) Método list
Registros CREATE Método create (POST /v4/users/{user}/dataTypes/{type}/dataPoints con sampleTime.utcOffset obligatorio para tipos de muestra o interval.startUtcOffset y interval.endUtcOffset para tipos de intervalo, que devuelve un wrapper Operation síncrono)
Registros de UPDATE Método patch (PATCH /v4/users/{user}/dataTypes/{type}/dataPoints/{id} con sampleTime.utcOffset obligatorio para tipos de muestra o interval.startUtcOffset y interval.endUtcOffset para tipos de intervalo, que devuelve un wrapper Operation síncrono)
Registros de DELETE Método batchDelete (POST /v4/users/{user}/dataTypes/{type}/dataPoints:batchDelete con {"names": [...]}, sin método HTTP DELETE, que devuelve un wrapper Operation síncrono)
GET Profile users.getProfile devuelve la información específica del usuario.
users.getSettings devuelve las unidades y las zonas horarias del usuario.
ACTUALIZAR perfil users.updateProfile modifica la información específica del usuario
users.updateSettings modifica las unidades y las zonas horarias del usuario
Obtener el ID de usuario users.getIdentity devuelve el ID de usuario de Google y el ID de Fitbit heredado del usuario.
Obtener dispositivos users.pairedDevices devuelve la lista de dispositivos vinculados.
Crea suscripciones projects.subscribers.subscriptions.create crea una suscripción de forma manual
Borrar suscripciones projects.subscribers.subscriptions.delete borrar una suscripción
Obtén la lista de suscripciones projects.subscribers.subscriptions.list enumera todas las suscripciones