Mea Culpa Twiter. Mea Culpa...

The way I look at social networks is as time sinks with little practical use compared to the maintenance and care required for the account. Not that I find them useless though. I had spent the last 4 years (around) working for a social marketing agency and have personally witnessed the benefits of social networks in building brand awareness and loyalty. But the work required entailed a dedicated, college educated, person and a couple student interns working 40 hours a week each to accomplish.

Me? I have shit to do thankyouverymuch. I want to spend my time producing ideas, projects and programs. I don’t want to spend any time tending to a social network profile with ephemeral friendships and connections. But apparently Twitter is different. Michael Lop sums it up nicely:

Twitter is a social network, yes, but it’s a social network without the superpoke scrabtaculous zombie noise and, for that, I’m thankful, because I’ve got work to do. Yes, I could spend days tidying my profile and scrubbing my friends list, but to what end? I want to know more people, and sure, it’s interesting to see what they’re up to, but what I really want to know is what is going on inside their heads with a minimum of fuss.

So once again I’m late to a party acting like they’re lucky to have me. I have finally, finally, begun to see the usefulness and benefits of Twitter. It’s weird because I’ve been working so closely with Twitter for the last year interacting with their API and I never “got” it until recently. I’m actually a little embarrassed about this. So many of my personal friends are on Twitter along with my peers online and I was a little pompous about the whole thing. My Bad.

What ended up turning  my perspective around was the realization that Twitter didn’t take any real effort. Outside of the marketing and announcement use (blog posts/updates, code release, project release, etc) all other status updates Twitter needs can be completely random thoughts along the lines of  a friendly conversation.

One key difference between Twitter and this blog is that this blog, and the discussion in it, are not in any way personal towards me or anyone else. But with Twitter, well, that can be, and probably should be, personal and a little intimate. Not completely understand, but the conversation appears to need to be a little more random and personal.

When I ask myself why I have this blog (and really why I think anyone has a blog), and if there’s a requirement of complete honesty, career is definitely at the top of the list. Yes there’s a love of writing and the conversation. But after that, career and ambition are what really motivates me to write and drives this site. (And yes ego has a little to do with it too but that’s a whole other discussion )

So, we’re really talking about a tool of promotion and marketing. I can understand that a little better for some reason.

So yes. I am on Twitter now and I actually like it. It’s liberating to be so open (which doesn’t make much sense to me at all… but there it is). If you’re a fan of this blog (hell, even if you hate me and think I’m an idiot) you might want to follow me .

Tweetmeme

Still, Twitter is all the rage and I do have to admit it is fun working with all the little toys people are making with the Twitter API (playing with the API is really FUN).

One such tool is TweetMeme.

Accoring to the TweetMeme site:

Tweetmeme is a service which aggregates all the popular links on twitter to determine which links are popular. Tweetmeme is able to categorize these links into categories and subcategories, making it easy to filter out the noise to find what your interested in.

We make it easy for you to subscribe to each category and the most popular through aur RSS feeds and Twitter accounts, you can find out more about theses through our help.

TweetMeme has a few ways to integrate their data into your site. The easiest way works by giving site owners a little sliver of JavaScript to embed in their site. The JavaScript adds a little button to the page for one click tweeting on Twitter.

<script type="text/javascript"><!--mce:0--></script>
<script src="http://tweetmeme.com/i/scripts/button.js" type="text/javascript"><!--mce:1--></script>

The above creates a little icon:

TweetMeme Icon

In theory, the above is all you’ll need to do; just drop that slip into a page and you’re good to go. The reality is that there are a couple rules you need to follow.

First, make sure you’re using a custom title meta for your pages. If you don’t all your Tweets will have the same title. Not good.

Second, make sure the page in question is open to the Internet. Don’t try and lock the page behind a log in barrier or TweetMeme won’t be able to parse the page to get the URL and title information.

Last, TweetMeme caches the data so don’t expect the update to be instant; you will be disappointed. For example, on the Dark Void site we are constantly being hit up by the client about the delay. You probably won’t see the number in the widget increment for a bit; there’s nothing you can do about it.

TweetMeme also offers a widget, which I admit I haven’t used and but it looks like it’s basically the same thing as Tweetizen.

It should be noted that I wasn’t able to get the TweetMeme Widget to work. Ever. It just shows a blank page. Good job, TweetMeme.

And of course, there’s the TweetMeme API. You just have to have an API to be taken seriously. It does seem a little redundant to have an API that’s populated with data from the Twitter API but, whatever. I haven’t looked at the API too much either but it doesn’t look too outside the norm for most APIs.

Anyway, there you go; TweetMeme. Marketers love it. I’m ambivalent.

XKCD

Enter PHPTwitterSearch; a pretty easy to use, lightweight, Twitter API Search class. It’s based on the class originally developed by David Billingham, which I admit, I didn’t check out so I don’t know how much it’s based on.

The thing I didn’t really like about the Arc90 script was how complicated the search process was. In case you didn’t notice, I didn’t go into any detail about the search process; for precisely because it was just to complicated. I stopped having fun when working with the search functionality.

Simplicity was what immediately drew me to PHPTwitterSearch. Here’s a basic example of a search:

1
2
3
4
5
6

<?php
$query = 'findme';
$search = new SWTwitterSearch();
$search = new TwitterSearch($query);
$results = $search->results();
?>

Very, very simple. The above searches the API for $query.

Here’s the best part though; for a little more complication all you have to do is chain the calls together.

1
2
3
4
5

<?php
$search = new SWTwitterSearch();
$search = new TwitterSearch();
$results = $search->from('username')->with('hashtag')->to('username2')->results();
?>

The above searches the API for tweets from “username” with the hash string “#hashtag” that was sent to the user “username2″.

The class returns an array with objects that’s really basic and simple.

Twitter

Here are the rest of the methods for interacting with Twitter via the Arc90 Twitter API Service.

It should be noted that nearly everything in the below is taken from the generously documented source code.

Get Messages

Returns a list of the 20 most recent direct messages sent to the authenticating user. The XML and JSON versions include detailed information about the sending and recipient users. This method can return XML< JSON, ATOM and RSS.

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

<?php
$params = array();
/*
$params['page'] = '0';
$params['since'] = mktime(date("H")-4, date("i"), date("s")); //unix timestamp;
$params['since_id'] = '0';
*/
$response = $twitter->getMessages('json', $params);
 
$return = $response->getData();
 
print_r( json_decode($return) );
?>

Get Sent Messages

Returns a list of the 20 most recent direct messages sent by the authenticating user.

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

<?php
$params = array();
/*
$params['page'] = '0';
$params['since'] = mktime(date("H")-4, date("i"), date("s")); //unix timestamp;
$params['since_id'] = '0';
*/
$response = $twitter->getSentMessages($format = 'json', $params);
 
// Print the XML response
$return = $response->getData();
 
print_r( json_decode($return) );
?>

Send Message

Sends a new direct message to the specified user from the authenticating user. This shows up under their “Direct Messages” section.

1
2
3
4
5
6
7
8

<?php
$text = 'Hello from my script!';
$user = 'USER_TO_SEND_TO'; //can be username or user_id
$response = $twitter->sendMessage($user, $text, 'json');
 
// Print the XML response
$return = $response->getData();
?>

Destroy Message

Destroys the direct message specified in the required ID parameter. The authenticating user must be the recipient of the specified direct message.

1
2
3
4
5
6
7
8
9

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

Create Friendship

Befriends the user specified in the ID parameter as the authenticating user. Returns the befriended user in the requested format when successful.

1
2
3
4
5
6
7
8
9

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

Destroy Friendship

Discontinues friendship with the user specified in the ID parameter as the authenticating user.

1
2
3
4
5
6
7
8
9

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

Check if Friendship Exists

Tests if a friendship exists between two users.

1
2
3
4
5
6
7

<?php
$user_a = 'USER_1';
$user_b = 'USER_2';
$response = $twitter->friendshipExists($user_a, $user_b, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Update Location

Updates the location attribute of the authenticating user, as displayed on the side of their profile and returned in various API methods. Please note this is not normalized, geocoded, or translated to latitude/longitude at this time.

1
2
3
4
5
6

<?php
$location = 'Home';
$response = $twitter->updateLocation($location,'json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Update Delivery Device

Sets which device Twitter delivers updates to for the authenticating user. $device Must be one of: sms, im, none.

Sending ‘none’ as the device parameter will disable IM or SMS updates.

1
2
3
4
5

<?php
$device = 'sms';
$response = $twitter->updateDeliveryDevice($device, 'json');
$return = $response->getData();
?>

Update Profile Colors

Sets one or more hex values that control the color scheme of the authenticating user’s profile page on twitter.com. These values are also returned in the /users/show API method.

At least one of the $params is required.

1
2
3
4
5
6
7
8
9
10

<?php
$params['profile_background_color'] = '#FFFFFF';
$params['profile_text_color'] = '#000000';
$params['profile_link_color'] = '#CCCCCC';
$params['profile_sidebar_fill_color'] = '#999999';
$params['profile_sidebar_border_color'] = '#FFFFFF';
 
$response = $twitter->updateProfileColors($params, $format ='json');
$return = $response->getData();
?>

Update Profile Image

Updates the authenticating user’s profile image. Image must be a valid GIF, JPG, or PNG image of less than 700 kilobytes in size. Images with width larger than 500 pixels will be scaled down.

1
2
3
4
5
6
7

<?php
$image = '/path/to/image/'; //Local file path of the image to be uploaded
$response = $twitter->updateProfileImage($image, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
 
?>

Update Profile Background Image

Updates the authenticating user’s profile background image. Image must be a valid GIF, JPG, or PNG image of less than 800 kilobytes in size. Images with width larger than 2048 pixels will be scaled down.

1
2
3
4
5
6

<?php
$image = '/path/to/image/'; //Local file path of the image to be uploaded
$response = $twitter->updateProfileBackgroundImage($image, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Update Profile

Sets values that users are able to set under the “Account” tab of their settings page. Only the parameters specified will be updated; to only update the “name” attribute, for example, only include that parameter in your request.

At least one of the $params is required.

1
2
3
4
5
6
7
8
9
10
11

<?php
$params['name'] = 'Name_TO_Use';
$params['email'] = 'Email_To_Use';
$params['url'] = 'URL_TO_Use';
$params['location'] = 'Location_TO_Use';
$params['description'] = 'Description_TO_Use';
 
$response = $twitter->updateProfile($params, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Get Favorites

Returns the 20 most recent favorite statuses for the authenticating user or user specified by the ID parameter.

1
2
3
4
5
6
7
8
9

<?php
$params['id'] = 'ID_TO_Use';//The ID or screen name of the user for whom to request a list of favorite statuses.
$params['page'] = '0';
 
$response = $twitter->getFavorites($format ='json', $params );
$return = $response->getData();
print_r( json_decode($return) );
 
?>

Create Favorite

Favorites the status specified in the ID parameter as the authenticating user. Returns the favorite status when successful.

1
2
3
4
5
6
7

<?php
$id = 'ID_TO_Use'; //The ID of the status to favorite
 
$response = $twitter->createFavorite($id, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Destroy Favorite

Un-favorites the status specified in the ID parameter as the authenticating user. Returns the un-favorited status in the requested format when successful.

1
2
3
4
5
6
7

<?php
$id = 'ID_TO_Use'; //The ID of the status to favorite
 
$response = $twitter->destroyFavorite($id, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Follow

Enables notifications for updates from the specified user to the authenticating user. Returns the specified user when successful.

NOTE: The Notification Methods require the authenticated user to already be friends with the specified user. Otherwise the error “there was a problem following the specified user” will be returned.

1
2
3
4
5
6
7

<?php
$id = 'ID_TO_Use'; //The ID or screen name of the user to follow
 
$response = $twitter->follow($id, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Leave

Disables notifications for updates from the specified user to the authenticating user. Returns the specified user when successful.

NOTE: The Notification Methods require the authenticated user to already be friends with the specified user. Otherwise the error “there was a problem following the specified user” will be returned.

1
2
3
4
5
6
7

<?php
$user = 'ID_TO_Use'; //The ID or screen name of the user to leave
 
$response = $twitter->leave($user, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Block

Blocks the user specified in the ID parameter as the authenticating user. Returns the blocked user in the requested format when successful.

1
2
3
4
5
6
7

<?php
$id = 'ID_TO_Use'; //The ID or screen name of the user to block
 
$response = $twitter->block($id, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Un-Block

Un-blocks the user specified in the ID parameter as the authenticating user. Returns the un-blocked user in the requested format when successful.

1
2
3
4
5
6
7

<?php
$id = 'ID_TO_Use'; //The ID or screen name of the user to block
 
$response = $twitter->unblock($user, $format ='json');
$return = $response->getData();
print_r( json_decode($return) );
?>

Graph Friends

Returns an array of numeric IDs for every user the specified user is following.

1
2
3
4
5
6
7

<?php
$user = 'ID_TO_Use'; //ID or screen_name of the user to retrieve the friends ID list for
 
$response = $twitter->graphFriends($format ='json', $user );
$return = $response->getData();
print_r( json_decode($return) );
?>

Graph Followers

Returns an array of numeric IDs for every user the specified user is followed by.

1
2
3
4
5
6
7

<?php
$user = 'ID_TO_Use'; //ID or screen_name of the user to retrieve the followers ID list for
 
$response = $twitter->graphFollowers($format ='json', $user );
$return = $response->getData();
print_r( json_decode($return) );
?>

Tweetizen

As part of my research into all things Twitter I recently took a look at Tweetizen. According the Tweetizen website:

Tweetizen is a simple web-based tool designed to help you filter the daily influx of tweets, and easily find the ones that are relevant to you.

It’s basically a site that uses the Twitter API to aggregate tags and keywords. Tweetizen doesn’t have an API of it’s own though I suspect this is would be a simple thing for them to implement; unless they’re pussies that is.

Are you pussies Tweetizen?

Instead of an API they do offer a cheap JavaScript widget that can be embedded into a website if you’re into half-assing the concept of “sharing”. Just embed the below into the head of your website:

 <style type="text/css">@import "http://embed.tweetizen.com/embed.css";</style>

And embed the below somewhere in your site:

<div id="twtzn" class="tweetizen_embed"></div>
<script type="text/javascript" src="http://embed.tweetizen.com/tweetizen.embed.js"></script>
<script type="text/javascript" src="http://embed.tweetizen.com?id=twtzn&g=Breaking+News"></script>

It looks just like every other widget they offer but you can style it using CSS if you wish. I imagine it would be incredibly tedious to really make the widget stand apart from the pack with just CSS but it’s all they offer. They do provide a sample CSS file for usage along with instructions on the Tweetizen FAQ page to help the process along.

For me Tweetizen is a lose; but as mentioned above the clients love this shit so I’m in whether I like it or not.

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['since'] = mktime(date("H")-4, date("i"), date("s")); //unix timestamp
$params['since_id'] = 'POST_ID_TO_USE_SINCE'; //id of post
$params['count'] = '10'; //must be < 200
$params['page'] = '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['since'] = mktime(date("H")-4, date("i"), date("s")); //unix timestamp
$params['id'] = 'ID_OF_USER_TO_CHECK'; //id of user to look up
$params['since_id'] = '902529454'; //id of post
$params['count'] = '10'; //must be < 200
$params['page'] = '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['page'] = '0';
$params['since'] = mktime(date("H")-4, date("i"), date("s")); //unix timestamp 4 hours ago;
$params['since_id'] = '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'] = 'ID_OF_USER_TO_GET_FRIENDS_FOR'; 
$params['page'] = '0';
$params['since'] = mktime(date("H")-4, date("i"), date("s")); //unix timestamp;
$params['lite'] = 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'] = 'ID_OF_USER_TO_GET_FRIENDS_FOR'; 
$params['page'] = '0';
$params['lite'] = 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.