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 reconstruyó 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 Energía activa quemada
  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 		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 Desviaciones diarias de la temperatura durante el sueño
  daily-sleep-temperature-derivations
Distancia Distancia
  distance
Electrocardiograma (ECG) Electrocardiograma (ECG)
  electrocardiogram
Actividad registrada Ejercicio
  exercise 		Entrenamientos o sesiones de ejercicio registrados, que incluyen horas de inicio y finalización, tipos de actividad y métricas de la sesión
Pisos Pisos
  floors
Comida Alimentos
  food
Unidad de medida de alimentos Unidad de medida de los 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 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 de actividad sedentaria 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, incluidas la tasa metabólica basal y el gasto calórico.
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 marcadas como no válidas por el algoritmo de validación. 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 puntos de 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 pasos de 150 pasos por minuto o más ≥6.0 MET o ≥5.0 MET con una frecuencia de pasos 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, moderada y muy activa) 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 (divídelo por 1,000) o en libras (divídelo por 453.59237).
  2. Recupera la altura del usuario en milímetros del campo heightMillimeters en el tipo de datos Height. 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

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

Categoría de peso Rango de IMC
Peso bajo Menos de 18.5
Peso saludable De 18.5 a 24.9
Sobrepeso De 25 a 29.9
Obesidad 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, sigue estos pasos:

  1. Recupera el peso del usuario en gramos del campo weightGrams en el tipo de datos Peso 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 facilita el uso de los extremos.
  • Identificador de usuario: Se debe especificar el ID de usuario o me en la sintaxis del extremo. Cuando usas me, el ID de 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 con windowSize = 1 día
GET (Intraday) cuando solicitas datos detallados Método list
GET (series temporales) por fecha o intervalo Método rollUp o dailyRollUp que incluya un período
GET (Log List) Método list
Registros de CREATE y UPDATE Método patch
Registros DELETE Método batchDelete
GET Profile users.getProfile devuelve la información específica del usuario
users.getSettings devuelve las unidades y 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
Borra suscripciones projects.subscribers.subscriptions.delete borrar una suscripción
Obtener la lista de suscripciones projects.subscribers.subscriptions.list enumera todas las suscripciones