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.