Today’s Advent Calendar post is about Beeminder’s API, which is generally an advanced topic but it can be used for certain things with little technical knowledge. This post is long but I think it should be easy-ish to understand.
I’ll be mentioning the API in at least one future Advent post so you may find today to be a helpful introduction. I’m hoping that the instructions I give here will be all you’ll need to know, so if you have any questions (today or at any future time), post a comment here. Also, if you can suggest improvements to these instructions, I would love for you to comment! The Windows instructions especially might benefit from adjustments - I rarely use Windows.
An API (Application Programming Interface) is a way to interact with a website using a script, sometimes a simple script. Here’s some generic points about APIs, with specific examples for Beeminder:
- Any website that has its own API will provide documentation about how to use it.
- Beeminder’s is here: https://api.beeminder.com (but don’t worry if that looks complex at first glance)
- An API will include a secure way for identifying your account and permitting your script to use that account (authentication). This is typically a userid / username and a secret “Auth Token” (or “API Token”).
- For Beeminder, your API username is your name that you see in your goal URLs (e.g., my aerobics goal is www.beeminder.com/alys/aerobic and that shows my username is “alys”). Usernames don’t need to be kept private.
- For Beeminder, your Auth Token can be found by going to your Account Settings and clicking on the Apps & API tab, and looking there for the “Personal Auth Token”. It will look something like
AbC12-abcd1234efgHIJ(that’s a made up example). Do not tell anyone what your Token is, not even if you’re emailing Beeminder support for help! It’s like a password and only you should use it. - Beeminder’s API has a handy feature that when you are using your Auth Token, you don’t actually need to specify your username. You can use “me” instead of your username, as you’ll see in the example below. This makes it easier to copy an API example that someone else has been using - you have to change some details in it, but not the username!
- An API will include methods for reading (fetching) data from your account - often several different methods, each for a different type of data.
- For example, Beeminder’s API has a method for fetching a list of your goals, another method for fetching all information about one specific goal, etc.
- An API will also include methods for adding or editing or deleting information in your account.
- For example, Beeminder’s API has a method for adding a datapoint to a specific goal, another method for deleting a datapoint, etc.
Adding a datapoint to a specific goal is easy with Beeminder’s API. The example below is for my “aerobic” goal, which has hours as its units. This example adds a datapoint with a value of “2.5” (2 hours and 30 minutes) and the comment “running on treadmill”. The different parts of the example are explained just below.
curl.exe -X POST
https://www.beeminder.com/api/v1/users/me/goals/aerobic/datapoints.json
-d auth_token="AbC12-abcd1234efgHIJ"
-d value="2.5"
-d comment="running on treadmill"
The important points about the example are:
- it uses a program called “curl.exe” which should be already installed on any modern Windows computer (see below for Linux and MacOS)
- the URL (starting with
https://) is how you specify which API method you want to use -
aerobicin the URL - that’s the goalname of my goal, and you can replace it with the goalname of any one of your goals (be careful to not delete the / characters on either side of it) - the text
"AbC12-abcd1234efgHIJ"- replace that with your own Auth Token (be sure to keep the quote marks around it) - the value
"2.5"- replace that with whatever value your datapoint should have (keep the quote marks) - the text
"running on a treadmill"- replace that with whatever comment your datapoint should have (keep the quote marks) - the example has line breaks for easy viewing, but the entire command should be on a single line OR it should use your operating system’s way of correctly splitting a command into multiple lines (see this comment from clivemeister)
- the other parts of the command should not be changed when you are adding a datapoint, but other API methods may require changes (e.g., if you are using a method to fetch data, you may need to replace
POSTwithGET)
So, what you can do is copy that command to a plain-text editor (e.g., Notepad) and edit it to specify:
- your own goalname
- your own Auth Token
- your desired datapoint value
- your datapoint comment
Then replace the line breaks with spaces so it’s all on a single line (or use appropriate end-of-line characters to allow it to be a multi-line command).
Copy the entire command to your clipboard.
Open the Windows Command Prompt and paste the command in.
Hit enter to make the command run.
It should then add the datapoint to your goal. Check your goal from your Beeminder dashboard to see if it worked.
The date for the datapoint will be today’s date. It is possible to specify a different date, but that’s a bit more advanced and isn’t needed for recording any actions you took today.
If you’re using Linux, Curl might be installed by default but it’s called just “curl” not “curl.exe” - i.e., remove “.exe” from the example above. Run the command in a Terminal window.
When you run the command, if you see an error message saying “curl: command not found” then you can install curl by entering “sudo apt install curl” into the Terminal (assuming you’re using Ubuntu Linux).
If you’re using Mac OS, Curl should already be installed, and is called “curl” not “curl.exe” as for Linux.
So, that command is how I would use the API to enter an aerobic goal datapoint for 2.5 hours of running on a treadmill. Did I mention this is a fictional example? 
I often use this method for entering Pessimistic Presumption (PP) datapoints in Do More Goals. I’ll typically enter the same value (e.g., -99) and the same comment (“#SELFDESTRUCT”) for the same goals each day, so I’ll use the same curl commands each day. On Linux, I can put the curl commands into a file, give the file execute permissions to make it a simple shell script, and run it each morning - much easier than manually adding the PP datapoints to the goals every day.
Here’s a PP example for my aerobics goal, which also shows the entire command correctly on a single line:
curl.exe -X POST https://www.beeminder.com/api/v1/users/me/goals/aerobic/datapoints.json -d auth_token="AbC12-abcd1234efgHIJ" -d value="-99" -d comment="#SELFDESTRUCT"
Remember that your Auth Token should never be shared with anyone. If you do accidentally let someone see it, go straight back to your Account Settings > Apps & API page and click the “REGENERATE” button. That will give you a new Auth Token and will stop your old one from being usable (I think!).
This is the first time I’ve tried to explain Beeminder’s API to anyone, so I may well have left out information that you need to know. Post a comment if anything doesn’t seem clear or correct!
EDIT 2022-12-18:
See Advent 2022: 18. Bash Script to Display Coloured Plain-Text Beeminder Dashboard for a script that uses an API command to fetch data about all your goals, including recent datapoints.