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
- Ruby
- Python
<?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))
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
- Ruby
- Python
<?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()
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.
HTTP Request
POST http://localhost:3490/v1/realtime
Examples
- PHP
- Ruby
- Python
<?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;
?>
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}"
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
- Ruby
- Python
<?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))
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
}