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

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

Examples

PHP

<?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;
?>

Ruby

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

Python

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))

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.

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

Pulsing

You can remotely execute a pulse via the Client API.

HTTP Request

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

Examples

PHP

<?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);
?>

Ruby

require 'httparty'

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

Python

import requests

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

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.

{
  "msg": "Pulse executed."
}

Real-time Stats

The client keeps real-time statistics, like keys and clicks per second and the current download and upload. This API call gives you access to that real-time data.

Note: Available from client version 2.8 and up.

HTTP Request

POST http://localhost:3490/v1/realtime

Examples

PHP

<?php
  $json     = file_get_contents("http://localhost:3490/v1/realtime");
  $result   = json_decode($json);
  $keys     = $result->keys;
  $download = $result->download;
  echo "Keys per second: ".$keys.", download rate: ".$download;
?>

Ruby

require 'httparty'

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

puts "Keys per second: #{keys}, clicks p/s: #{clicks}"

Python

import requests

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

print("Clicks per second: {}, upload rate: {}".format(clicks, upload))

Results

The results if the API call will be a JSON formatted array with the current keys and clicks per second, download and upload rates (KB/s, MB/s, GB/s). These values are updating in real-time with an average of the last 5 seconds.

{
  "clicks": "0,10",
  "download": "21KB/s",
  "keys": "2,17",
  "upload": "2KB/s"
}

Unpulsed Stats

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

Examples

PHP

<?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;
?>

Ruby

require 'httparty'

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

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

Python

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))

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.

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