Diving into the Twitter Search API


Twitter is something you're either obsessed with, confused by, or sick of. So, let's see what we can do with it using the Twitter API. Don't worry, it's a lot easier than you may think. If I can do it anyone can. We'll be looking at how you can use the Twitter API with PHP to make requests and create a simple search and result page.

This tutorial includes a screencast available to Tuts+ Premium members.

Step 1 - Make Sure cURL for PHP is Enabled on your Web Server

cURL is a command line tool for transferring files with URL syntax. It allows a much quicker and easier way to make http requests through PHP. This is important to have because the PHP Library we'll be using requires it. If you're not sure whether or not you've got cURL installed and enabled on your web server run the phpinfo() function and search for "curl" to see if it's enabled. Most modern web servers have it installed and enabled. If not you can manually enable it from the two php.ini files on your web server.

Step 1.5 - Join the Twitters

If you haven't already, get yourself a Twitter account. You don't actually need one for the purposes of this tutorial, but if you want to extend this with posting and following and other stuff, you'll need one. I still have no idea why people love or hate it so much, but I'm going to show you what you can do with the API.

Step 2 - Download the Twitter API PHP Library

Yeah, we could do it from scratch, but why? In the real world we need to get stuff done fast and a lot of the heavy lifting has already been done for us. The PHP Library will bridge the gap for us between the Twitter API and PHP. For this tutorial we're gonna use a PHP Library from the web development company Arc90. You can Download the Arc90 PHP Twitter API Client as a ZIP file here.

Full Screencast

Step 3 - Setup the File/Folder Structure

Extract the downloaded ZIP file and move the 'lib' file into your 'code' (this is just my arbitrary code folder, you can name it anything you want) folder in your project. I've got a 'css' folder containing a twitter styled 'style.css' file.

Step 4 - Import the Twitter Library and Start Talking to the API

Create a new 'tweet-feed.php' file. Here's the code on that page. I've commented out the Public Timeline request. You can uncomment that and comment out the search request if you want to. This is just to get you started. Remember the Twitter Search API only allows ATOM and JSON request types. All other requests allow XML, RSS, ATOM, and JSON. This tutorial uses ATOM.

// The PHP Library requires us to set the include path to the main 'lib' folder 
// Require the central PHP Library 'Twitter.php' file 
// Create a new instance of the Twitter object 
$twitter = new Arc90_Service_Twitter(); 
// Get Public Timeline 
//$response = $twitter->getPublicTimeline('ATOM'); 
//echo $feed = $response->getData(); 
// Conditionals for the get query from the url 
if(isset($_GET['q']) && $_GET['q'] != ''){ 
	$q = $_GET['q']; 
} else { 
	$q = 'nettuts'; 
// Search Twitter API Request 
$response = $twitter->searchAPI('ATOM'); 
echo $feed = $response->search($q,array('rpp'=>10)); 

Step 5 - Displaying the API Requested Data

Create another PHP file, 'index.php' and add the following code. This includes a simple search form, the PHP for importing the ATOM/XML result file ('tweet-feed.php') we created earlier using SimpleXML, and looping the content to display the resulting Twitter API Search results.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" ""> 
<html xmlns=""> 
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 
<title>Tweetorial, Simple Twitter Search</title> 
<link rel="stylesheet" type="text/css" href="css/style.css" /> 
if(isset($_GET['q']) && $_GET['q'] != ''){ 
	$q = $_GET['q']; 
} else { 
	$q = 'nettuts'; 
<div id="content"> 
<h1>Tweetorial Search Results</h1> 
<h2>Search Results for <b><?php echo $q; ?></b></h2> 
<div class="search"> 
	<form action="index.php" method="get" name="tweetsearch"> 
		<input type="text" name="q" /> 
		<input type="submit" /> 
</div><!-- /.search --> 
//SimpleXML load results feed 
$twitter_results = simplexml_load_file('http://localhost/tweet/tweet-feed.php?q='.$q); 
// Loop the resulting Twitter Search data 
foreach($twitter_results->entry as $tweet){ 
	// Wrap all the tweet data in a '.tweet' div 
	echo '<div class="tweet">'; 
		// Get the Twitter avatar and wrap it in an '.avatar_border' div 
		echo '<div class="avatar_border"><img class="avatar" src="'.$tweet->link[1]['href'].'" /></div>'; 
		// Display the Twitter username and wrap it in a H3 tag 
		echo '<hr /><h2>'.$tweet->author->name.'</h2>'; 
		// Display the tweet content and wrap it in a P tag 
		echo '<p>'.$tweet->content.'</p>'; 
	echo '</div>'; 
</div><!-- /#content --> 

Step 6 - Make It All Pretty

Now that we've got all the data, let's make it easy on the eyes. Here's the CSS I used to style the 'index.php' page. Notice at the end of the CSS the 'img.avatar' style. This is important as Twitter doesn't always reduce the avatar images correctly and some may display a much larger image.

body { 
	background: #9AE4E8; 
	margin: 0 auto; 
	padding: 0; 
	font-family: "Trebuchet MS", Arial, Verdana; 
	font-size: 12px; 
	color: #333333; 
img { 
	border: 0; 
a { 
	text-decoration: underline; 
	color: #00CCFF; 
a:hover { 
	color: #FFFFCC; 
	margin:0 auto; 
h3, h3 a { 
a:hover { 
/* ------------------------------------------- Content ------------------------------------------- */ 
	margin:0 auto; 
/* ------------------------------------------- Other/Misc ------------------------------------------- */ 
.search { 
.tweet { 
	background: #FFFFFF; 
	color: #666666; 
	margin:0 0 2px; 
/* The b tag is used to highlight the search keyword on the resulting search page */ 
b { 
	background: #CCFFFF; 
.avatar_border { 
	border:1px solid #EFEFEF; 
	margin:0 10px 0 0; 
.avatar { 
	border:6px solid #F0F0F0; 
/* It's important to manually set the height and width as Twitter doesn't always reduce the avatar images and some may display a much larger image */ 
img.avatar { 


Well, that's all I've got time for right now. This should give you the basics to get started using the Twitter API with PHP. Now you can extend it to more useful web applications, a Twitter AIR client, add some sweet AJAX-iness, whatever you can think of. Get tweetin' while the Twitter's hot.