Narcistat API Reference

Narcistat's public interface is crazy simple. It consists of only two REST web services:

Ping - to notify Narcistat when a user has touched one of your pages.
Get - to ask Narcistat for data.

Ping:

Ping is used to notify Narcistat when a user has touched one of your pages. You should be calling this service from every page on your site, every time it is requested. The simplest way to call it is to request an image from your page, like this: <img src="http://api.narcistat.com/ping/" style="display:none"/> Ping requests take the form a a HTTP GET to http://api.narcistat.com/ping/, with the following parameters:

http://api.narcistat.com/ping/
out (optional)	Set this to "`image`" if you'd like to receive an actual image to display on your site. If you're not planning to display an image, you can leave this blank or omit it entirely.
siteid (optional)	Narcistat will normally group hits together by hostname. If, however, you want to get all fancy, you can specify your own unique `siteid` to group by instead. This will allow you to consolidate stats across multiple hostnames, or you can simply use it to mask your site's name from prying eyes. You can choose any siteid that you want, but you might want to send off a Get request or two to ensure that it's not already taken.

Get:

Get is used to ask Narcistat for data, and to notify Narcistat to begin collecting data for a given host or siteid. You'll only need to use it if you are building your own visualization client, or if you wish to view your Narcistat data in it's pure form. Mmmmm... data...

Get requests take the form a a HTTP GET to http://api.narcistat.com/get/, with the following parameters:

http://api.narcistat.com/get/
mode	Specifies how you want to see your results. Possible values include: `json` `xml` `csv` `html (default)`
host	The hostname of the site for which you'd like to retrieve stats. Required, unless a `siteid` is specified.
siteid (optional)	If you've been specifying a `siteid` in your Ping requests, this is how you ask for your data. NOTE: If a `siteid` is specified, any value supplied for `host` will be ignored.
since (optional)	A UTC Datestamp specifying the oldest data that you wish to receive. In practice, this will be the last time that you asked for data from us (e.g., the datestamp that Narcistat sent you during your last request.)

Get requests will return a list of hits, along with a UTC Datestamp specifying the time the request was completed. The data format will vary based on the mode parameter specified in the request, but will contain the following fields (in order for CSV):

ip	IP address associated with this user
date	Date/Time of the last page request by this IP address
url	URL of the last page request by this IP address
firstseen	Date/Time when the first request was seen from this IP address
pagecount	Count of page requests seen from this IP address
useragent	UserAgent string supplied by this user's browser

Usage Notes:

Ping will not begin collecting data for a given host until it has received at least one Get request. Until that time, any Ping requests from that host will be ignored.
If multiple hits have been received from a single IP address since the last Get request, only the most recent url and date will be returned. The pagecount returned will reflect the number of pages logged for that IP address since the last Get request.
Narcistat stores each individual data point for no longer than one minute. You will need to check in at least that often to ensure that you see every hit that has occurred.
Narcistat will cease logging for a given host if more than five minutes have elapsed since the last Get request was issued. Just like you, Narcistat only works while somebody is watching it.