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
https://api.whatpulse.org/user.php	GET	Retrieve user statistics
https://api.whatpulse.org/team.php	GET	Retrieve team statistics
https://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
XML

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

<?xml version="1.0"?>

<WhatPulse>
  <error>This is the error message</error>
</WhatPulse>

Team Stats

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 https://api.whatpulse.org/team.php?team=<teamid or name>

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

Examples

PHP
Ruby
Python

<?php
  // JSON example
  $json   = file_get_contents("https://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("https://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("https://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))

Results

If successful, the result will return a JSON or XML formatted body with the team statistics. See below for an example with JSON output. These values are updated from the website each time a member of the team pulses or joins/parts the team.

{
  "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
      }
    }
  }
}

Pulse Stats

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 https://api.whatpulse.org/pulses.php?team=<teamid or name> or user=<userid or username>

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

Examples

PHP
Ruby
Python

<?php
  // JSON example
  $json   = file_get_contents("https://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('https://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('https://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))

Results

If successful, the result will return a JSON or XML formatted body with a list of pulses with their stats. See below for an example with JSON output.

{
  "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"
  }
}

User Stats

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

HTTP Request

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

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)

Examples

PHP
Ruby
Python

<?php
  // XML example
  $xml    = file_get_contents("https://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("https://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("https://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))

Results

If successful, the result will return a JSON or XML formatted body with statistics about a certain user. See below for an example with JSON output.

{
  "GeneratedTime": "2016-01-28 22:27:52",
  "UserID": "1",
  "AccountName": "smitmartijn",
  "Country": "Netherlands",
  "tld": "NL",
  "DateJoined": "2003-02-09",
  "DateJoinedUnixTimestamp": "1044745200",
  "Homepage": "https://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"
    }
  }
}

Web API

Caching​

Errors​

Team Stats​

HTTP Request​

Available Options​

Errors​

Examples​

Results​

Pulse Stats​

HTTP Request​

Available Options​

Errors​

Examples​

Results​

User Stats​

HTTP Request​

Available Options​

Errors​

Examples​

Results​

Caching

Errors

Team Stats

HTTP Request

Available Options

Errors

Examples

Results

Pulse Stats

HTTP Request

Available Options

Errors

Examples

Results

User Stats

HTTP Request

Available Options

Errors

Examples

Results