AllFacebook InsideFacebook InsideMobileApps InsideSocialGames SocialTimes LostRemote TVNewser TVSpy AgencySpy PRNewser MediaJobsDaily UnBeige

Getting Started with the Twitter API Console

In past columns we’ve looked at several different ways to use the Twitter API to search, post tweets and various other Twitter related functions. The console at http://dev.twitter.com/console is another useful way to access Twitter functionality. The console provides access to basically all of the API functions. It can be used to research functionality and Twitter data, debug issues in API calls for your own applications or even design calls for those apps. This powerful and easy to use tool is made by Apigee. They have a version posted on their own site along with an informative getting started video outlining the major features.

Let’s take a look at a quick example to see the current Twitter trends. Once you access the console, it may take a moment for the tool to load depending on your connection speed. Once it does you should see an interface similar to the one pictured above.

The left-hand menu lists available API calls (or functions) and the right, main column is reserved for the response of the queries. Search down to near the bottom of the function column for Trends. Open up the Trends parent category and select the first function also called trends. The top URL field will update to show the full URL to the Trends -> trends endpoint.

http://api.twitter.com/1/trends.json

To the right of this URL click on the large orange button label GET to execute the trends call and update the results pane with the output.

The top section of the results is the HTTP protocol header. This data will vary depending on the usage and location. Similar headers are passed back and forth for every HTTP page, image and file accessed over the web.

Below the header is the result of our API query. Scroll down to see all of the result data. The result may not be immediately understandable as it is in a machine-readable format called JSON, but you should be able to pick out enough of the keywords to see what’s going on. Though the exact output will be different depending on what Twitter topics are actually trending when the query is executed, there should be several dozen lines starting like:

{
"trends": [
{
"name" : "#thatswhyursingle",
"url" : "http://search.twitter.com/search?q=%23thatswhyursingle"
},
{
"name" : "#ispendwaytomuchmoneyon",
"url" : "http://search.twitter.com/search?q=%23ispendwaytomuchmoneyon"
},
... snipped ...
],
"as_of" : "Mon, 16 May 2011 19:04:05 +0000"
}

Where name is the hashtag trend and url the full URL to search for this trending tag directly at Twitter. In PHP we can extract the JSON data into an array for usage with json_decode(). See json.org for examples of using the JSON format in other programming languages.

For a more useful example of the console, let’s retrieve a user’s timeline. Back in the API console function list in the left-hand pane, click on Timeline then statuses/user_timeline. The console URL field will update to:

http://api.twitter.com/1/statuses/user_timeline.json?screen_name=<strong>{screen_name}</strong>

The user_timeline endpoint requires a screen_name as a parameter so the API knows which user’s timeline it is being asked for. Replace {screen_name} with the Twitter screen name of the desired user before submitting the query so that it looks like this:

http://api.twitter.com/1/statuses/user_timeline.json?screen_name=<strong>alltwtr</strong>

Execute the query in the console and the response will be similar to the previous example consisting of a header and the JSON reply data.

[
{
"retweet_count" : 1,
"in_reply_to_status_id" : null,
"text" : "CBS Cancels "$#*! My Dad Says"  Will We Ever See Another Twitter-Inspired Show? http://mbist.ro/iWQ1dI",
"created_at" : "Mon May 16 21:15:15 +0000 2011",
"in_reply_to_screen_name" : null,
"in_reply_to_status_id_str" : null,
"contributors" : null,
"retweeted" : false,
"in_reply_to_user_id_str" : null,
"source" : <a rel="nofollow" href="http://www.hootsuite.com">HootSuite</a>,
"id_str" : "70235890852691968",
"place" : null,
"coordinates" : null,
"geo" : null,
"in_reply_to_user_id" : null,
"truncated" : false,
"user": {
"contributors_enabled" : false,
"notifications" : false,
"created_at" : "Fri Jan 22 19:16:39 +0000 2010",
"profile_sidebar_border_color" : "C0DEED",
"listed_count" : 295,
"following" : true,
"description" : "Community, news, and resources from AllTwitter.com - the unofficial twitter resource",
"statuses_count" : 1413,
... snipped ...
},
"id" : 70235890852691970,
"favorited" : false
},
... snipped ...

In the timeline reply the actual tweet text will be listed under the text variable. Also included will be various information such as retweet count, date and time of the tweet, the application which posted the tweet (in this case Hootsuite) and user information about the user who posted it. The Twitter developer documentation gives a good examples of the all of the possible fields that could be returned for each function.

If JSON isn’t your thing, most API functions provide multiple output formats. The documentation for statuses/user_timeline lists supported return formats of JSON, XML, RSS and Atom. To tell the API to output XML instead, simply change the .json at the end of the URL to .xml like so:

http://api.twitter.com/1/statuses/user_timeline<strong>.xml</strong>?screen_name=alltwtr

Not every function provides alternate methods of return other than JSON. The developer documentation for each function will list all of the supported reply data formats.

Clicking on the gear icon to the right of the URL field in the console will allow for other parameters, headers, attachments and text to be added to console queries. To the left of the URL field a pulldown supports OAuth authentication which spawns the familiar Twitter authorization popup for functions that require authentication from a specific account such as reading your personal timeline and listing your followers.

The Twitter Console is a powerful tool to explore the functionality provided by the Twitter API and for developers to build complex queries and debug issues in their existing queries. We’ll explore more uses of the Twitter Console in future articles.

Mediabistro Course

Content Marketing 101

Content Marketing 101Almost 60% of businesses use some form of content marketing. Starting December 8, get hands-on content marketing training in our online boot camp! Through an interactive series of webcasts, content and marketing experts will teach you how to create, distribute, and measure the success of your brand's content. Register now!