July 27, 2009 10:17 AM
This example demonstrates how to grab data from the Internet source of your choice and utilize the api/account/my_graphs and api/account/start_tracking API functions. The program below utilizes Twitter's search API to get the latest trends and automatically creates Trendrr graphs for the phrases returned.
The structure provided is quite linear in nature, though a more robust and abstract class system was created to automate graph creation for multiple sources. The more advanced version is available for download, but I thought it would be easier to comprehend the API flow linearly to start. Don't worry, I'm an advanced PHP5 developer normally :-) Let's begin at the top.
index.php
require_once 'TrendrrRequest.php';
$datasource_id = 115; // Twitter Search
$feed = 'http://search.twitter.com/trends.json';
// Get JSON object of Twitter trends
$twitter_obj = getTwitterTrends($feed);
...
TrendrrRequest is a class I created to handle the low level calls to the API. The source code is included in the advanced download. Two other things I will need ahead of time are the source of information (The url to Twitter's Trends) and the ID of the Trendrr data source I will be using to create a graph. All of the data source IDs can be found here or by using the api/account/data_sources call. Next, I call a function I defined to get information from Twitter and save it as an object. Let's take a look at this function.
getTwitterTrends()
function getTwitterTrends($feed) {
$curl_obj = curl_init($feed);
if ($curl_obj === false) { return false; }
curl_setopt($curl_obj, CURLOPT_RETURNTRANSFER, 1);
$source = curl_exec($curl_obj);
curl_close($curl_obj);
if ($source === false) { return false; }
return json_decode($source);
}
The function utilizes a cURL session to make the Twitter API request. It will return false if the process fails at any point. If everything works, it will decode the response into a JSON object for the return value. Now, for the rest of the main source code.
index.php
...
if ($twitter_obj !== false) {
// Get the array of trends from the JSON return
$trends_array = $twitter_obj->trends;
if (!empty($trends_array)) {
// Make a graph for each trend if it doesn't already exist
foreach ($trends_array as $trend) {
// Search for existing graph
if (!graphExistsFor($trend->name, null, $datasource_id)) {
// Start tracking the new trend
$request = startTracking(
$datasource_id,
createTagArray($trend->name),
$trend->name
);
// Display the result
echo $request->getResultMessage(),"\n";
}
}
}
}
Ok, there are a few things here, but it would be more confusing to split it up. The first thing is to make sure that a JSON object was actually created and that the function didn't return false. From there, I save 'trends' from the JSON object which is actually an array of the trends. And as long as that array is not empty, we are going to make a graph for each trend (hence a foreach loop).
In order to avoid numerous duplicate and repetitive graphs, I'll be using the api/account/my_graphs function in the Trendrr API to see if a phrase is already being tracked within my own graphs. Let's take a closer look at the graphExistsFor() function which I use in the code above.
graphExistsFor()
function graphExistsFor($input1, $datasource_id) {
$api_string = 'api/account/my_graphs?'.
'input1='.urlencode($input1).
'&datasource_id='.$datasource_id;
$request = new TrendrrRequest($api_string);
if ($request != null) {
$graph_number = $request->getNumberOfElementsByTagName('graph');
return ($graph_number !== 0);
}
return false;
}
api/account/my_graphs actually doesn't require any parameters, but you can refine a search (instead of returns all of your graphs) using input1, input2, and a datasource_id. In this example, I'm using the Twitter trend as input1 and twitter search datasource_id. Note that I do not have to limit the graphs I create to the Twitter Search data source, but it is the most logical. I could have used Twitter's API to get the trends and then create graphs that track these phrases on different blogging or video sites. A TrendrrRequest object handles the call and then I check if there are any graph tags in the response XML. If none exist, then we need to track this trend!
You'll notice that if a graph doesn't exist, another function (which I defined) is called; startTracking(). This takes the data source id, an array of tags, and the actual trending phrase as arguments. Don't worry too much about createTagArray(). All this does is take the input and explode it so each word in the input becomes an element in the array of tags. Plus, it's in the download if you really want to check it out. A closer look at the tracking function:
startTracking()
function startTracking($datasource_id, $tags_array, $input1) {
$api_string = 'api/account/start_tracking?'.
'input1='.urlencode($input1).
'&datasource_id='.$datasource_id;
// TAGS
$tag_string = null;
if (!empty($tags_array)) {
$tag_string .= '&tags=';
foreach ($tags_array as $key => $tag) {
if ($key != 0) { $tag_string .= '+'; }
$tag_string .= urlencode(trim($tag));
}
}
$api_string .= $tag_string;
// Make the request
return new TrendrrRequest($api_string);
}
api/account/start_tracking has three required parameters. You could have probably guessed that these are at least one input, a set of tags, and a data source ID. The first thing is to set up the values for these parameters into a string for the API call. You'll notice that I have multiple tags, so I add pluses in between to distinguish them from one another. After that, I just need to send the request. If all was successful, my Twitter Search graphs using the Twitter Trends should be in my Trendrr account.
There's a bit more you can add to this code, which I have included in the advanced version that's supposed to be run on the command line. It will also include functions to check response codes and echo more response messages. I suggest you take a look once you grab the basics here. Also take a look at my TrendrrRequest class to see how I handle the API communication.
And an important note: make sure to always have your inputs URL encoded!
Download advanced version