/ 
WebService-Beeminder-0.002
River stage one • 1 direct dependent • 1 total dependent
/ WebService::Beeminder

NAME

WebService::Beeminder - Access the Beeminder API

VERSION

version 0.002

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 danced $result->[-1]{timestamp} seconds from the epoch at " .
    $result->[-1]{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();

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']
}

Note: Presently only basic parameters are returned, even though the beeminder API supports additional filters.

datapoints

my $results = $bee->datapoints($goal);

This method returns an array reference of data points for the given goal:

[
    {  
        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 for 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.