If you aren’t familiar with the Mechanical Turk, it’s part of the Amazon Web Services, and it allows anyone to source simple activities to a number of people that would otherwise be too expensive or logistically complex to accomplish. You can learn more at the Amazon Mechanical Turk site.

Why did I do it? I recently had to work on  a project building a game interface that finds players and gives them access to a simple game using the Mechanical Turk. I decided to use PHP with the REST API and found it very cumbersome. Hence, I decided to use my code as a wrapper for the REST API so other developers could perform the same actions using simple functions instead of gargantuan URLs.

Little by little I will incorporate more and more functions to match those provided by the API, and hopefully some of you will add some functions as well.

Bookmark It

Hide Sites

First of all you’ll want to set up your Ping.fm service right to update the feeds of your choice, as well as create the necessary permissions to post to each service. Log in to your account and select Add More Networks; now make your selection.

Now that your account is set up you need to gather your api key and a user key. I found this point to be the most confusing of the entire set up. Apparently the user app key is no longer necessary, but I couldn’t find an explanation of what the new method is.

If you take a look in the footer there’s a ‘developers’ section that has all the information necessary to get the keys and such.

Now you can go ahead and send your updates from your web app.

<?php

 $api_key = ''; //Don't forget your keys
 $user_app_key = '';
 //$api_call = 'http://api.ping.fm/v1/system.services'; //Good test
 $api_call = 'http://api.ping.fm/v1/user.post';

 //I assume you are pulling this content from a database, a feed, or some other automated method. But it's not important for this example.
 $title = "Something really witty";
 $content = "Your awesome post";

 //Set up the connection and pass the options required by the API.
 $curl_conn = curl_init();
 curl_setopt($curl_conn, CURLOPT_URL, $api_call); //URL to connect to
 curl_setopt($curl_conn, CURLOPT_POST, 1); //Use POST
 curl_setopt($curl_conn, CURLOPT_HEADER,1); //Get the header. This is key to getting the response code!
 curl_setopt($curl_conn, CURLOPT_RETURNTRANSFER, 1); //Return the result as string.

 //Check out all the options in the Ping.fm documentation
 $options = array('api_key' => $api_key, 'user_app_key' => $user_app_key, 'post_method' => 'blog', 'title' => $title, 'body' => $content);
 curl_setopt($curl_conn, CURLOPT_POSTFIELDS, $options);
 $output = curl_exec($curl_conn);

 echo $output; //See what you get

 ?>

Here’s an example of posting to a Facebook page.

Bookmark It

Hide Sites

We will be using PHP and cURL to access the API. If you aren’t too familiar, please read this post.

Each heading is exactly what you will find in the Twitter API documentation, along with my own explanation and some examples.

200 OK: Success!

Let’s say I want to get a list of my followers, I can use the code example below, and if I get a 200 OK return code I know that my request has been successful.

//Create the connection handle

$curl_conn = curl_init();

//Set up the URL to query Twitter
$user_followers = "https://twitter.com/statuses/followers/nicdev.xml";

//Set cURL options

curl_setopt($curl_conn, CURLOPT_URL, $user_followers); //URL to connect to
curl_setopt($curl_conn, CURLOPT_GET, 1); //Use GET method
curl_setopt($curl_conn, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); //Use basic authentication
curl_setopt($curl_conn, CURLOPT_USERPWD, 'username:password'); //Set u/p
curl_setopt($curl_conn,CURLOPT_HEADER,1); //Get the header. This is key to getting the response code!<strong></strong>

curl_setopt($curl_conn, CURLOPT_RETURNTRANSFER, 1); //Return the result as string.

// Result from querying URL. Will parse as xml
$output = curl_exec($curl_conn);

// close cURL resource. It's like shutting down the water when you're brushing your teeth.
curl_close($curl_conn);

echo $output;

If you are following along you will now have a pretty messy screen full of information about your followers. The part of the response we are interested in, it’s in the first line.

HTTP/1.1 200 OK Date: Tue, 10 Nov 2009
13:51:56 GMT Server: hi X-RateLimit-Limit:
20000 X-Transaction: 1257861116-80037-4182
Status: 200 OK

The 200 OK code let’s us know it’s all good, and our request has been successfully processed.

304 Not Modified: There was no new data to return.

This one is a bit trickier. In short, a 304 code means that there is no new data to a request. I attempted to send the request repeatedly through a “for loop” but I got a 200 OK every time. I tried to search for bug reports so I could try to reproduce it, but no dice. Maybe they don’t really provide 304′s? If you know a way of getting it to reply 304, please comment.

400 Bad Request: The request was invalid.  An accompanying error message will explain why. This is the status code will be returned during rate limiting.

Well, Twitter imposes all sorts of limits on the amount of API calls you can make, and this is a good thing. The limits imposed are workable, and can be increased if you are a developer and ask nicely. The default limit is 150/hour on any given account, so it was easy to reproduce.

Change the script as follows, and refresh the page.

//Replace the line  $output = curl_exec($curl_conn); with the following block of code.

for($i = 0; $i < 160; $i++)
{
    $output = curl_exec($curl_conn);
    $output = substr($output, 0, 200);
    echo $output."<br />";
}

You will probably get a lot of 200 codes followed by 400′s.

HTTP/1.1 400 Bad Request Date: Tue, 10 Nov
2009 14:43:40 GMT Server: hi
X-RateLimit-Limit: 150 Status: 400 Bad
Request X-RateLimit-Remaining: 0
X-Runtime: 0.01104 Content-Type:
application/xml;

401 Not Authorized: Authentication credentials were missing or incorrect.

Does as it says, and there’s a great way of testing it out, the verify_credentials method. Simply pass it a bad username and password and you’ll have a 401 error to call your own.

//Change this part in the original script.

//Set up the URL to query Twitter

$user_followers = "http://twitter.com/account/verify_credentials.xml";

//Don't forget to change the credentials to something invalid

Here’s the result

HTTP/1.1 401 Unauthorized Date: Tue, 10 Nov
2009 15:16:24 GMT Server: hi Status: 401
Unauthorized

403 Forbidden: The request is understood, but it has been refused.  An accompanying error message will explain why. This code is used when requests are being denied due to update limits.

You simply tweet too much! Again, you hit a rate limit that is pretty forgiving for most people. The following piece of code will actually post just one tweet to your account, which will most likely get a 200 OK code; I’m posting in in case you were looking for a short script to post updates to Twitter. The second one will actually try to post more messages than it’s allowed in order to purposely get a 403 code.

Please note that because Twitter checks you aren’t sending the exact same message repeatedly, I’m changing the text in every post.

One tweet:

//Create the connection handle

$curl_conn = curl_init();

//Set up the URL to query Twitter

$api_call = "http://twitter.com/statuses/update.xml";
$options = "status=This is a test status made with PHP"; //The actual message is a required parameter

//Set cURL options

curl_setopt($curl_conn, CURLOPT_URL, $api_call); //URL to connect to
curl_setopt($curl_conn, CURLOPT_POST, 1); //Use POST
curl_setopt($curl_conn, CURLOPT_POSTFIELDS, $options);
curl_setopt($curl_conn, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); //Use basic authentication
curl_setopt($curl_conn, CURLOPT_USERPWD, 'username:password..'); //Set u/p
curl_setopt($curl_conn, CURLOPT_HEADER,1); //Get the header. This is key to getting the response code!

curl_setopt($curl_conn, CURLOPT_RETURNTRANSFER, 1); //Return the result as string.

// Result from querying URL. Will parse as xml

$output = curl_exec($curl_conn);

echo $output;

// close cURL resource. It's like shutting down the water when you're brushing your teeth.
curl_close($curl_conn);

Many, many tweets.

//Create the connection handle

$curl_conn = curl_init();

//Set up the URL to query Twitter

$api_call = "http://twitter.com/statuses/update.xml";

//Set cURL options

curl_setopt($curl_conn, CURLOPT_URL, $api_call); //URL to connect to
curl_setopt($curl_conn, CURLOPT_POST, 1); //Use POST
curl_setopt($curl_conn, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); //Use basic authentication
curl_setopt($curl_conn, CURLOPT_USERPWD, 'username:password'); //Set u/p
curl_setopt($curl_conn, CURLOPT_HEADER,1); //Get the header. This is key to getting the response code!

curl_setopt($curl_conn, CURLOPT_RETURNTRANSFER, 1); //Return the result as string.

for($i=0;$i < 160;$i++)
{
    $options = "status=This is a test status made with PHP to reach a 403".md5($i); //Change the message on each iteration
    curl_setopt($curl_conn, CURLOPT_POSTFIELDS, $options);
    $output = curl_exec($curl_conn);
    $output = substr($output,0,200);
    echo $output;
}

// close cURL resource. It's like shutting down the water when you're brushing your teeth.
curl_close($curl_conn);

HTTP/1.1 403 Forbidden Date: Tue, 10 Nov
 2009 18:54:52 GMT Server: hi
X-Transaction: 1257879292-55915-20315
Status: 403 Forbidden
Last-Modified: Tue, 10..

In case you haven’t noticed this is spamming, and it uses a lot of resources unnecessarily, so don’t do it, please.

404 Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist.

This one is very simple. You’re looking for something that’s just not there. To try it out, go to the original script and change the request to a user you know doesn’t exist. For example @nicdev1232342

$user_followers = "https://twitter.com/statuses/followers/nicdev1232342.xml";

HTTP/1.1 404 Not Found Date: Tue, 10 Nov
 2009 19:16:49 GMT Server: hi
X-RateLimit-Limit: 150 X-Transaction:
 1257880609-95984-9773 Status:
404 Not Found

406 Not Acceptable: Returned by the Search API when an invalid format is specified in the request.

Either the dpcumentation is wrong, or I’m too slow to understand. I tried making a request for followers using an non-existing format of .noformat, and all I got was a lousy 403. Again, if someone knows how to get this one to fire, please let me know and I’ll update the post.

$user_followers = "https://twitter.com/statuses/followers/nicdev.noformat";

I wanted a 406!

HTTP/1.1 403 Forbidden Date: Tue, 10
 Nov 2009 19:23:03 GMT Server: hi
 X-Transaction: 1257880983-50850-
1216 Status: 403 Forbidden

500 Internal Server Error: Something is broken.  Please post to the group so the Twitter team can investigate.

This one you can’t reproduce at will, but if you play with the Twitter API long enough you’re bound to run into it.

502 Bad Gateway: Twitter is down or being upgraded.

503 Service Unavailable: The Twitter servers are up, but overloaded with requests. Try again later. The search and trend methods use this to indicate when you are being rate limited.

The following script will run a search for the term “argentina” against the Twitter search API. Search limits are independent of other limits, and will return a 503 as opposed to a 403 when reaching the rate limit.

$curl_conn = curl_init();

//Set up the URL to query Twitter

$api_call = "http://search.twitter.com/search.json?&q=argentina";

//Set cURL options

curl_setopt($curl_conn, CURLOPT_URL, $api_call); //URL to connect to
curl_setopt($curl_conn, CURLOPT_GET, 1); //Use GET
curl_setopt($curl_conn, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); //Use basic authentication
curl_setopt($curl_conn, CURLOPT_USERPWD, 'username:password'); //Set u/p
curl_setopt($curl_conn, CURLOPT_HEADER,1); //Get the header. This is key to getting the response code!

curl_setopt($curl_conn, CURLOPT_RETURNTRANSFER, 1); //Return the result as string.

for($i=0;$i < 160;$i++)
{
    $output = curl_exec($curl_conn);
    $output = substr($output,0,200);
    echo $output."<br />";
}

// close cURL resource. It's like shutting down the water when you're brushing your teeth.
curl_close($curl_conn);

This one was a true surprise. While running the script that loops around 160 times I received many 200′s, followed by a 502 Bad Gateway, followed by a 503 Service Unavailable (what I was expecting), and then again by a bunch of 200′s. It seems to me that the rate limit on search is very forgiving.

HTTP/1.1 200 OK Date: Tue, 10 Nov 2009 19:49:38
HTTP/1.1 502 Bad Gateway Date: Tue, 10 Nov 2009 19:49:42

HTTP/1.0 503 Service Unavailable

HTTP/1.1 200 OK Date: Tue, 10 Nov 2009 19:50:01

I hope you enjoyed the post and that it’ll help you when writing applications for Twitter, or any other app that relies on response codes. To finish here are some great resources.

• Twitter API Documentation – Good docs and a great community built around it.
• Scripting Twitter With cURL – Tech@Sakana

Bookmark It

Hide Sites

How to Authenticate Users With Twitter OAuth

How to quickly integrate with Twitter’s OAuth API using PHP

Now that I’m in the process of writing a simple twitter application, I want to share with you some of the steps that might help you save some time and grief in the future.

In this post I’ll show you how to connect securely to Twitter, authenticate, make a query and return a particular users’ followers as a string using PHP and cURL.

//Create the connection handle

$curl_conn = curl_init();

//Set up the URL to query Twitter
$user_followers = “https://twitter.com/statuses/followers/”username.xml”;

//Set cURL options

curl_setopt($curl_conn, CURLOPT_URL, $user_followers); //URL to connect to
curl_setopt($curl_conn, CURLOPT_GET, 1); //Use GET method
curl_setopt($curl_conn, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); //Use basic authentication
curl_setopt($curl_conn, CURLOPT_USERPWD, ‘username:password’); //Set u/p
curl_setopt($curl_conn, CURLOPT_SSL_VERIFYPEER, false); //Do not check SSL certificate (but use SSL of course), live dangerously!
curl_setopt($curl_conn, CURLOPT_RETURNTRANSFER, 1); //Return the result as string

// Result from querying URL. Will parse as xml
$output = curl_exec($curl_conn);

// close cURL resource. It’s like shutting down the water when you’re brushing your teeth.
curl_close($curl_conn);

Explanation

The first step is to decide the type of query to use. For more information see the API wiki. Then you will set up all the options for cURL. In PHP these are set up one by one using curl_setopt(). If you don’t need a particular option, you can comment it out.  Each option is explained as a comment, but there are some areas that grant a bit more explanation.

Twitter uses basic authentication for their services.  This is only needed for certain parts of the API, but more than likely you’ll end up having to authenticate at some point.

Use HTTPS if possible, otherwise credentials would be sent in clear text and it would be fairly easy to intercept and read.

Lastly,  execute cURL. This is when the connection happens, until now we have only set options, but haven’t actually attempted a connection. Now that we have a string back, we can convert it to an XML object and parse it for any information we need.

Bookmark It

Hide Sites

The first thing I set to do was my homework: research the API. Oh the excitement! A few different options, with me setting my sights on the REST API. And the excitement continued, they had several different functions for me to get the data I needed in beautiful XML.

And so I tested one of these in my browser, go ahead try it out, put this in your address bar http://twitter.com/statuses/followers/nicdev.xml enter your credentials and bam! There you have my followers (or any other user’s, just substitue “nicdev”).

This is great, let me try it again! Not so fast

/statuses/followers/nicdev.xml Rate limit exceeded. Clients may not make more than 100 requests per hour

Well, that sure sucked, but imagine if you have a succeessful service that a lot of people want to use. What happens then? It happens that you can get white-listed. I just applied for it, and will update this post (or write another) when I receive a reply. Yet, it seems that some applications are still hard pressed to survive with this cap in place. In fact, both Cnet and ReadWriteWeb published articles on this subject yesterday.

I certainly hope that Twitter supports the development community around them and allows me to continue executing my idea.

EDIT:

Twitter has sent me a notification granting my request. Expect a post regarding a new application soon!

Bookmark It

Hide Sites