Introduction

The FeedBurner Awareness API (AwAPI) allows publishers of FeedBurner feeds to reuse the detailed traffic statistics FeedBurner captures for any of their feeds. Third-party applications and web services that consume feeds can leverage this data to provide useful feed awareness statistics to potential subscribers. FeedBurner captures traffic data at an overall level for every feed. Feeds that use our free FeedBurner Stats PRO item view tracking have access to much more detailed data at the individual item level. This data includes “resyndication” information, which is very useful for determining where and how a feed is being consumed.
The FeedBurner Awareness PHP API wrapper class AwAPI.class.php provides an easy and simple was to use the FeedBurner Awareness API in your PHP projects.

Requirements

In order to use the FeedBurner Awareness PHP API you will need the following:

  • FeedBurner account and a feed to use with Awareness API enabled. To activate AwAPI, sign in to your FeedBurner account and visit the Publicize tab on the details page for the feed whose awareness data you want to access. Click Awareness API on the service menu that appears on the left side of the page. On the Awareness API form that appears, click Activate.
  • Server with installed PHP, please note that the FeedBurner Awareness PHP API wrapper class AwAPI.class.php works only with PHP version 5 and above. There are no known problems of using the AwAPI.class.php with PHP in SafeMode.
  • Client URL Library (cURL) installed and enabled in your php.ini file.

The AwAPI PHP Class

The FeedBurner Awareness PHP API wrapper class AwAPI.class.php is an Object Oriented (OOP) PHP5 API class for accessing the Awareness API. Here are few things that you need to know in order to use this class.

Creating Instances

If you wish to use the methods available in this class you will need to create an instance of the object first. To do that simply write the following:

	$aw = new AwAPI('FeedURI', true);

The first argument is the URI of the feed (same as http://feedproxy.google.com/<feeduri>), the second argument is weather to use exceptions or use return false on errors. If set to TRUE it will throw exceptionad (this is the default value so if you wish to use exceptions you might ommit this argument) and if set to FALSE it will return false on errors. Here are a few examples:

With Exceptions

	$aw = new AwAPI('FeedURI');
	try{
		// MAKE SOME API CALL HERE
	}
	catch(Exception $e){
		echo 'ERROR From Exception: '.$e -> getMessage().'<br />';
		echo 'ERROR From Class Variable: '.$aw -> err.' ERROR CODE: '.$aw -> errcode.'<br />';
	}

Without Exceptions

	$aw = new AwAPI('FeedURI', false);
	$res = $aw -> FeedDataHistory(''); // We did not pass a valid start date
	if($res === false){
		echo 'ERROR: '.$aw -> err.' ERROR CODE: '.$aw -> errcode;
	}

Methods of the AwAPI PHP Class

The FeedBurner Awareness PHP API wrapper class AwAPI.class.php has methods which allow you to access the Awareness API. All of the methods return arrays on success, or throw exceptions / return false when there is an error.

Feed Circulation, Hits And Reach

FeedData() – Current Basic Feed Circulation, Hits And Reach

The FeedData() method provides you with the current feed circulation, hits and reach numbers. This method returns an array with the following items:

  • id – The FeedBurner id of the feed
  • uri – The URI of the feed
  • date – The date this entry describes
  • circulation – Number of people who requested your feed in the 24 hour period described by date
  • hits – The exact number of requests for your FeedBurner feed during the 24 hour period described by date
  • reach – Total number of people who have taken action

Here is an example on how to get the number of people subscribed to the BlackBerry Freeware RSS feed:

	$aw = new AwAPI('freeblackberrysoftware');
	try{
		$res = $aw -> FeedData();
		echo 'People subscribed to your feed: '.$res['circulation'];
		print_r($res);
	}
	catch(Exception $e){echo $aw -> err;}

print_r($res); will give you insight of the returned array structure.

FeedDataHisory($startDate, $endDate = ”) – Feed Circulation, Hits And Reach History

The FeedDataHisory() method gives you access to the past feed circulation, hits and reach data for a specified date range. When passing the $startDate and $endDate arguments, please make sure that they are in the “YYYY-MM-DD” format. If you ommit the $endDate argument, it defaults to today’s date.

This method returns an a set of arrays one for each date, here is the structure of those arrays:

  • date – The date this entry describes
  • circulation – Number of people who requested your feed in the 24 hour period described by date
  • hits – The exact number of requests for your FeedBurner feed during the 24 hour period described by date
  • reach – Total number of people who have taken action
	$aw = new AwAPI('freeblackberrysoftware');
	try{
		$res = $aw -> FeedDataHistory('2010-07-23', '2010-07-25');
		print_r($res);
	}
	catch(Exception $e){echo $aw -> err;}

print_r($res); will give you insight of the returned array structure.

Feed Item Circulation, Hits And Reach

ItemData($itemurl = ”) – Current Feed Items Circulation, Hits And Reach

This method if used without the $itemurl argument returns an array with the current feed items and circulation, hits and reach for each item.
When used with the $itemurl argument, url address of the item in the feed, returns circulation, hits and reach only for the item.

	$aw = new AwAPI('freeblackberrysoftware');
	try{
		$res = $aw -> ItemData();
		print_r($res);
		$res = $aw -> ItemData('http://www.blackberrysoftware.us/n10240,free-theme-winterberry-for-blackberry.html');
		print_r($res);
	}
	catch(Exception $e){echo $aw -> err;}

print_r($res); will give you insight of the returned arrays structure.

ItemDataHistory($startDate, $endDate = ”, $itemurl = ”) – Feed Item Circulation, Hits And Reach History

	$aw = new AwAPI('freeblackberrysoftware');
	try{
		$res = $aw -> ItemDataHistory('2010-07-23'); // From 2010-07-23 till today
		print_r($res);
		$res = $aw -> ItemDataHistory('2010-07-23', '2010-07-25');
		print_r($res);
		$res = $aw -> ItemDataHistory('2010-07-23', '', 'http://www.blackberrysoftware.us/n10240,free-theme-winterberry-for-blackberry.html'); // From 2010-07-23 till today
		print_r($res)
		$res = $aw -> ItemDataHistory('2010-07-23', '2010-07-25', 'http://www.blackberrysoftware.us/n10240,free-theme-winterberry-for-blackberry.html');
		print_r($res);
	}
	catch(Exception $e){echo $aw -> err;}

print_r($res); will give you insight of the returned arrays structure.

Feed Resyndication

ResyndicationData($itemurl = ”) – Get Feed / Item Resyndication Data

	$aw = new AwAPI('freeblackberrysoftware');
	try{
		$res = $aw -> ResyndicationData();
		print_r($res);
		$res = $aw -> ResyndicationData('http://www.blackberrysoftware.us/n10240,free-theme-winterberry-for-blackberry.html');
		print_r($res);
	}
	catch(Exception $e){echo $aw -> err;}

print_r($res); will give you insight of the returned arrays structure.

Download

FeedBurner Awareness PHP API v0.1