Arc90 Twitter API Service Part 1

Published: 04/27/2009

Programming, Code

Twitter is all the rage these days; everyone’s on it and everyone seems to love it. Not me, of  course. Like most social networking tools and services I find the whole thing pretty stupid.

Twitter

And, again, I’m apparently wrong because I’ve done some digging into manipulating the Twitter API so I can use it on my client’s sites.

There are a few different libraries available for accessing the API, in all the popular programming languages, but the one I chose was the PHP Twitter API Client. Unlike all the other php libraries available this one has sick documentation. We’re talking full phpdocumentor documentation; pure geak porn here.

I wanted to document the client but it’s a really, REALLY, exhaustive codeset so I’m going to break it up into 2 different posts.

The Basics

The Arc90 API client requires the entire library be in the php include path so you’ll have to either modify the php.ini directly or use ini_set to include the library. Kinda sucks, but whatever.

The client can also return the response in a few different data formats: XML, JSON and sometimes even RSS and ATOM depending on how you call the API and whether that format is available. For the purposes of this article all the examples will be returned in JSON format.

In order for the client to work you  have to have CURL installed and available to php. Most hosts already do but you never know so it’s best to check with your host if you’re not sure.

It’s also important to familiarize yourself with all the ins and outs of the Twitter API. They employ rate limiting and have some useful information for developers that’ll help make the API a little less painful.

Basic Example

The client is a full OOP service with exceptions so the basic layout of the algorithm is like the below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

<?php
//echo ini_get('include_path');
require_once 'Arc90/Service/Twitter.php';
 
$username = 'YOUR_USERNAME';
$password = 'YOUR_PASSWORD';
 
$twitter = new Arc90_Service_Twitter($username, $password);
 
try
{ 
 
	$response = $twitter->getFriendsTimeline('json');
	$return = $response->getData();
 
	// If Twitter returned an error (401, 503, etc), print status code
	if($response->isError())
	{
		echo $response->http_code;
	}
	print_r( json_decode($return) );
}
catch(Arc90_Service_Twitter_Exception $e)
{
	// Print the exception message (invalid parameter, etc)
	print $e->getMessage();
}
?>

For all additional examples I’ll only be displaying exactly what’s necessary; take that into account.

End Session

Ends the session of the authenticating user, returning a null cookie. Use this method to sign users out of client-facing applications like widgets.

1
2
3

<?php
$response = $twitter->endSession();
?>

Get Public Timeline

Returns the 20 most recent statuses from non-protected users who have set a custom user icon. This method can return JSON, XML, ATOM and RSS.

1
2
3
4
5

<?php
$response = $twitter->getPublicTimeline('json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Get Friends Timeline

Returns the 20 most recent statuses posted by the authenticating user and that user’s friends. This method can return JSON, XML, ATOM and RSS.

If the optional $params are passed you can pare down the results.

1
2
3
4
5
6
7
8
9
10
11
12
13

<?php
$params = array();
$params = mktime(date("H")-4, date("i"), date("s")); //unix timestamp
$params = 'POST_ID_TO_USE_SINCE'; //id of post
$params = '10'; //must be < 200
$params = '1';
$response = $twitter->getFriendsTimeline('json',$params);
 
// Print the XML response
$return = $response->getData();
 
print_r( json_decode($return) );
?>

Get User Timeline

Returns the most recent statuses posted from the authenticating user based on the set options. This method can return JSON, XML, ATOM and RSS.

1
2
3
4
5
6
7
8
9
10
11
12

<?php
$params = array();
$params = mktime(date("H")-4, date("i"), date("s")); //unix timestamp
$params = 'ID_OF_USER_TO_CHECK'; //id of user to look up
$params = '902529454'; //id of post
$params = '10'; //must be < 200
$params = '1';
$response = $twitter->getUserTimeline('json',$params);
 
// Print the XML response
$return = $response->getData();
?>

Show Status

Returns the status for a single user based on the provided id. This method can return XML and JSON.

1
2
3
4
5

<?php
$response = $twitter->showStatus('ID_OF_USER_TO_CHECK','json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Update Status

Updates the authenticating user’s status and returns the posted status in the requested format when successful.

1
2
3
4
5
6

<?php
$status = 'My Script Sent This Status';
$response = $twitter->updateStatus($status, $in_reply_to_status_id = 0, $format = 'json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Get Replies

Returns the 20 most recent @replies (status updates prefixed with @username) for the authenticating user. Returns JSON, XML, ATOM and RSS.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<?php
$params = array();
/*
$params = '0';
$params = mktime(date("H")-4, date("i"), date("s")); //unix timestamp 4 hours ago;
$params = '0';
*/
$response = $twitter->getReplies('json', $params);
 
// Print the XML response
$return = $response->getData();
 
print_r( json_decode($return) );
 
?>

Destroy Status

Destroys the status specified by the required ID parameter. The authenticating user must be the author of the specified status.

1
2
3
4
5
6

<?php
$id = 'ID_OF_STATUS_TO_DESTROY';
$response = $twitter->destroyStatus($id, 'json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Get Friends

Returns the 20 most recent statuses from non-protected users who have set a custom user icon. This method can return ATOM and RSS.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<?php
$params = array();
/*
$params = 'ID_OF_USER_TO_GET_FRIENDS_FOR';
$params = '0';
$params = mktime(date("H")-4, date("i"), date("s")); //unix timestamp;
$params = TRUE; //removes status
*/
$response = $twitter->getFriends('json', $params);
 
// Print the XML response
$return = $response->getData();
print_r( json_decode($return) );
?>

Get Followers

Returns the authenticating user’s followers, each with current status inline. They are ordered by the order in which they joined Twitter (this is going to be changed). This method can return ATOM and RSS.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<?php
$params = array();
/*
$params = 'ID_OF_USER_TO_GET_FRIENDS_FOR';
$params = '0';
$params = TRUE; //removes status
*/
$response = $twitter->getFollowers('json', $params);
 
// Print the XML response
$return = $response->getData();
 
print_r( json_decode($return) );
 
?>

Show User

According to the source code on this method:

614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630

/**
 * Returns extended information for a given user, specified by ID, screen name, or email.
 *
 * This information includes design settings, so third party developers can theme their widgets
 * according to a given user's preferences.
 *
 * You must be properly authenticated to request the page of a protected user.
 *
 * The API allows a user to be identified by ID, screen name, or email.
 * Any of these fields may be provided using the $id parameter.
 *
 * A user ID must be passed as an integer.
 * A screen name or an email address must be passed as a string.
 *
 * Show data for a user with an ID of 123: showUser(123)
 * Show data for a user with a screen name of 123: showUser("123")
 */

Can return in XML or JSON.

1
2
3
4
5
6
7
8
9

<?php
$id = 'SCREEN_NAME_ID_OR_EMAIL_OF_USER_TO_CHECK';
$response = $twitter->showUser($id, 'json');
 
// Print the XML response
$return = $response->getData();
 
print_r( json_decode($return) );
?>

Be sure to check out Part 2 of the series for details on the remaining methods and functionality.