The fundraising amount shown on Beats Per Mile uses the JustGiving API to show the up-to-date figure on Gemma’s donation page.

By way of one of their various SDKs, the JustGiving API is a doddle to use and is pretty well featured. Unfortunately the documentation isn’t particularly comprehensive.

You can expect to be able to fetch any information found on a typical page — event and charity details, lists of donations and comments, even the colour scheme — all of which can be fetched without any need for authentication.

We’re using the PHP SDK to show a very simple totaliser, the current percentage raised of the target amount. This can be achieved in just a few lines of code.

Firstly you need to register your application, which will get you an API key and access to the staging sandbox. This access is only for development, you can query live pages but the information you’ll obtain is out-of-date.

Applications go through a two day approval process but require nothing more than an decent application description, from that point on you’re free to access real pages and live data.

The PHP SDK is available from GitHub and comes with plenty of examples and cover a lot of use cases for data queries.

As I say, the API offers plenty more, such as automatic page creation, user account creation and integrating donations from third-party sites.

Our needs are far simpler, however. The code is exactly this:

include ‘./JustGivingClient.php’;

$client = new JustGivingClient(“https://api.justgiving.com/”, “API_KEY”, 1);
$page = $client->Page->Retrieve(“Gemma-Bardsley”);
$funds = $page->grandTotalRaisedExcludingGiftAid;
$target = round($page->fundraisingTarget);
$percent_raised = round($funds/$target * 100);

As simple as querying the page, grabbing the current total and the target total then determining the percentage.

We retrieve the page via it’s short name, which for us is “Gemma-Bardsley”, this will be set in the JustGiving page admin area.

Note that the target amount has to be explicitly set there too (you’ll get a similar totaliser on your fundraising page anyway if that’s set correctly) and this queries the live API staging over HTTPS, not the developer sandbox.

The third parameter sent to the client constructor specifies version one of the API.

I went out for a ride and I never went back.