++ed by:
Paul Jamieson Fenwick


WebService::Beeminder - Access the Beeminder API


version 0.003


    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 " .


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.



    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'.


    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


    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


   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.


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.



Paul Fenwick <pjf@cpan.org>


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.

Hosting generously
sponsored by Bytemark