Skip to content

API_REFERENCE.md

Latest commit

 

History

History
549 lines (420 loc) · 14.6 KB

API_REFERENCE.md

File metadata and controls

549 lines (420 loc) · 14.6 KB

API Reference

Complete API documentation for react-native-google-fit.

Table of Contents

Authorization

Methods

Method Description Returns
authorize(options) Request access to Google Fit with specified scopes Promise<{success: boolean, message?: string}>
checkIsAuthorized() Check if already authorized Promise<void> (sets GoogleFit.isAuthorized)
disconnect() Revoke access and remove listeners void

Example

import GoogleFit, { Scopes } from 'react-native-google-fit'

const options = {
  scopes: [
    Scopes.FITNESS_ACTIVITY_READ,
    Scopes.FITNESS_ACTIVITY_WRITE,
    Scopes.FITNESS_BODY_READ,
    Scopes.FITNESS_BODY_WRITE,
  ],
}

// Authorize
const authResult = await GoogleFit.authorize(options)
if (authResult.success) {
  console.log('Authorized!')
}

// Check authorization status
await GoogleFit.checkIsAuthorized()
console.log(GoogleFit.isAuthorized) // true or false

Available Scopes

See src/scopes.js for all available scopes. Common ones:

  • Scopes.FITNESS_ACTIVITY_READ / FITNESS_ACTIVITY_WRITE
  • Scopes.FITNESS_BODY_READ / FITNESS_BODY_WRITE
  • Scopes.FITNESS_HEART_RATE_READ / FITNESS_HEART_RATE_WRITE
  • Scopes.FITNESS_BLOOD_PRESSURE_READ / FITNESS_BLOOD_PRESSURE_WRITE
  • Scopes.FITNESS_BLOOD_GLUCOSE_READ / FITNESS_BLOOD_GLUCOSE_WRITE
  • Scopes.FITNESS_NUTRITION_READ / FITNESS_NUTRITION_WRITE
  • Scopes.FITNESS_SLEEP_READ / FITNESS_SLEEP_WRITE

Activity & Steps

Methods

Method Description Parameters Returns
getDailyStepCountSamples(options) Get daily step counts for a period {startDate, endDate, bucketUnit?, bucketInterval?} Promise<Array>
getDailySteps(date?) Get steps for a specific day date?: Date Promise<number>
getWeeklySteps(date?, adjustment?) Get steps for a week date?: Date, adjustment?: number Promise<number>
getUserInputSteps(options) Get manually entered steps {startDate, endDate} Callback
getDailyDistanceSamples(options) Get distance data {startDate, endDate, bucketUnit?, bucketInterval?} Promise<Array>
getActivitySamples(options) Get activity data {startDate, endDate, bucketUnit?, bucketInterval?} Promise<Array>
getMoveMinutes(options) Get move minutes (Google Fit metric) {startDate, endDate, bucketUnit?, bucketInterval?} Promise<Array>
getDailyCalorieSamples(options) Get calorie expenditure {startDate, endDate, basalCalculation?, bucketUnit?, bucketInterval?} Promise<Array>

Example: Get Daily Steps

const options = {
  startDate: "2024-01-01T00:00:00.000Z",
  endDate: new Date().toISOString(),
  bucketUnit: BucketUnit.DAY,
  bucketInterval: 1,
}

const steps = await GoogleFit.getDailyStepCountSamples(options)
console.log(steps)

Response Format

[
  {
    source: "com.google.android.gms:estimated_steps",
    steps: [
      { date: "2024-01-01", value: 5432 },
      { date: "2024-01-02", value: 8921 }
    ],
    rawSteps: [
      { startDate: 1704067200000, endDate: 1704153600000, steps: 5432 }
    ]
  }
]

Body Measurements

Methods

Method Description Parameters Returns
getWeightSamples(options) Get weight history {startDate, endDate, unit?, bucketUnit?, bucketInterval?, ascending?} Promise<Array>
saveWeight(options) Save weight entry {value, date, unit?} Callback
deleteWeight(options) Delete weight entry {value, date} Callback
getHeightSamples(options) Get height history {startDate, endDate, bucketUnit?, bucketInterval?, ascending?} Promise<Array>
saveHeight(options) Save height entry {value, date} Callback
deleteHeight(options) Delete height entry {value, date} Callback

Example: Weight Tracking

// Save weight
await GoogleFit.saveWeight({
  value: 75.5,
  date: new Date().toISOString(),
  unit: "kg" // or "pound"
})

// Get weight history
const weights = await GoogleFit.getWeightSamples({
  startDate: "2024-01-01T00:00:00.000Z",
  endDate: new Date().toISOString(),
  unit: "kg",
  ascending: false
})

Response Format

[
  {
    addedBy: "com.example.app",
    value: 75.5,
    startDate: "2024-01-15T10:00:00.000Z",
    endDate: "2024-01-15T10:00:00.000Z",
    day: "Mon"
  }
]

Heart Rate & Blood Pressure

Methods

Method Description Parameters Returns
getHeartRateSamples(options) Get heart rate data {startDate, endDate, bucketUnit?, bucketInterval?} Promise<Array>
getAggregatedHeartRateSamples(options, inLocalTimeZone?) Get aggregated heart rate {startDate, endDate} Promise<Array>
getRestingHeartRateSamples(options) Get resting heart rate {startDate, endDate} Promise<Array>
saveHeartRate(options) Save heart rate measurement {value, date} Callback
getBloodPressureSamples(options) Get blood pressure data {startDate, endDate, bucketUnit?, bucketInterval?} Promise<Array>
saveBloodPressure(options) Save blood pressure reading {systolic, diastolic, date} Promise<boolean>

Example: Heart Rate

// Get heart rate samples
const heartRate = await GoogleFit.getHeartRateSamples({
  startDate: "2024-01-01T00:00:00.000Z",
  endDate: new Date().toISOString()
})

// Save heart rate
GoogleFit.saveHeartRate({
  value: 72,
  date: new Date().toISOString()
}, (error, result) => {
  if (result) console.log('Saved!')
})

Blood Pressure Example

await GoogleFit.saveBloodPressure({
  systolic: 120,
  diastolic: 80,
  date: new Date().toISOString()
})

Blood Glucose & Other Vitals

Methods

Method Description Parameters Returns
getBloodGlucoseSamples(options) Get blood glucose data {startDate, endDate} Callback
saveBloodGlucose(options) Save blood glucose reading {value, date} Promise<boolean>
getBodyTemperatureSamples(options) Get body temperature data {startDate, endDate} Callback
getOxygenSaturationSamples(options) Get oxygen saturation (SpO2) {startDate, endDate} Callback

Example

// Save blood glucose
await GoogleFit.saveBloodGlucose({
  value: 95, // mg/dL
  date: new Date().toISOString()
})

// Get readings
GoogleFit.getBloodGlucoseSamples({
  startDate: "2024-01-01T00:00:00.000Z",
  endDate: new Date().toISOString()
}, (error, result) => {
  console.log(result)
})

Nutrition & Hydration

Methods

Method Description Parameters Returns
getDailyNutritionSamples(options) Get nutrition data {startDate, endDate, bucketUnit?, bucketInterval?} Promise<Array>
saveFood(options) Save food/nutrition entry {foodName, nutrients, date, mealType?} Callback
getHydrationSamples(options) Get hydration data {startDate, endDate} Promise<Array>
saveHydration(waterArray) Save hydration data [{date, waterConsumed}] Promise<boolean>
deleteHydration(options) Delete hydration entry {date} Callback

Example: Hydration

// Save water intake
await GoogleFit.saveHydration([
  {
    date: new Date().toISOString(),
    waterConsumed: 250 // ml
  }
])

// Get hydration history
const hydration = await GoogleFit.getHydrationSamples({
  startDate: "2024-01-01T00:00:00.000Z",
  endDate: new Date().toISOString()
})

Example: Nutrition

GoogleFit.saveFood({
  foodName: "Banana",
  date: new Date().toISOString(),
  mealType: "snack", // breakfast, lunch, dinner, snack
  nutrients: {
    [Nutrient.CALORIES]: 105,
    [Nutrient.PROTEIN]: 1.3,
    [Nutrient.CARBS]: 27,
    [Nutrient.SUGAR]: 14
  }
}, (error, result) => {
  console.log('Food saved!')
})

Sleep

Methods

Method Description Parameters Returns
getSleepSamples(options, inLocalTimeZone?) Get sleep data {startDate, endDate} Promise<Array>
saveSleep(options) Save sleep session {startDate, endDate, sleepStages?} Promise<boolean>
deleteAllSleep(options) Delete all sleep data in range {startDate, endDate} Promise<boolean>

Example

// Get sleep data
const sleep = await GoogleFit.getSleepSamples({
  startDate: "2024-01-01T00:00:00.000Z",
  endDate: new Date().toISOString()
}, true) // inLocalTimeZone = true

// Save sleep
await GoogleFit.saveSleep({
  startDate: "2024-01-15T22:00:00.000Z",
  endDate: "2024-01-16T06:00:00.000Z",
  sleepStages: [
    { startDate: "2024-01-15T22:00:00.000Z", endDate: "2024-01-15T22:30:00.000Z", stage: SleepStage.AWAKE },
    { startDate: "2024-01-15T22:30:00.000Z", endDate: "2024-01-16T02:00:00.000Z", stage: SleepStage.DEEP },
    { startDate: "2024-01-16T02:00:00.000Z", endDate: "2024-01-16T05:00:00.000Z", stage: SleepStage.LIGHT },
    { startDate: "2024-01-16T05:00:00.000Z", endDate: "2024-01-16T06:00:00.000Z", stage: SleepStage.REM }
  ]
})

Sleep Stages

import { SleepStage } from 'react-native-google-fit'

SleepStage.AWAKE      // 1
SleepStage.SLEEP      // 2
SleepStage.OUT_OF_BED // 3
SleepStage.LIGHT      // 4
SleepStage.DEEP       // 5
SleepStage.REM        // 6

Workouts

Methods

Method Description Parameters Returns
getWorkoutSession(options) Get workout sessions {startDate, endDate} Promise<Array>
saveWorkout(options) Save workout session {startDate, endDate, activityType, calories?, distance?} Promise<boolean>
deleteAllWorkout(options) Delete all workouts in range {startDate, endDate} Promise<boolean>

Example

import { ActivityType } from 'react-native-google-fit'

// Save workout
await GoogleFit.saveWorkout({
  startDate: "2024-01-15T10:00:00.000Z",
  endDate: "2024-01-15T11:00:00.000Z",
  activityType: ActivityType.Running,
  calories: 450,
  distance: 5000 // meters
})

// Get workouts
const workouts = await GoogleFit.getWorkoutSession({
  startDate: "2024-01-01T00:00:00.000Z",
  endDate: new Date().toISOString()
})

Activity Types

See ActivityType constant for all available activities (Running, Walking, Cycling, Swimming, etc.)

Recording API

The Recording API allows background data collection without needing the Google Fit app.

Methods

Method Description Parameters Returns
startRecording(callback, dataTypes?) Start background recording dataTypes?: string[] void
isAvailable(callback) Check if Google Fit is available Callback void
openFit() Open Google Fit app None void

Example

// Start recording steps in background
GoogleFit.startRecording((callback) => {
  console.log('Recording started')
})

// With specific data types
GoogleFit.startRecording((callback) => {
  console.log('Recording started')
}, ['step', 'distance', 'activity'])

Note: Requires ACCESS_FINE_LOCATION permission for location/distance data.

Permissions

Methods

Method Description Returns
checkPermissionAndroid() Check if location permission granted Promise<boolean>
requestPermissionAndroid(dataTypes?) Request location permission Promise<boolean>

Example

// Check permission
const hasPermission = await GoogleFit.checkPermissionAndroid()

// Request permission
if (!hasPermission) {
  const granted = await GoogleFit.requestPermissionAndroid(['step', 'distance'])
  if (granted) {
    console.log('Permission granted!')
  }
}

Constants & Types

BucketUnit

Time intervals for aggregating data:

import { BucketUnit } from 'react-native-google-fit'

BucketUnit.NANOSECOND
BucketUnit.MICROSECOND
BucketUnit.MILLISECOND
BucketUnit.SECOND
BucketUnit.MINUTE
BucketUnit.HOUR
BucketUnit.DAY

Nutrient

Nutrition data types (see Nutrient constants for full list):

import { Nutrient } from 'react-native-google-fit'

Nutrient.CALORIES
Nutrient.PROTEIN
Nutrient.TOTAL_FAT
Nutrient.TOTAL_CARBS
Nutrient.SUGAR
// ... and many more

ActivityType

Physical activity types (see ActivityType constants for full list):

import { ActivityType } from 'react-native-google-fit'

ActivityType.Running
ActivityType.Walking
ActivityType.Cycling
ActivityType.Swimming
ActivityType.Yoga
// ... 100+ activity types

SleepStage

Sleep stage classifications:

import { SleepStage } from 'react-native-google-fit'

SleepStage.AWAKE      // 1
SleepStage.SLEEP      // 2
SleepStage.OUT_OF_BED // 3
SleepStage.LIGHT      // 4
SleepStage.DEEP       // 5
SleepStage.REM        // 6

Common Options

Most methods accept these common parameters:

Parameter Type Description Default
startDate string ISO8601 timestamp Required
endDate string ISO8601 timestamp Required
bucketUnit BucketUnit Time unit for aggregation DAY
bucketInterval number Number of units per bucket 1
ascending boolean Sort order false

Date Format

All dates should be in ISO8601 format:

new Date().toISOString() // "2024-01-15T10:30:00.000Z"

Error Handling

All async methods return promises and can be caught:

try {
  const steps = await GoogleFit.getDailyStepCountSamples(options)
  console.log(steps)
} catch (error) {
  console.error('Error fetching steps:', error)
}

For callback-based methods:

GoogleFit.saveWeight(options, (error, result) => {
  if (error) {
    console.error('Error saving weight:', error)
  } else {
    console.log('Weight saved!', result)
  }
})

Next Steps