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.