fitbit

README

go-fitbit

A library for exporting your tracker data from the Fitbit. It's meant to be used for extracting raw tracker data and not as a backup tool. It does not cover all available fields, but rather aims to capture the most granular data available.

Status

• Activities
• Heart rate
• Location
• Nutrition
• Sleep
• Weight

Prerequisites

To use this library, you need to create an OAuth2 application on dev.fitbit.com. To get the full data, you should mark the application as Personal type.

The Fitbit authorization process requires that the callback URL used in the OAuth2 application to be available for the initial token request (you can put for example localhost:8080 there).

Installation

go get github.com/byonchev/go-fitbit

Usage

package main

import (
	"fmt"
	"time"

	"github.com/byonchev/go-fitbit"
)

func main() {
	config := fitbit.Config{
		// Port for the initial callback URL server
		CallbackServerPort: 8080,
		// OAuth2 credentials
		ClientID:     "XXXXXXXX",
		ClientSecret: "XXXXXXXXXXXXXXXXXXXXXXXX",
		// Scopes that you want to access
		Scopes: []fitbit.Scope{fitbit.Sleep, fitbit.HeartRate},
		// Path to the token that will be stored on your machine
		TokenPath: "token.json",
	}

	client := fitbit.NewClient(config)

	sleepLogs, err := client.GetSleepLogs(time.Now().Add(-24 * time.Hour))
	if err != nil {
		panic(err)
	}

	fmt.Printf("%+v\n", sleepLogs)
}

Note: Keep in mind that the API rate limit is 150 requests per hour.

Initial run

When running for the first time (or adding more scopes), you'll have to accept the scopes manually in a browser. You'll get a message like this in the stdout:

2019/08/17 23:32:57 Visit URL: https://www.fitbit.com/oauth2/authorize?client_id=XXXXXX&response_type=code&scope=sleep+heartrate&state=XXXX

The library creates a temporary HTTP server on the CallbackServerPort. Once you've accepted the requested scopes, the browser will redirect to the callback URL, which will be handled by the temporary HTTP server. This captures the initial token and stores it on the TokenPath.

Once the initial setup is done, the library takes care of the token refreshing and should not require manual intervention.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

MIT

Documentation

Index

• type Client
  • func NewClient(config Config) *Client
  • func (client Client) GetHeartRateLogs(date time.Time, resolution DataResolution) ([]HeartRateMeasurement, error)
  • func (client Client) GetSleepLogs(date time.Time) ([]SleepLogEntry, error)
• type Config
• type DataResolution
• type HeartRateMeasurement
• type LocalDate
  • func (date *LocalDate) UnmarshalJSON(data []byte) error
• type LocalTime
  • func (date *LocalTime) UnmarshalJSON(data []byte) error
• type MillisecondDuration
  • func (duration *MillisecondDuration) UnmarshalJSON(data []byte) error
• type MinuteDuration
  • func (duration *MinuteDuration) UnmarshalJSON(data []byte) error
• type Scope
• type SecondDuration
  • func (duration *SecondDuration) UnmarshalJSON(data []byte) error
• type SleepData
• type SleepEvent
• type SleepLogEntry
• type SleepPhase
• type SleepSummary

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is used to access the Fitbit API

func NewClient

func NewClient(config Config) *Client

NewClient creates new API client

func (Client) GetHeartRateLogs

func (client Client) GetHeartRateLogs(date time.Time, resolution DataResolution) ([]HeartRateMeasurement, error)

GetHeartRateLogs returns all heartrate time series for a given date

func (Client) GetSleepLogs

func (client Client) GetSleepLogs(date time.Time) ([]SleepLogEntry, error)

GetSleepLogs returns all sleep logs for a specific date

type Config

type Config struct {
	CallbackServerPort int
	ClientID           string
	ClientSecret       string
	Scopes             []Scope
	TokenPath          string
}

Config is the API client config

type DataResolution

type DataResolution = string

DataResolution determines the granularity of the heart rate data

const (
	OneSecondResolution DataResolution = "1sec"
	OneMinuteResolution DataResolution = "1min"
)

Available resolution levels

type HeartRateMeasurement

type HeartRateMeasurement struct {
	Date  LocalTime `json:"time"`
	Value int       `json:"value"`
}

HeartRateMeasurement represents the heartrate at a point in time

type LocalDate

type LocalDate struct {
	time.Time
}

LocalDate is used to parse the date fields in the API

func (*LocalDate) UnmarshalJSON

func (date *LocalDate) UnmarshalJSON(data []byte) error

UnmarshalJSON parses the date string from the JSON response

type LocalTime

type LocalTime struct {
	time.Time
}

LocalTime is used to parse time fields in the API

func (*LocalTime) UnmarshalJSON

func (date *LocalTime) UnmarshalJSON(data []byte) error

UnmarshalJSON parses the time string from the JSON response

type MillisecondDuration

type MillisecondDuration struct {
	time.Duration
}

MillisecondDuration is used to parse millisecond durations in the API

func (*MillisecondDuration) UnmarshalJSON

func (duration *MillisecondDuration) UnmarshalJSON(data []byte) error

UnmarshalJSON parses the milliseconds int from the JSON response

type MinuteDuration

type MinuteDuration struct {
	time.Duration
}

MinuteDuration is used to parse minute durations in the API

func (*MinuteDuration) UnmarshalJSON

func (duration *MinuteDuration) UnmarshalJSON(data []byte) error

UnmarshalJSON parses the minutes int from the JSON response

type Scope

type Scope = string

Scope represents a specific resource permission

const (
	Activity  Scope = "activity"
	HeartRate Scope = "heartrate"
	Location  Scope = "location"
	Nutrition Scope = "nutrition"
	Profile   Scope = "profile"
	Settings  Scope = "settings"
	Sleep     Scope = "sleep"
	Social    Scope = "social"
	Weight    Scope = "weight"
)

All available scopes

type SecondDuration

type SecondDuration struct {
	time.Duration
}

SecondDuration is used to parse second durations in the API

func (*SecondDuration) UnmarshalJSON

func (duration *SecondDuration) UnmarshalJSON(data []byte) error

UnmarshalJSON parses the seconds int from the JSON response

type SleepData

type SleepData struct {
	Summary  map[SleepPhase]SleepSummary `json:"summary"`
	Timeline []SleepEvent                `json:"data"`
}

SleepData contains the summary and details for a sleep

type SleepEvent

type SleepEvent struct {
	Date     LocalDate      `json:"datetime"`
	Phase    SleepPhase     `json:"level"`
	Duration SecondDuration `json:"seconds"`
}

SleepEvent is a sleep phase in the sleep timeline

type SleepLogEntry

type SleepLogEntry struct {
	ID        int64               `json:"logId"`
	Duration  MillisecondDuration `json:"duration"`
	StartDate LocalDate           `json:"startTime"`
	EndDate   LocalDate           `json:"endTime"`
	Data      SleepData           `json:"levels"`
}

SleepLogEntry represents a single sleep

type SleepPhase

type SleepPhase = string

SleepPhase represents a sleep phase

const (
	Awake SleepPhase = "wake"
	Deep  SleepPhase = "deep"
	Light SleepPhase = "light"
	REM   SleepPhase = "rem"
)

Enum of all sleep phases

type SleepSummary

type SleepSummary struct {
	Count    int            `json:"count"`
	Duration MinuteDuration `json:"minutes"`
}

SleepSummary is the summary of a sleep phase