Narcistat Home API Reference Visualizations

Narcistat API Reference

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


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="" style="display:none"/> Ping requests take the form a a HTTP GET to, with the following parameters:
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 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, with the following parameters:
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: