Blog

With the Performancing Metrics API launch I thought I would knock together a quick example to show you how you can use it. The simplest idea I could think of was to show a visitor count in your WordPress or Drupal blog sidebar. Being predominantly a Microsoft based developer I found the XML support in PHP a little quirky to say the least so please forgive my code if there is a better way to do it, just see it as an example of how to talk to the API rather than a guide to elegant programming!

If you don’t want to touch code (much) there is a link to a zip file at the end of this post, you will need to extract the text file enclosed and edit the “$API” URL as I describe later down the page.

Authorisation Code

If you check out the Metrics API Handbook you will see we have implemented an authentication system. This provides you with an authorisation token to use instead of sending your username and password in the clear over and over again. You only need to grab this key once until you change your Performancing password, if you request it more than once it still remains the same. Go grab yourself an authorisation token now by entering the URL found below (changing the uid to your Performancing username and the pwd to your Password).

http://performancing.com/perfstats/api.php?action=getauth&uid=some+user&pwd=mypass

Copy the key from the “Auth” bit of the XML and store it somewhere safe. Don’t worry if you lose it, you can always request it again, just don’t leave it lying around as with this code people can snoop on your stats.

Now you have a token you can talk to the API and it will answer. Each call to the API requires this token to prove you are allowed to access the data you have requested. If you enter the URL below changing the domain to your own and they KEY to your token, you should get back some xml representing your visitor stats for the date of 01/03/2006 (if you have any).

api.php?action=getvisitorstats&auth=KEY&blog_domain=myblog.com&m=single_date&d1=2006-03-01

Whatever language or blog software you use there should be a way that you can program a plugin or template hack to use this information but I am going to show you how I did it with PHP as a WordPress plugin and a Drupal Block.

WordPress Plugins

WordPress plugins are simply text files that live in the WordPress plugin folder and that are named with a .php extension. WordPress looks to the top of the file for a commented out area for certain information to identify the plugin so you can enable it in your plugins control panel. After your opening PHP tag (making sure you don’t have anything, even spaces, before the php tag) you need to have something like the below.


/*
WordPress Info
----------------------------------------------------------------------------
Plugin Name: PerformancingMetricsVisitCount
Plugin URI: http://performancing.com/metrics/handbook/api/
Description: Shows Visit Count for your blog using Performancing Metrics API
Version: 0.000000001
Author: Chris Garrett
Author URI: http://performancing.com/

License
-------
GNU General Public License
http://www.gnu.org/copyleft/gpl.html

*/


It just tells WordPress what the plugin is called, who wrote it, etc. If you were to close the PHP tag at the end of the file and upload it to your plugins directory you could enable it now. It wouldn’t do anything but it would be a working plugin.

I said before I wanted the visits to appear in the sidebar. While WordPress seems to have ways of getting content into the header and footer it doesn’t seem to have a way to get info into the sidebar other than the “Meta” area which is a bullet list. Ah well, guess it is meta information we are presenting. To get our info into this area we use a hook like below.

add_action('wp_meta', array('VisitCount', 'ShowVisitCount'));

This tells WordPress to attach our code whenever the meta info is displayed. With this code though we need to create a class and a function. The class will just be a container for the code in this case. Our function will read the XML and output the meta list items.

To make it easier for people using other blog software such as Drupal I have split the code into WordPress stuff and generic PHP stuff, at the end of this post I will show you how you can add the code to Drupal quite easily.

Here is the class that is required for the WordPress hook

class VisitCount {
function ShowVisitCount()
{
visits();
}
}


You will see all it does is calls the “visits” function.

Reading the XML – the Visits Function

The main part of the code is shown below. You need to edit the $API url to add your authorisation token in place of “KEYKEY” and your own domain instead of “myblog.com”.

</p> <p>Global $API,$TAG;<br /> $API = ‘http://performancing.com/perfstats/api.php?action=getvisitorstats&auth=KEYKEY&blog_domain=myblog.com’; </p> <p> function startElement( $parser, $tagName, $attrs ) {<br /> Global $TAG;<br /> $TAG = $tagName;<br /> }</p> <p> // function: endElement<br /> function endElement( $parser, $tagName ) { </p> <p> } </p> <p> function charElement( $parser, $text ) {<br /> Global $TAG,$VISITS;<br /> if($TAG == “VISITS”){<br /> print “</p> <li><b>VISITS TODAY</b>: $text</li> <p>“;<br /> $TAG = “”;<br /> }elseif($TAG == “REPEATVISITORS”){<br /> print “</p> <li><b>RETURN VISITORS</b>: $text</li> <p>“;<br /> $TAG = “”;<br /> }</p> <p> } </p> <p> function visits()<br /> {<br /> Global $API,$TAG;<br /> // Create an xml parser<br /> $xmlParser = xml_parser_create();<br /> xml_set_element_handler( $xmlParser, “startElement”, “endElement” );<br /> xml_set_character_data_handler( $xmlParser, “charElement” ); </p> <p> // Open connection to RSS XML file for parsing.<br /> $fp = fopen($API, “r” )<br /> or die( “Cannot read RSS data file.” ); </p> <p> // Parse XML data from RSS file.<br /> while( $data = fread( $fp, 4096 ) ) {<br /> xml_parse( $xmlParser, $data, feof( $fp ) );<br /> } </p> <p> // Close file open handler<br /> fclose( $fp ); </p> <p> // Free xml parser from memory<br /> xml_parser_free( $xmlParser );<br /> }</p> <p>

Our function reads the XML returned by the API and looks for certain tags, either “visits” or “repeatvisitors”, if it finds them it outputs list items containing those values.

Using as a Drupal Block

I mentioned this code could be repurposed for Drupal. To do that you need to add a “block” and paste the last bit if code (from where it says “global”). Make sure you have allowed PHP code and you surround the pasted code with PHP start and end tags. Then add a call to “visits();” before the closing PHP tag and add the blog to your sidebar.

Summary

This is a very simple example, I am sure you will be able to put the API to much more effective use. I hope though this will help kick start your grey cells creative process. Let us know what you come up with!