gitpan / webservice-fitbit Goto Github PK

NAME
    WebService::FitBit - OO Perl API used to fetch fitness data from
    fitbit.com

VERSION
    version 0.1_5

SYNOPSIS
        use WebService::FitBit;

        # pulls default config from ~/.fitbit -- init that first, with
        # 'initialize_fitbit_config_file' command
        my $fb = WebService::FitBit->new();

        # No date defaults to today
        my $log = $fb->intraday_calories_burned();
        foreach ($log->all_items) {
            printf "time = %s -> calories = %s\n" , $_->time , $_->value;
        }

        printf "calories burned = %s\n" , $fb->calories_burned('2010-05-03');
        printf "active score    = %s\n" , $fb->active_score('2010-05-03');
        printf "steps           = %s\n" , $fb->steps_taken('2010-05-03');

DESCRIPTION
    "WebService::FitBit" provides an OO API for fetching fitness data from
    fitbit.com. Currently there is no official published API.
    "WebService::FitBit" works by accssing the XML feeds that drive the
    Flash/JavaScript-based interface at fibit.com. That means that changes
    to the location of format of those XML feeds could produce errors --
    caveat user.

    Intraday (5min and 1min intervals) logs are provided for:

     - calories burned
     - activity score
     - steps taken
     - sleep activity (every 1 min)

    Historical (aggregate) info is provided for:

     - calories burned / consumed
     - activity score
     - steps taken
     - distance travels (miles)
     - sleep (total time in hours, and times awoken)

METHODS
  new
        my $fb = WebService::FitBit->new();
        my $fb = WebService::FitBit->new({ config => 'alternate/file/location' });
        my $fb = WebService::FitBit->new({
          sid     => $sid ,
          uid     => $uid ,
          user_id => $user_id ,
        });

    Returns a WebService::FitBit object. Generally you'll want to use the
    default form, which pulls required parameters out of a file called
    '.fitbit' in your home directory (using the value obtained from
    "File::HomeDir"). There is a helper command included in the dist --
    "initialize_fitbit_config_file" -- which will prompt for an account name
    and password and then use those to retrieve the required values from
    <http://fitbit.com>

    If you prefer, you can specify an alternate config file location with
    the 'config' parameter, or specify the required 'sid', 'uid', and
    'user_id' values directly.

    If 'sid', 'uid', or 'user_id' parameters are supplied, they will
    override any parameters read from the config.

  active_score
        $score = $fb->active_score();
        $score = $fb->active_score('2010-10-20');

    Returns the active score for a given date. Defaults to current date if
    none given.

  activities_breakdown
        my $activities_breakdown_hash = $fb->activities_breakdown();
        my $activities_breakdown_hash = $fb->activities_breakdown('2010-10-20');

    Returns a hashref summarizing what percentage of the given date was
    spent in each of four activity level categories: 'sedentary', 'lightly',
    'fairly', and 'very'. If no date is given, defaults to the current date.

    NOTE: The four values in the hash will sum to (approximately) 100, not
    1. That is, if half of the date was in the 'sedentary' level, the
    'sedentary' key in the hashref would have a value of '50'.

  calories_burned
        $calories_burned = $fb->calories_burned();
        $calories_burned = $fb->calories_burned('2010-10-20');

    Returns the number of calories burned on the given date. Defaults to the
    current date if none given.

  calories_consumed
        $calories_consumed = $fb->calories_consumed();
        $calories_consumed = $fb->calories_consumed('2010-10-20');

    Returns the number of calories consumed on the given date. Defaults to
    the current date if none given.

  calories_in_out
        $calories_in_out_hashref = $fb->calories_in_out();
        $calories_in_out_hashref = $fb->calories_in_out('2010-10-20');

    Returns a hashref with information about calories burned and consumed on
    the given day. Calories burned are under the 'burned' key; calories
    consumed are under the 'consumed' key.

  distance_from_steps
        $distance_in_miles = $fb->distance_from_steps();
        $distance_in_miles = $fb->distance_from_steps('2010-10-20');

    Returns the distance walked on the given date, in miles. Defaults to the
    current date, if none given.

  intraday_active_score
      @intraday_active_scores = $fb->intraday_active_score();
      @intraday_active_scores = $fb->intraday_active_score('2010-10-20');

    Returns a WebService::FitBit::IntradayLog object containing
    WebService::FitBit::IntradayLog::Item objects with the active score for
    5 minute intervals throughout the day.

    Note that when requesting data for the current day, you still get the
    full range of time values, even though some of them haven't occurred
    yet.

    Takes a date argument; defaults to the current date if none is given.

  intraday_calories_burned
      @intraday_calories_burned = $fb->intraday_calories_burned();
      @intraday_calories_burned = $fb->intraday_calories_burned('2010-10-20');

    Returns a WebService::FitBit::IntradayLog object containing
    WebService::FitBit::IntradayLog::Item objects with the calories burned
    for 5 minute intervals throughout the day.

    Note that when requesting data for the current day, you still get the
    full range of time values, even though some of them haven't occurred
    yet.

    Takes a date argument; defaults to the current date if none is given.

  intraday_sleep
    NOT YET IMPLEMENTED. Patches welcomed.

  intraday_steps
      @intraday_steps = $fb->intraday_steps();
      @intraday_steps = $fb->intraday_steps('2010-10-20');

    Returns a WebService::FitBit::IntradayLog object containing
    WebService::FitBit::IntradayLog::Item objects with the steps taken for 5
    minute intervals throughout the day.

    Note that when requesting data for the current day, you still get the
    full range of time values, even though some of them haven't occurred
    yet.

    Takes a date argument; defaults to the current date if none is given.

  minutes_active
        $minutes_active_hashref = $fb->minutes_active();
        $minutes_active_hashref = $fb->minutes_active('2010-10-20');

    Returns a hashref containing information about the time spent in the
    'lightly', 'fairly', and 'very' activity levels for the given date.
    Defaults to the current date if none given.

    Values are expressed in fractional hours. I.e., if the 'very' key has a
    value of '0.50', that indicates that 30 minutes were spent in that
    activity level.

  steps_taken
        $steps_taken = $fb->steps_taken();
        $steps_taken = $fb->steps_taken('2010-10-20');

    Returns the number of steps taken on the given date. Defaults to the
    current date if none given.

  time_asleep
        $hours_asleep = $fb->time_asleep();
        $hours_asleep = $fb->time_asleep('2010-10-20');

    Returns the amount of time spent asleep on the given day. Defaults to
    the current date if none given.

    The value is expressed in fractional hours. I.e., a value of 7.5
    indicates 7 hours and 30 minutes spent asleep.

    TODO Currently unclear if this value is the sum of all sleeps on a given
    day or just the value from the first or the value from the longest.

  times_woken_up
        $times_woken_up = $fb->times_woken_up();
        $times_woken_up = $fb->times_woken_up('2010-10-20');

    Returns the number of times woken up on the given day. Defaults to the
    current date if none given.

    TODO Currently unclear if this value is the sum of all sleeps on a given
    day or just the value from the first or the value from the longest.

  weight
        $weight = $fb->weight();
        $weight = $fb->weight('2010-10-20');

    Returns the weight value for a given date, or the current date if none
    is given.

    Note that the value returned for a day where no explict value was
    entered is an interpolation done on the FitBit server side. Currently
    there is no way to retrieve only the data that was explictly entered.

INTRADAY LOGS
    "intraday_*" methods return 'WebService::FitBit::IntradayLog' objects.
    That object has one useful method, 'all_items', which returns a list of
    'WebService::FitBit::IntradayLog::Item' objects. Those objects support
    'time' and 'value' accessors.

    To print out the calories burned during five minute intervals, you can
    do something like:

        my $log = $fb->intraday_calories_burned();
        for my $item ( $log->all_items ) {
          printf "%S -> %S\n" , $item->time , $item->value;
        }

    Over time, the 'WebService::FitBit::IntradayLog' object will likely be
    extended with convenience methods such as 'max', 'min', 'average', and
    so on. Suggestions and/or patches are welcomed.

KNOWN_ISSUES
    At this time, if you attempt to tally the intraday (5min) logs for the
    total daily number, this number will NOT match the number from the
    equivalent API call for the total number. This is due to the way that
    FitBit feeds the intraday values via XML to the flash-graph chart. All
    numbers are whole numbers, and this rounding issue causes the detailed
    log tally to be between 10-100 points higher.

    For example:

        # Calling total = 2122
        print "Total calories burned = " . $fb->calories_burned . "\n";

        # Tallying total from log entries = 2157
        my $total = 0;
        for my $item ( $fb->intraday_calories_burned->all_items ) {
          $total += $item->value;
        }

CREDITS
    Eric Blue did the initial version of this module, which solved most of
    the annoying issues around deciphering the URL parameters and XML
    formats.

SEE ALSO
    The FitBit site <http://fitbit.com>

    Eric's original announcement
    <http://eric-blue.com/2010/05/11/fitbit-unofficial-perl-api-and-csv-down
    load/>

AUTHORS
    *   John SJ Anderson <[email protected]>

    *   Eric Blue <[email protected]>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2010 by John SJ Anderson.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.