StatHat - Send Stats to StatHat

General

API

Language libraries

External Services

Other

This page describes the API for sending stats to StatHat. We have libraries in many languages that you can use instead of interacting with this API directly. There are links in the sidebar to each of them.

EZ API

The easiest way to post a stat to StatHat is to use the "EZ API". With the EZ API, you can create stats on the fly from your code without going to the StatHat website. You can turn off the EZ API on the Settings page.

HTTP POST or GET request to: http://api.stathat.com/ez

Include the following parameters:

Name	Description	Example	Required?
`ezkey`	The ezkey for your StatHat account (defaults to email address)	`john@example.com`	Yes
`stat`	Unique stat name (any character except `~` allowed, 255 characters maximum)	`ws0 load average`	Yes
`count`	Number you want to count	`9`	No
`value`	Value you want to track	`0.375`	No
`t`	Timestamp (unix seconds since epoch)	`1362772440`	No

Note: You must include a count or value parameter with every EZ API call.

If the stat doesn't exist, it will be created and the account owner will receive an email allowing them to destroy the stat. You do not need to specify the timestamp. If there is no t parameter, StatHat will use the time it received the call.

Post same value/count to multiple related stats

The ~ character is a special character in stat names. It allows you to post a count/value to mutliple stats with one call. The format for this is:

[prefix]~[name1],...,[nameX]

For example, say you want to track your users sending messages. You'd like to know how many messages women and men are sending, and a breakdown based on continent. When a woman sends a message, you could post the following stats:

messages sent: total

messages sent: female

messages sent: europe

Or, you could use the ~ syntax to post to all three at once:

messages sent~total,female,europe

StatHat will split that into three stats: messages sent total, messages sent female, and messages sent europe.

There are many other situations that this is perfect for and will cut down on the number of API calls you need to make.

JSON option

You can also post JSON to http://api.stathat.com/ez. With JSON, you can send updates for multiple stats in one call.

The request must come in with a Content-Type header of application/json.

Send a JSON object with two fields, ezkey and data. ezkey should contain your ezkey and data contains an array of stat objects. For example, here's the JSON to post to a few stats:

{
    "ezkey": "XXXYYYZZZ",
    "data": [
        {"stat": "page view", "count": 2},
        {"stat": "messages sent~total,female,europe", "count": 1},
        {"stat": "request time~total,messages", "value": 23.094},
        {"stat": "ws0: load average", "value": 0.732, "t": 1363118126},
    ]
}

As you can see in the example JSON, you can include the timestamp and you can use the special ~ to send data to multiple stats at once.

Classic API

The Classic API requires you to create your stats with the web interface. Its use of signed keys is more tamper-resistant than the EZ API, but it is less convenient to add new stats while you are coding. It is the only recommended API for situations where the stat posting code will be viewable by anyone (client side JavaScript and HTML, for example).

Counter Stat

HTTP POST or GET request to: http://api.stathat.com/c

Include the following parameters:

Name	Description	Example	Required?
`key`	Private key identifying the stat	`i2oer9xisFGsHDNVYzJTM2cy9Xj`	Yes
`ukey`	Private key identifying the user	`i2oer9xisFGsHDNVYzJTM2cy9Xj`	Yes
`count`	Number you want to count	`9`	No (default is 1)
`t`	Timestamp (unix seconds since epoch)	`1362772440`	No

The key and ukey values can be found on the full details page for the stat. key is unique to each stat, ukey is unique to each user. Set a value for count if you want to record multiple occurrences of something with one call. If you do not specify a timestamp with the t parameter, the count will be recorded with the current time.

Note: if someone knows key and ukey, they can post updates to the stat identified by key. That's all they would be able to do, but it could be an issue for you. For example, if you use Javascript in a web page to post a stat, anyone will be able to see your key and ukey.

Value Stat

HTTP POST or GET request to: http://api.stathat.com/v

Include the following parameters:

Name	Description	Example	Required?
`key`	Private key identifying the stat	`i2oer9xisFGsHDNVYzJTM2cy9Xj`	Yes
`ukey`	Private key identifying the user	`i2oer9xisFGsHDNVYzJTM2cy9Xj`	Yes
`value`	Value you want to track	`13.947`	Yes
`t`	Timestamp (unix seconds since epoch)	`1362772440`	No

The key and ukey values can be found on the full details page for the stat. key is unique to each stat, ukey is unique to each user. The value for value will be recorded for the current time, unless you specify a time with the t parameter.

Notes

All API requests can be sent over HTTP or HTTPS, whatever works best for you. The endpoints are the same, just change any URLs listed above from http:// to https://.