NAV
php ruby python

Introduction

Welcome to the WhatPulse Developer Center! Here you will learn about the APIs we have available; the Web API, Client API and local database schema for the client.

We currently have examples for PHP, Ruby and Python. If you made any awesome examples yourself and want to share them with the world, contact us at info@whatpulse.org.

Client API

The Client API is a lightweight JSON API that is available on the WhatPulse client (version 2.7 and above) to retrieve real-time statistics from your local computer. It is a small web server that is embedded in the client and is disabled by default. You will need to enable it before attempting to make a connection, see our Help Center for more information on the setting. The Client API does not need authentication, only enabling and the connecting IP address has to be allowed.

Once it is enabled, you can visit the main index webpage to get a list of all available API calls. By default, this index can be found here: http://localhost:3490/. At this moment, these are the possible API calls:

Endpoint HTTP Method Description
/ GET Index of all possible calls
/v1/account-totals GET Get all total account stats
/v1/unpulsed GET Get all unpulsed stats
/v1/pulse POST Execute a pulse

Let’s dive into each one separately in the next chapters.

Status Codes

Before we go into the available API calls, here’s an overview of the possible status codes the client can return:

HTTP Status Code Description
200 Call success, result is in the body
401 Connecting IP address not allowed in the client settings
404 Invalid URL
405 Invalid HTTP Method (only GET and POST are allowed)

Account Totals

Retrieving the account total stats:

<?php
  // TODO: error handling
  $json   = file_get_contents("http://localhost:3490/v1/account-totals");
  $result = json_decode($json);
  $keys   = $result->keys;
  $clicks = $result->clicks;
  $rank_uptime = $result->ranks->rank_uptime;
  echo "Current keys: ".$keys.", current clicks: ".$clicks.", rank in uptime: ".$rank_uptime;
?>
require 'httparty'

request = HTTParty.get('http://localhost:3490/v1/account-totals')
keys    = request['keys']
clicks  = request['clicks']
rank_uptime = request['ranks']['rank_uptime']

puts "Current keys: #{keys}, current clicks: #{clicks}, rank in uptime: #{rank_uptime}"
import requests

request = requests.get('http://localhost:3490/v1/account-totals').json()
keys = request['keys']
clicks = request['clicks']
rank_uptime = request['ranks']['rank_uptime']

print("Current keys: {}, current clicks: {}, rank in uptime: {}".format(keys,
clicks, rank_uptime))

JSON Result:

{
  "clicks":"11696357",
  "download":"2395411",
  "keys":"56008172",
  "ranks":
  {
    "rank_clicks":"3070",
    "rank_download":"4819",
    "rank_keys":"530",
    "rank_upload":"3729",
    "rank_uptime":"1704"
  },
  "upload":"828733",
  "uptime":"60513152"
}

In the Account tab, the client displays the total statistics of your account. Each time the client pulses, these stats are updated. Get your total clicks, keys, download (in MB), upload (in MB), uptime (in seconds) and the online rankings on all those stats.

HTTP Request

GET http://localhost:3490/v1/account-totals

Results

If successful, this call will return a JSON formatted array with the total keys, clicks, download, upload, uptime and the ranks of your account. These values are updated from the website each time you pulse.

Executing a Pulse

Executing a pulse:

<?php
  $url = "http://localhost:3490/v1/pulse";
  $curl = curl_init($url);

  curl_setopt($curl, CURLOPT_POST, 1);
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($curl);
  curl_close($curl);

  $result = json_decode($response);
?>
require 'httparty'

result = HTTParty.post('http://localhost:3490/v1/pulse')
import requests

result = requests.post('http://localhost:3490/v1/pulse').json()

JSON Result:

{
  "msg": "Pulse executed."
}

You can remotely execute a pulse via the Client API.

HTTP Request

POST http://localhost:3490/v1/pulse

Results

If successful, this call will return a JSON formatted array with the field “msg” which displays the pulse is successful or not. Please note that at this time, it will always return “Pulse executed.” - as pulsing is an asynchronous process and the API call does not wait around for the result. Future versions will return the actual result of the pulse.

Unpulsed Stats

Retrieving the unpulsed stats:

<?php
  $json   = file_get_contents("http://localhost:3490/v1/unpulsed");
  $result = json_decode($json);
  $keys   = $result->keys;
  $clicks = $result->clicks;
  echo "Current keys: ".$keys.", current clicks: ".$clicks;
?>
require 'httparty'

result = HTTParty.get('http://localhost:3490/v1/unpulsed')
keys   = result['keys']
clicks = result['clicks']

puts "Current keys: #{keys}, current clicks: #{clicks}"
import requests

result = requests.get('http://localhost:3490/v1/unpulsed').json()
keys = result['keys']
clicks = result['clicks']

print("Current keys: {}, current clicks: {}".format(keys, clicks))

JSON Result:

{
  "clicks":3474,
  "download":3444883866,
  "keys":22061,
  "upload":230877183,
  "uptime":22346
}

The stats that are accumulated between pulses is accessible through this call. Get the unpulsed clicks, keys, download (in bytes), upload (in bytes) and uptime (in seconds).

HTTP Request

GET http://localhost:3490/v1/unpulsed

Results

If successful, this call will return a JSON formatted array with the current unpulsed keys, clicks, download (in bytes), upload (in bytes) and uptime (in seconds). These values are updated in real-time.

Web API

The Web API can be used to retrieve raw data from WhatPulse on users, teams and pulses. You can use this API to show statistics on your website, blog or use it for your own applications. In the following examples, we will assume that you want to display your statistics on a website. We will also assume that you have some working knowledge of web development.

Below is a list of available URLs to request stats:

URL HTTP Method Description
http://api.whatpulse.org/user.php GET Retrieve user statistics
http://api.whatpulse.org/team.php GET Retrieve team statistics
http://api.whatpulse.org/pulses.php GET Retrieve a list of pulses made by a user or team

Let’s dive into each one separately in the next chapters.

Caching

To prevent overloading our servers, the API has a built in caching method. The cache duration is currently set to 1 hour. This means that the first time you retrieve the stats of a certain user, the API output will not update for 1 hour (even if the user has pulsed).

Errors

If something doesn’t go as planned, the Web API can display several errors. While the actual error messages are specific to each API call and are specified in the call chapter, they all look like below. You should test the output of your calls for the error field.

JSON

{ "error": "This is the error message"}

XML

<?xml version="1.0"?> <WhatPulse> <error>This is the error message</error> </WhatPulse>

Team Stats

Retrieving the stats of a team:

<?php
  // JSON example
  $json   = file_get_contents("http://api.whatpulse.org/team.php?team=whatnet&formatted=yes&format=json");
  $result = json_decode($json);
  if(!empty($result->error))
  {
    echo "Something went wrong: ".$result->error;
  }
  else
  {
    $name   = $result->Name;
    $users  = $result->Users;
    $rank_keys = $result->Ranks->Keys;
    echo "Team ".$name." has ".$users." users and is in the ".$rank_keys." place in the global rankings.";
  }
?>
require 'httparty'

result = HTTParty.get("http://api.whatpulse.org/team.php?team=whatnet&formatted=yes&format=json")

if result['error']
  puts "Something went wrong: #{result['error']}"
else
  name      = result['name']
  users     = result['users']
  rank_keys = result['Ranks']['Keys']

  puts "Team #{name} has #{users} users and is in the #{rank_keys} place in the global rankings."
end
import requests

result = requests.get("http://api.whatpulse.org/team.php?team=whatnet&formatted=yes&format=json").json()

if 'error' in result:
    print("Something went wrong: ", result['error'])
else:
    name = result['name']
    users = result['']
    rank_keys = result['Ranks']['Keys']

    print("Team {} has {} users and is in the {} place in the global rankings".format(name, users, rank_keys))

JSON Result:

{
  "TeamID":"12986",
  "Name":"Kongregate",
  "Description":"Kongregate is the team for WhatPulsers who like playing games and browsing the forums of the online gaming website Kongregate.com.",
  "Users":237,
  "Keys":2895182322,
  "Clicks":1317534407,
  "DownloadMB":168787961,
  "UploadMB":230624555,
  "Download":"160.97TB",
  "Upload":"219.94TB",
  "UptimeSeconds":3582843148,
  "UptimeShort":"113y31w6d2h12m28s",
  "UptimeLong":"113 years, 31 weeks, 6 days, 2 hours, 12 minutes, 28 seconds",
  "Ranks":
  {
    "Keys":"6",
    "Clicks":"7",
    "Download":"18",
    "Upload":"9",
    "Uptime":"9"
  },
  "DateFormed":"2007-12-17 00:00:00",
  "DateFormedUnixTimestamp":"1197846000",
  "Founder":"Jaume",
  "GeneratedTime":"2016-01-28 22:33:44",
  "SubTeams":
  {
    "subteam-0":
    {
      "SubTeamID":"46",
      "SubTeamName":"Bronies",
      "Founder":"Snailplant",
      "DateFormed":"2013-05-24 03:52:15",
      "DateFormedUnixTimestamp":"1369360335",
      "Users":"12",
      "Keys":"76541085",
      "Clicks":"24953172",
      "DownloadMB":"8316405.00",
      "UploadMB":"8566764.00",
      "Download":"7.93TB",
      "Upload":"8.17TB",
      "UptimeSeconds":"197041382",
      "UptimeShort":"6y12w6d13h43m2s",
      "UptimeLong":"6 years, 12 weeks, 6 days, 13 hours, 43 minutes, 2 seconds",
      "Ranks":
      {
        "Keys":1,
        "Clicks":1,
        "Download":1,
        "Upload":1,
        "Uptime":1
      }
    }
  }
}

This API endpoint gets you all statistics of a certain team. You can either specify a WhatPulse Team ID or a Team Name at the end of the URL.

HTTP Request

GET http://api.whatpulse.org/team.php?team=<teamid or name>

Results

If successful, the result will return a JSON or XML formatted body with the team statistics. The format for the JSON output you can check out on the right of this page. These values are updated from the website each time a member of the team pulses or joins/parts the team.

Available Options

Option Required Description
/team.php?team=<teamid or name> Y Get stats for a team name or team ID
/team.php?formatted=yes N Format all numbers. (turns 1000, into 1,000)
/team.php?format=xml N Outputs data in XML format (default)
/team.php?format=json N Outputs data in JSON format
/team.php?members=yes N Includes list of members. (can be a large page)

Errors

Error Description
No Team given! Please supply the team input field
Unknown TeamID given! The team was not found

Pulse Stats

Get a list of pulses of a user or an entire team:

<?php
  // JSON example
  $json   = file_get_contents("http://api.whatpulse.org/pulses.php?user=1&formatted=yes&format=json");
  $result = json_decode($json);
  if(!empty($result->error))
  {
    echo "Something went wrong: ".$result->error;
  }
  else
  {
    foreach($result as $pulse)
    {
      $time     = $pulse->Timedate;
      $computer = $pulse->Computer;
      $keys     = $pulse->Keys;
      echo "Found pulse at ".$time." from computer ".$computer." with ".$keys." keys\n";
    }
  }
?>
require 'httparty'

result = HTTParty.get('http://api.whatpulse.org/pulses.php?user=1&formatted=yes&format=json')

if result['error']
  puts "Something went wrong: #{result['error']}"
else
  result.each do |pulse|
    time     = pulse['Timedate']
    computer = pulse['Computer']
    keys     = pulse['Keys']

    puts "Found pulse at #{time} from computer #{computer} with #{keys}\n"
  end
end
import requests

result = requests.get('http://api.whatpulse.org/pulses.php?user=1&formatted=yes&format=json').json()

if 'error' in result:
    print('Something went wrong: ', result['error'])
else:
    for pulse in result:
        time = pulse['Timedate']
        computer = pulse['Computer']
        keys = pulse['Keys']

        print("Found pulse at {} from computer {} with {}\n".format(time, computer, keys))

JSON Result:

{
  "Pulse-232321427":
  {
    "Timedate":"2016-01-28 21:31:53",
    "Timestamp":"1454013113",
    "UserID":"1",
    "Username":"smitmartijn",
    "Computer":"mac",
    "OS":"osx",
    "Keys":"44318",
    "Clicks":"9074",
    "Download":"6GB",
    "DownloadMB":6240,
    "Upload":"467MB",
    "UploadMB":467,
    "UptimeSeconds":"54247",
    "UptimeShort":"15h4m7s",
    "UptimeLong":"15 hours, 4 minutes, 7 seconds"
  },
  "Pulse-232254817":
  {
    "Timedate":"2016-01-28 11:24:32",
    "Timestamp":"1453976672",
    "UserID":"1",
    "Username":"smitmartijn",
    "Computer":"grover",
    "OS":"osx",
    "Keys":"50000",
    "Clicks":"12471",
    "Download":"3GB",
    "DownloadMB":3563,
    "Upload":"890MB",
    "UploadMB":890,
    "UptimeSeconds":"112790",
    "UptimeShort":"1d7h19m50s",
    "UptimeLong":"1 day, 7 hours, 19 minutes, 50 seconds"
  }
}

This API endpoint allows you to get a list of pulses for a user or an entire team. This function accepts a username, user ID, team name or team ID. The amount of pulses returned is limited by a maximum of 100 records.

HTTP Request

GET http://api.whatpulse.org/pulses.php?team=<teamid or name> or user=<userid or username>

Results

If successful, the result will return a JSON or XML formatted body with a list of pulses with their stats. The format for the JSON output you can check out on the right of this page.

Available Options

Option Required Description
/pulses.php?team=<teamid or name> Y (or) Show pulses from all users inside a team, or:
/pulses.php?user=<userid or username> Y (or) Show pulses from a specific user
/pulses.php?formatted=yes N Format all numbers. (turns 1000, into 1,000)
/pulses.php?format=xml N Outputs data in XML format (default)
/pulses.php?format=json N Outputs data in JSON format
/pulses.php?start=<unix timestamp> N Show between a certain date. Needs to be used in conjunction with end
/pulses.php?end=<unix timestamp> N Show between a certain date. Needs to be used in conjunction with start

Errors

Error Description
No User or Team given! Please supply the user or team input field
Please provide ‘start’ as an unix timestamp! The start input field does not seem to be a timestamp
Please provide 'end’ as an unix timestamp! The end input field does not seem to be a timestamp
Timestamp 'end’ seems to be before 'start’ - needs to be the other way around! Self-explanatory
Timestamp 'start’ is not a valid timestamp! The timestamp test failed
Timestamp 'end’ is not a valid timestamp! The timestamp test failed
No pulses found! Valid inputs, but no pulses found

User Stats

Retrieving the stats of a user:

<?php
  // XML example
  $xml    = file_get_contents("http://api.whatpulse.org/user.php?user=1&formatted=yes&format=xml");
  $result = @simplexml_load_string($xml);
  if(!empty($result->error))
  {
    echo "Something went wrong: ".$result->error;
  }
  else
  {
    $userid   = $result->UserID;
    $username = $result->AccountName;
    $joined   = $result->DateJoined;
    echo "User ".$username." holds userid ".$userid." and joined WhatPulse on ".$joined;
  }
?>
require 'httparty'

result = HTTParty.get("http://api.whatpulse.org/user.php?user=1&formatted=yes&format=json");

if result['error']
  puts "Something went wrong: #{result['error']}"
else
  userid   = result['UserID']
  username = result['AccountName']
  joined   = result['DateJoined']

  puts "User #{username} holds userid #{userid} and joined WhatPulse on #{joined}"
end
import requests

result = requests.get("http://api.whatpulse.org/user.php?user=1&formatted=yes&format=json").json()

if 'error' in result:
    print("Something went wrong: ", result['error'])
else:
    userid = result['UserID']
    username = result['AccountName']
    joined = result['DateJoined']

    print("User {} holds userid {} and joined WhatPulse on {}".format(username, userid, joined))

JSON Result:

{
  "GeneratedTime":"2016-01-28 22:27:52",
  "UserID":"1",
  "AccountName":"smitmartijn",
  "Country":"Netherlands",
  "tld":"NL",
  "DateJoined":"2003-02-09",
  "DateJoinedUnixTimestamp":"1044745200",
  "Homepage":"http:\/\/whatpulse.org",
  "LastPulse":"2016-01-28 21:31:53",
  "LastPulseUnixTimestamp":"1454013113",
  "Pulses":"4789",
  "Keys":"56260883",
  "Clicks":"11775268",
  "Download":"2.33TB",
  "Upload":"815.32GB",
  "DownloadMB":2446442,
  "UploadMB":834886,
  "UptimeSeconds":"61130997",
  "UptimeShort":"1y48w6d12h49m57s",
  "UptimeLong":"1 year, 48 weeks, 6 days, 12 hours, 49 minutes, 57 seconds",
  "AvKeysPerPulse":11748,
  "AvClicksPerPulse":2459,
  "AvKPS":0.14,
  "AvCPS":0.03,
  "Ranks":
  {
    "Keys":"525",
    "Clicks":"3075",
    "Download":"4819",
    "Upload":"3760",
    "Uptime":"1729"
  },
  "Team":"0",
  "Computers":
  {
    "computer-0":
    {
      "ComputerID":"459566",
      "Name":"my-computer",
      "Keys":"47328",
      "Clicks":"14050",
      "Download":56159,
      "Upload":3562,
      "UptimeSeconds":"17445201",
      "UptimeShort":"28w5d21h53m21s",
      "UptimeLong":"28 weeks, 5 days, 21 hours, 53 minutes, 21 seconds",
      "Pulses":"754",
      "LastPulse":"2014-08-21 21:26:46",
      "LastPulseUnixTimestamp":"1408649206"
    }
  }
}

With this call, you can retrieve all the stats from a user based on a username or user ID.

HTTP Request

GET http://api.whatpulse.org/user.php?user=<userid or username>

Results

If successful, the result will return a JSON or XML formatted body with statistics about a certain user. The format for the JSON output you can check out on the right of this page.

Available Options

Option Required Description
/user.php?user=<userid or username> Y Get stats for a username or user ID
/user.php?formatted=yes N Format all numbers. (turns 1000, into 1,000)
/user.php?format=xml N Outputs data in XML format (default)
/user.php?format=json N Outputs data in JSON format

Errors

Error Description
No User given! Please supply the user input field
Unknown UserID given The username or user ID was not found (yes, confusing message, sorry)