WWW::Nike::NikePlus - Perl extension for retrieving running data from www.nikeplus.com
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";
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!)
This module provides all the following functions, which are all exported by default when you call use WebService::NikePlus;.
use WebService::NikePlus;
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_authenticate()
Once authenticated and you have $pin, you can call nike_web_links( $pin ) to return direct URLs to various www.nikeplus.com web pages.
nike_web_links( $pin )
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!
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()
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()
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()
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++; }
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!
Retrieve a list of all your goals
Returns: ( hash ref of data, total number of goals, number of completed goals)
$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"; }
Retrieve a list of all your challenges
Returns: ( hash ref of data, number of challenges )
$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"; }
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 )
$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"; }
http://www.nikeplus.com
Alex Lomas<alexlomas at cpan dot org>
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.
To install WWW::Nike::NikePlus, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WWW::Nike::NikePlus
CPAN shell
perl -MCPAN -e shell install WWW::Nike::NikePlus
For more information on module installation, please visit the detailed CPAN module installation guide.