NAME
WebService::Beeminder - Access the Beeminder API
VERSION
version 0.003
SYNOPSIS
my $bee = WebService::Beeminder->new( token => $token );
# I flossed my teeth today.
$bee->add_datapoint( goal => 'floss', value => 1 );
# When did I last take dance lessons?
my $result = $bee->datapoints('dance');
say "I last went dancing on $result->[0]{timestamp} with a comment of " .
$result->[0]{comment};DESCRIPTION
This is a thin-ish wrapper around the Beeminder API. All results are exactly what's returned by the underlying API, with the JSON being converted into Perl data structures.
You need a Beeminder API token to use this module. The easiest way to get a personal token is just to login to Beeminder and then go to https://www.beeminder.com/api/v1/auth_token.json. Copy'n'paste the token into your code (or a config file your code uses), and you're good to go!
More information on tokens is available in the Beeminder API documentation.
METHODS
user
my $result = $bee->user(
goals_filter => 'frontburner', # or 'backburner', or 'all' (default)
diff_since => $last_check, # Seconds from the epoch. Default: 'null'
skinny => 1, # Return slimmed info. Default: 'false'
);All arguments are optional.
Obtains information about the current user. This returns a user resource (as defined by the Beeminder API), which looks like this:
{
username => "alice",
timezone => "America/Los_Angeles",
updated_at => 1343449880,
goals => ['gmailzero', 'weight']
}If diff_since is specified, then the goals will be a list of hashes, rather than just a simple list of goals.
Note that the associations parameter specified in the API is currently not supported as it results in excessively slow server responses, even when set to 'false'.
datapoints
my $results = $bee->datapoints($goal);This method returns an array reference of data points for the given goal. At the time of writing, the Beeminder API returns the most recent data point in the first position in the array.
[
{
id => 'abc123'
timestamp => 1234567890,
value => 1.1,
comment => "Frobnicated a widget",
updated_at => 1234567890
},
{
id => 'abc124'
timestamp => 1234567891,
value => 1.2,
comment => "Straightened my doohickies",
updated_at => 1234567891
},
]add_datapoint
my $point = $bee->add_datapoint(
goal => 'floss',
timestamp => time(), # Optional, defaults to now
value => 1,
comment => 'Floss every tooth for great justice!',
sendmail => 0, # Optional, defaults to false
);Adds a data-point to the given goal. Mail will be sent to the user if the sendmail parameter is true.
Returns the data-point that was created:
{
id => 'abc125'
timestamp => 1234567892,
value => 1,
comment => 'Floss every tooth for great justice!'
updated_at => 1234567892
}goal
my $results = $bee->goal('floss', datapoints => 0);Returns information about a goal. The optional datapoints parameter can be supplied with a true value to also fetch datapoints for that goal.
Goal objects are complex data structures, and are described in the Beeminder API documentation.
INSTALLATION
This module presently uses MooseX::Method::Signatures. If you're not experienced in installing module dependencies, it's recommend you use App::cpanminus, which doesn't require any special privileges or software.
Perl v5.10.0 or later is required to use this module.
SEE ALSO
AUTHOR
Paul Fenwick <pjf@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 by Paul Fenwick.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.