NAME

WebService::Beeminder - Access the Beeminder API

VERSION

version 0.001

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
    }

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

• The Beeminder API

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.

cpanm WebService::Beeminder

perl -MCPAN -e shell
install WebService::Beeminder