Finding the number of tweets for a hashtag (or Twitter account mentions) using the Topsy API

I’ve recently started using APIs with some amount of confidence so I figured it was time to start sharing some of what I’ve learned. For longer than I’d like to admit, I thought APIs were some out-of-my-league thing that I needed to learn some more PHP before I even attempted to navigate. Turns out I was wrong: APIs are pretty dang simple.

To get the ball rolling, we’re going to look at using the Topsy API to return the number of tweets for a given hashtag (or Twitter handle mention- any Twitter search really). Topsy is a social search engine and provides a really nifty API for accessing some awesome real-time data.

Note: for access to increased queries, you’ll need a Topsy API key. They are free and painless, but they’ve also got a free version if you don’t mind the limitations. If you’ve got a key, insert it where you see [your api key]. If you don’t, just remove that entire bit from the markup and carry on.

Part one: getting the data

Most APIs allow you to craft a specific URLs with a few of options which will return the data you’ve requested. The service examines the options you’ve set in the URL and returns the data back to you in a usuable format (JSON, XML, etc). The Topsy API provides a number of different request types, but the one we want is searchcount. If we wanted to count the number of tweets in a search for #android, we would do the following:

[php]
<?php
$jsonurl = ‘http://otter.topsy.com/searchcount.json?q=%23android&type=tweet&apikey=[your api key]‘;
$json = file_get_contents($jsonurl,0,null,null);
$json_output = json_decode($json, true);
?>
[/php]

Even if you don’t speak PHP, that part is pretty self explanatory. We’re going to query the Topsy API via searchcount asking for all tweets with #android in them. Then we get the returned file contents and decode them for use in PHP. Our variable $json_output now contains an array of the data we want, which looks something like this:

[code]
$VAR1 = {
'request' => {
'resource' => 'searchcount',
'response_type' => 'json',
'parameters' => {
'q' => '#android',
'type' => 'tweet'
},
'url' => 'http://otter.topsy.com/searchcount.json?q=%23android&type=tweet'
},
'response' => {
'w' => 434131,
'a' => 1105681,
'h' => 1258,
'm' => 706077,
'd' => 146547
}
};
[/code]

As you can see, there is an array labeled response, which contains the actual data we’re after. We’re halfway there! Topsy has now told us exactly how many tweets are marked #android (even broken down by week, day, hour, and all time). All we’ve got to do now is make use of the data…

Part two: using the data

For my purposes, I wanted the total count of tweets from all time, so we’ll be targeting the variable labeled “a”. To use that specific piece of data, we’ll need to extract it from the array we stored in $json_output. Which we’ll do like so:

[php]
<?php
$json_output = array_values($json_output);
foreach($json_output as $key=>$val) {
$hash_count = $val["a"];
}
?>
[/php]

Again, if you don’t speak PHP, let me walk through it in plain English. We take our $json_output variable and use array_values to search it for the value labeled “a”. We store the returned number in a new variable, $hash_count. Now displaying the total number of #android tweets is as simple as echoing $hash_count:

[php]
<?php
echo $hash_count;
?>
[/php]

Of course, now that you’ve got the data as a plain php variable, you can do oh so much more with it…

Step Three: Do something awesome

I took the simple code above and stretched it into a hashtag fight promotion for my site, Android and Me. Over at androidandme.com/fight, you’ll find a head-to-head fight where users can vote for their favorite tablet with a simple tweet. I use the Topsy API to keep track of everything, displaying the total number of tweets of each side, along with a percentage score and even an animated bar graphic.

I’m fully aware that an online tutorial without a live demo can be a total bummer, so I whipped up a little barebones example so you can see the above code live in action. I’ll even make a big ol’ button so people don’t miss it:

Live Example For Internet Fun

After I figured all this out had thoroughly patted myself on the back, someone sent me a link to Hashtag Battle, which also uses Topsy to compare hashtags but does so using Ruby on Rails. They were clearly first to the idea, I’ve just had some fun with it and thought it was a neat example to explain here. I’m going to try to write a new blog post any time I figure out something nifty with a publicly available API, this was just a first attempt at getting things moving. Did I do alright? Does anything need to be explained more clearly? If you’d like to see the entire snippet of code in one piece, here it is:

[php]
<?php
$jsonurl = ‘http://otter.topsy.com/searchcount.json?q=%23android&type=tweet';
$json = file_get_contents($jsonurl,0,null,null);
$json_output = json_decode($json, true);

$json_output = array_values($json_output);
foreach($json_output as $key=>$val) {
$hash_count = number_format($val["a"]);
}

echo $hash_count; ?>
[/php]

PS: I know I said I’d teach you how to pull the total number of mentions for an account, but I bet you already figured it out by now. You just change part of that original $jsonurl. The part that says %23android can just become %40username. The %23 and %40 are URL encoded versions of the # and @ sign, respectively.

Happy hacking!

DATE10th October, 2011

CATEGORIESposts

TAGS , , , ,

Leave a Reply