Alex Lomas > WWW-Nike-NikePlus-0.04a > WWW::Nike::NikePlus

Download:
WWW-Nike-NikePlus-0.04a.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.04   Source  

NAME ^

WWW::Nike::NikePlus - Perl extension for retrieving running data from www.nikeplus.com

SYNOPSIS ^

Example use that retrieves and prints your last run information

  use WWW::Nike::NikePlus;
  my $username = 'my@email.address';
  my $password = 'MySecretPassword';
  my $locale = "en_us";
  
  my $pin = nike_authenticate( $username, $password, $locale );
  unless( $pin ) { print "Authentication failed\n"; }
  
  #Details of the last run
  my ( $unit, $last_run_dist, $last_run_duration_millisecs, 
        $last_run_duration_friendly, $last_run_pace_friendly ) = nike_last_run();
  
  print "Last run: $last_run_dist$unit in $last_run_duration_friendly\n";
  print "Last run pace: $last_run_pace_friendly per $unit\n";

DESCRIPTION ^

This module provides a Perl interface to the Nike+ running site and allows you to query most of the data exposed by the Nike+ web API.

You can: Authenticate to Nike+ and obtain the login token and cookie Retrieve your last run Retrieve your personal settings (name, perferred units, avatar etc.) Retrieve data on all your runs, ever Get specific pace information on a run (not yet implemented, sorry!) List all your goals and whether you've completed them or not List all your challenges See who's taking part in your challenges, and how they're doing Display direct URL links to home page/runs/goals/challenges that use the token to bypass login (CAUTION!)

FUNCTIONS ^

This module provides all the following functions, which are all exported by default when you call use WebService::NikePlus;.

nike_authenticate( username, password, locale )

Carries out the authentication against Nike+ with the provided username, password and locale.

Returns the pin (token) if successful, or undef if authentication failed

You must call nike_authenticate() before calling any of the other functions.

nike_web_links( pin )

Once authenticated and you have $pin, you can call nike_web_links( $pin ) to return direct URLs to various www.nikeplus.com web pages.

E.g. to find out the URLs for the front, challenge, goals and runs pages bypassing authentication:

        ( $front_page, $chals_page, $goals_page, $runs_page ) = nike_web_links( $pin )

Exercise caution if using this module with (for example) a public facing CGI script. By obtaining the pin/token and following these URLs anyone would be able to access your Nike+ account!

nike_last_run()

Retrieve details for the last run.

Returns: ( distance unit, last run distance, last run time (in ms), last run time (in friendly format), last run pace (mins/secs per km/mi) (in friendly format) )

E.g. to find out everything about your last run:

        ( $unit, $last_run_dist, $last_run_duration_millisecs, $last_run_duration_friendly, $last_run_pace_friendly ) = nike_last_run()
nike_run_totals()

Retrieve lifetime run totals

Returns: ( total number of runs, total distance run, total run tims (in ms), total run time (in friendly format)

E.g. to find out how far and how long you've run all time:

        ( $total_run_num, $total_run_dist, $total_run_duration_millisecs, $total_run_duration_friendly ) = nike_run_totals()
nike_run_averages()

Retrieve lifetime run averages

Returns: ( distance unit, average distance per run, average time per run (ms), average time per run (friendly), average pace (mins/secs / km/mi)

E.g. to find out your overall averages across every run you've ever done:

        ( $unit, $average_dist, $average_time_millisecs, $average_time_friendly, $average_run_pace_friendly ) = nike_run_averages()
nike_runs_list()

Retrieve list of all runs to date, with basic details

Returns: ( hash ref of data, total number of runs)

Hash ref data structure:

        $data = { 
                run_number (starts at 0) => {
                                        synctime => datetime,
                                        distance => number (use $unit from nike_last_run() ),
                                        name => text (user specified name),
                                        calories => number (cals calculated to be burnt, requires weight to be specified),
                                        duration => number (run length in ms),
                                        starttime => datetime,
                                        nike_id => number (unique ID for each run, use with nike_run_detail() ),
                                        description => text,
                                        },
        };

E.g. to print out the distances of each run you've done:

        my ( $run_data_ref, $run_num ) = nike_runs_list();
        my %run_data = %$run_data_ref;
        my $run = 0;
        while ( $run < $run_num ) {     
                print $run_data{$run}{distance};
                print "\n";
                $run++; 
        }
nike_run_detail( run_id )

Not yet impletemented

Will eventually take a run id (see nike_runs_list()) and output data so that you can see how you performed over the course of a run. This is not implemented for now as the web interface at Nike+ does a much better job at graphing than I can manage!

nike_user_goals()

Retrieve a list of all your goals

Returns: ( hash ref of data, total number of goals, number of completed goals)

Hash ref data structure:

        $data = { 
                goal_number (starts at 0) => {
                                                level => number,
                                                endtime => datetime,
                                                starttime => datetime,
                                                complete => boolean,
                                                type => text,
                                                progress => text,
                                                },
        };

E.g. to list all the types you have:

        my ( $goal_data_ref, $num_of_goals, $goals_complete ) = nike_user_goals();
        print "$goals_complete/$num_of_goals goals completed\n";
        my %goal_data = %$goal_data_ref;
        my @goal_ids = keys %goal_data;
        foreach my $goal ( @goal_ids ) {
                print $goal_data{$goal}{type};
                print "\n";
        }
nike_user_challenges()

Retrieve a list of all your challenges

Returns: ( hash ref of data, number of challenges )

Hash ref data structure:

        $data = { 
                challenge_name  => {
                                        owner => text,
                                        greeting => text,
                                        status => boolean,
                                        active => boolean,
                                        level => number,
                                        starttime => datetime,
                                        status => boolean,
                                        id => number (unique ID for each challenge, use with nike_chal_detail() ),
                                        comparator => number,
                                        unit => text (km or mi),
                                        type => text,
                                        quickchallenge => boolean,
                                        },
        };

E.g. to display all the challenge IDs you're associated with:

        my ( $chal_data_ref, $num_of_chals ) = nike_user_challenges();
        my %chal_data = %$chal_data_ref;
        my @chal_names = keys %chal_data;
        foreach my $challenge ( @chal_names ) {
                print "$chal_data{$challenge}{id}\n";
        }
nike_chal_detail( challenge_id );

Retrieve detailed list of participants in a challenge. Required argument of the challenge ID - use nike_user_challenges() above to obtain list of all challenges and their IDs.

Returns: ( hash ref of data, number of challengers )

Hash ref data structure:

        $data = { 
                member_name  => {
                                        email => text,
                                        invcode => text,
                                        progress => number,
                                        status => boolean,
                                        screenname => text,
                                        gender => text,
                                        isowner => boolean,
                                        },
        };

E.g. to list the (first part) of each challenger's email address and their progress so far for a given challenge ID:

        my ( $chal_detail_ref, $number_of_challengers) = nike_chal_detail( 123456 );
        my %chal_detail = %$chal_detail_ref;
        my @member_names = keys %chal_detail;
        foreach my $member ( @member_names ) {
                print $chal_detail{$member}{email};
                print ": ";
                print $chal_detail{$member}{progress};
                print "\n";
        }

SEE ALSO ^

http://www.nikeplus.com

AUTHOR ^

Alex Lomas<alexlomas at cpan dot org>

COPYRIGHT AND LICENSE ^

Copyright (C) 2007 by Alex Lomas

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

syntax highlighting: