FireStats API

This API is for FireStats 1.3.0 or newer, if you use an older version please use this.

FireStats provide several API calls that allow you to access statistics and other FireStats resources.
At the moment, the API is officially supported only under Wordpress. (if you would like support for other platform please submit an enhancment request).
But using it on other systems should be easy, simply inculde the file php/api.php from within FireStats root directory and call the functions.
(WordPress users can simply call the API functions without including it first).

if the API file is included, 'FS_API' is defined. this allow you to test if its safe to call FireStats API functions like this:

<?php
if (defined('FS_API')) 
{
   // call API here.
}
?>

The following APIs are supported:

<?php

/**
 * Site ID:
 * Some functions accepts a $site_id parameters which defined as follows:
 * - true  : to exclude all sites but the one in the sites_filter option.
 * - false : to include all sites.
 * - a specific number : site id to include (exclude all other sites).
 * 
 * URL:
 * Some function accepts an optional $url to get the hits for.
 * The URL should be exactly as recorded by FireStats.
 * note trailing slash and leading www. 
 * example: 'http://mysite.com/?p=123'
 * 
 * Unix time : Returns the current time measured in the number of seconds since the Unix Epoch (January 1 1970 00:00:00 GMT).
 * see http://php.net/time
 */

/*
    Returns the number of pages displayed in the specified time period.
    days_ago is an optional parameter which specifies how many days ago to start counting.
    if days_ago is not specified, the count will begin when you installed FireStats.
    site_id : see comment at the start of the file
    url: see comment at the start of the file
*/
function fs_api_get_page_views($days_ago = NULL, $site_id = true, $url = null)

/**
    Returns the number of pages displayed in the specified time range
    $range_start : start of range in unix time. see comment at the start of the file  
    $range_end : end of range in unix time. see comment at the start of the file
    site_id : see comment at the start of the file
    url: see comment at the start of the file
 */
function fs_api_get_page_views_range($range_start, $range_end, $site_id = true, $url = null)


/*
    Returns the number of unique hits in the specified time period.
    days_ago is an optional parameter which specifies how many days ago to start counting.
    if days_ago is not specified, the count will begin when you installed FireStats.
        url: see comment at the start of the file
*/
function fs_api_get_visits($days_ago = NULL, $site_id = true, $url = null)


/**
    Returns the number of visits in the specified time range
    $range_start : start of range in unix time. see comment at the start of the file  
    $range_end : end of range in unix time. see comment at the start of the file
    site_id : see comment at the start of the file
    url: see comment at the start of the file
 */
function fs_api_get_visits_range($range_start, $range_end, $site_id = true, $url = null)

/*
    Returns image tags of images representing the useragent
    3 Icons may be returned:
    * OS Icon
    * Browser Icon
    * PDA Icon (if the useagent is of a phone)

    To access the user agent of the current user in PHP use $_SERVER['HTTP_USER_AGENT']
*/ 
function fs_api_get_browser_and_os_images($useragent)

/*
    Returns an image tag with the flag of the country this ip_address blonged to.
    if unknown, an empty string is returned.
*/
function fs_api_get_country_flag_image($ip_address)

/*
    Returns a two characters country code of the country this ip address is belonged to.
    if unknown, false is returned.
*/
function fs_api_get_country_code($ip_address)

/*
    Returns and array of popular pages
    days_ago: is an optional parameter which specifies how many days ago to start counting. 
        if days_ago is not specified, the count will begin when you installed FireStats.
    num_limit : maximum number of items in the result. optional, defaults to 10.
    site_id : see comment at the start of the file
    type: type of urls to return. if not specified all are returned. see FS_URL_TYPE_* in php/constants.php

    returns: an array of containing object with the fields: 
            url : Item URL
            title: the URL title (only if exists)
            c : number of times this item was viewed
*/
function fs_api_get_popular_pages($days_ago = NULL, $num_limit = 10, $site_id = true, $type = null)

/*
        returns the number of RSS subscribers for the specified site. (this functionality is only available in FireStats PRO)
        site_id : see comment at the start of the file
        returns: number of rss subscribers for site.
 */
function fs_api_get_rss_subscribers($site_id = true)

?>

Example

Here is an example usage of the FireStats API.

<?php
if (defined('FS_API'))
{
    echo "Page views ever : ".fs_api_get_page_views()."<BR/>";
    echo "Page views in last day : ".fs_api_get_page_views(1)."<BR/>";
    echo "Visitors ever : ".fs_api_get_visits()."<BR/>";
    echo "Your browser and OS icons are :". fs_api_get_browser_and_os_images($_SERVER['HTTP_USER_AGENT'])."<BR/>";
    echo "Your country flag is : " .fs_api_get_country_flag_image($_SERVER['REMOTE_ADDR'])."<BR/>";

    echo "Number of times the download page was viewed in the last 100 days ". fs_api_get_page_views(100,true,'http://firestats.cc/wiki/Download')."<br/>";
    echo "Number of visitors to the download page between 90 days ago and 50 days ago ";
    echo fs_api_get_visits_range(time() - 60*60*24*90,time() - 60*60*24*50,true,'http://firestats.cc/wiki/Download')."<br/>";
}
?>