Site Stats | API to Site Stats

To track your web links
try our new "likin' links"

API to Site Stats

Introduction

Site Stats offers an Application Programming Interface (API) to help you integrate Site Stats information with your other systems. The API is designed to be very simple to use, with just 3 services:

token.cgi - Get an API token for a username and password
report.cgi - Get a web traffic report for an API token
traffic.cgi - Get a list of web site visits for an API token

Below we explain how to make calls to the Site Stats API services:

Using the token.cgi service

To request your API token, put your username and password in the URL:
https://site-stats.com/api/token.cgi?username=USER&password=PASS

You will receive an XML document formatted like this:

<api>
  <token calls="0" expires="" limit="100000" starts="2007-06-05"
         status="A" text="ab4cdef7b0aed4bcd12345ec71daf7c6" />
  <stats remote_addr="189.130.27.138" request="" timestamp="1180546967" />
</api>

Make a copy of the token's "text" attribute because you will need this to call the report.cgi and traffic.cgi API services. For JSON service responses, please see below.

Using the report.cgi service

To request a web traffic report, put your token, site ID and report name in the URL:
https://site-stats.com/api/report.cgi?token=TOKEN&site=SITE&report=REPORT

...where REPORT is one of:

traffic - a web traffic summary report
browser - a web browser (user agent) report
country - the number of visits from each country
language - the number of visits reading each language
time_zone - the time zones where your visitors live
color_bits - the quality of color on your visitors' computers
resolution - the size of the screen on your visitors' computers
op_sys - the operating system running on your visitors' computers
host - the internet host names where your visitors access the web
referrer_page - visits from web pages that referred traffic to you
referrer_site - visits from web sites that referred traffic to you
referrer_search - visits from search engines, with search phrases
search_word - visits searching for a particular word
search_phrase - visits searching for a particular phrase
page - most popular web pages in your site, measured in page views
directory - most popular directories (folders) in your site
entry_page - pages where your visitors entered your web site
exit_page - pages where your visitors left your web site
page_navigation - navigation from one page to another
page_visits - the number of visits to each page
commerce_referrer - visits from referrers who delivered commerce
commerce_entry_page - the first pages of visits to commerce pages
page_duration - the average duration on each page, in seconds
hour_of_day_visits - the number of visits per hour of the day
commerce_word - search words that referred commerce page views
commerce_phrase - search phrases that referred commerce page views
visit_duration - the distribution of visit durations in minutes
visit_pages - the distribution of page views per visit in pages
search_engine_phrase - popularity of search engine search phrases
commerce_engine_phrase - search engines that referred you commerce
mail - email views
hour_of_day_hits - page views per hour of the day
spider - visits by web spiders (typically crawlers)
referrer_path - web traffic paths from referrals
location - geographical locations of visits
campaign_entry_page - visits to your campaign landing pages
campaign_commerce - campaign visits that included commerce pages
commerce_path - web traffic paths to commerce pages
file - files downloaded, such as music, images and documents
link - link activity, as defined in your redirector links
link_cost - the costs associated to your redirector links
link_revenue - the revenues associated to your redirector links

If you would like a report for a particular date, please add "&date=YYYYMMDD" to your service request URL, where YYYYMMDD is a date like 20070531 for May 31st 2007.

You will receive an XML document formatted like this:

<api>
  <site id="12345" time_zone="0" url="yoursite.com">
    <channel name="" id="0">
      <report name="referrer_search" date="20070531" date_requested="0"
              id="12" secs="26130" time="1180483200">
        <data field="www.google.co.uk" value="1" />
        <data field="www.google.com" value="2" />
      </report>
    </channel>
  </site>
  <stats remote_addr="189.130.27.138" request="" timestamp="1180509330" />
</api>

Using the traffic.cgi service

To request a list of web traffic visits, put your token and site ID in the URL:
https://site-stats.com/api/traffic.cgi?token=TOKEN&site=SITE

If you would like a report for a particular date, please add "&date=YYYYMMDD" to your service request URL, where YYYYMMDD is a date like 20070531 for May 31st 2007.

You will receive an XML document formatted like this:

<api>
  <site id="12345" time_zone="0" url="yoursite.com">
    <channel name="" id="0">
      <traffic date="20070531">
        <visit browser="IE70" city="Burbank" color_bits="32" cookies="yes"
               country="us" flash="no" global_id="1180454992226294"
               host="71-80-175-46.static.lsan.ca.charter.com"
               host_ip="71.80.175.46" java="yes" javascript="yes"
               language="en" latitude="341855" longitude="-1183146"
               netspeed="cabledsl" op_sys="WinXP" referrer="some/page.html"
               region="ca" resolution="1024x768" time_zone="-7"
               user_id="1180454992226294" visit_id="1180483258837142" />
      </traffic>
    </channel>
  </site>
  <stats remote_addr="189.130.27.138" request="" timestamp="1180546967" />
</api>

JSON service responses

To have the Site Stats API return responses formatted as JSON, please add "&format=json" to your request URL. This works for all 3 API services.

To have your JSON response call a JavaScript function, please add "&callback=FUNC" where FUNC is your function name. This can help with asyncronous AJAX style code.

To have your JSON response include a requst number, please add "&request=NUM" where NUM is your request number. This is very useful when connecting responses to original requests.