Tweetledee

A PHP library that provides an incredibly easy way to access Twitter data formatted as JSON or a RSS feed

View project onGitHub

Easy Access to Your Data

Tweetledee now supports Twitter data caching to avoid exceeding the Twitter API v1.1 rate limits Learn More

Tweetledee provides ready-bake PHP files that allow you to access Twitter user timelines, user favorites, lists, home timelines, and tweet search data in a JSON or RSS format. This approach works after the Twitter API 1.1 changes that eliminated Twitter support for RSS feeds.

Grab your API tokens from Twitter, upload the Tweetledee files to your server, and use them. It's that simple.

Requirements

You will need the following to use Tweetledee:

  • Access to a web server with PHP version 5.3 or greater. As of Tweetledee v0.4.1, JSON pretty printing is also supported for PHP version 5.3 or greater (previously v5.4+).
  • libcurl installed on your web server (cURL)
  • Twitter application OAuth settings and access tokens
  • Local file write access on the web server (if you are using the caching Tweetledee files)

The 3 Minute Install Guide

Step 1 : Create a Twitter Application

  • Create a Twitter application on the Twitter Developers site
  • For the application details:
  • Name : assign any name that you'd like
  • Description : brief description of the site where you are using Tweetledee
  • Website : enter the domain where you will be using Tweetledee
  • Read and agree to the "Rules of the Road"
  • Fill in the Captcha
  • Click the 'Create Your Twitter Application' button

Presto! You now have a Twitter application and access to the Twitter API. This will provide you with the necessary tokens to access Twitter data with Tweetledee.

Step 2 : Download the Tweetledee files

  • Use one of the handy buttons on the right side of this page
  • Decompress the files locally on your machine
  • This will result in a .zip or .gz compressed directory that contains the delectable goods which reside within the 'tweetledee' directory inside
  • The outer decompressed directory includes a FAQ, LICENSE, and README files. They are worth a read, but they do not need to be included in the installation of Tweetledee on your server. The 'tweetledee' directory inside is the one that you want.

Step 3 : Obtain Your Twitter OAuth Settings

  • Open your application settings page on the Twitter developers site
  • Click the details tab for your application (if it is not selected)
  • Scroll to the bottom of the page and click the 'Create My Access Token Button'
  • Click the OAuth Tool tab in your application settings
  • You are now viewing the four tokens that you need to access Twitter through Tweetledee
  • You will enter these in Tweetledee in the next step

Step 4 : Enter your OAuth Settings in Tweetledee

  • Open the directory where you decompressed the Tweetledee files in Step 2 above
  • Open the file located on this file path in any text editor : tweetledee > tldlib > keys > tweetledee_keys.php
  • Copy your consumer key from Step 3 and paste into the appropriate spot in the tweetledee_keys.php file
  • Copy your consumer secret from Step 3 and paste into the appropriate spot in the tweetledee_keys.php file
  • Copy your access token from Step 3 and paste into the appropriate spot in the tweetledee_keys.php file
  • Copy your access token secret from Step 3 and paste into the appropriate spot in the tweetledee_keys.php file
  • Confirm that you did not modify any other part of the settings file and that you maintained the single quotes around all of your tokens/keys
  • Save the tweetledee_keys.php file

Step 5 : Upload the Tweetledee files to your Server

  • Upload the tweetledee directory that you downloaded in Step 2 to your web server
  • You do not need to upload the outer directory (probably called tweetledee-master or chrissimpkins-tweetledee-version) or the top level files in the outer directory (LICENSE, FAQ, etc) that you decompressed

That's it. You are done. The usage section examples assume that you uploaded the files to your top level public facing web server directory so that the tweetledee directory appears in your URL like this:

Example Tweetledee URL path
http://[yourdomain]/tweetledee/[tweetledee_file]

Try this as a quick test to confirm that it is working. This will display your user timeline RSS feed:

Your New User Timeline Feed
http://[yourdomain]/tweetledee/userrss.php

Note that the default is 25 tweets in this feed. You can modify this with URL parameters that you pass to the Tweetledee file (up to 200 tweets). The default files cache your results for 90 seconds in order to remain within the Twitter API v1.1 rate limits. For this reason, you will not see updated results for 90 seconds after you initially access the PHP script. You can modify this interval with a URL parameter cache_interval. See the Usage and Caching docs for more information about caching.

The Usage section of the documentation includes a large number of examples that will introduce you to all of the available parameters.

What Tweetledee Includes

Favorites (User) JSON

http://[yourdomain]/tweetledee/favoritesjson.php

Favorites (User) JSON | Non-Cached

http://[yourdomain]/tweetledee/favoritesjson_nocache.php

Favorites (User) JSON (pretty printed)

http://[yourdomain]/tweetledee/favoritesjson_pp.php

Favorites (User) JSON (pretty printed) | Non-Cached

http://[yourdomain]/tweetledee/favoritesjson_pp_nocache.php

Favorites (User) RSS

http://[yourdomain]/tweetledee/favoritesrss.php

Favorites (User) RSS | Non-Cached

http://[yourdomain]/tweetledee/favoritesrss_nocache.php

Home timeline JSON

http://[yourdomain]/tweetledee/homejson.php

Home timeline JSON | Non-Cached

http://[yourdomain]/tweetledee/homejson_nocache.php

Home timeline JSON (pretty printed)

http://[yourdomain]/tweetledee/homejson_pp.php

Home timeline JSON (pretty printed) | Non-Cached

http://[yourdomain]/tweetledee/homejson_pp_nocache.php

Home timeline RSS feed

http://[yourdomain]/tweetledee/homerss.php

Home timeline RSS feed | Non-Cached

http://[yourdomain]/tweetledee/homerss_nocache.php

List JSON

http://[yourdomain]/tweetledee/listsjson.php?list=[list-slug]

List JSON | Non-Cached

http://[yourdomain]/tweetledee/listsjson_nocache.php?list=[list-slug]

List JSON (pretty printed)

http://[yourdomain]/tweetledee/listsjson_pp.php?list=[list-slug]

List JSON (pretty printed) | Non-Cached

http://[yourdomain]/tweetledee/listsjson_pp_nocache.php?list=[list-slug]

List RSS Feed

http://[yourdomain]/tweetledee/listsrss.php?list=[list-slug]

List RSS Feed | Non-Cached

http://[yourdomain]/tweetledee/listsrss_nocache.php?list=[list-slug]

Tweet search JSON

http://[yourdomain]/tweetledee/searchjson.php?q=[search-query]

Tweet search JSON | Non-Cached

http://[yourdomain]/tweetledee/searchjson_nocache.php?q=[search-query]

Tweet search JSON (pretty printed)

http://[yourdomain]/tweetledee/searchjson_pp.php?q=[search-query]

Tweet search JSON (pretty printed) | Non-Cached

http://[yourdomain]/tweetledee/searchjson_pp_nocache.php?q=[search-query]

Tweet search RSS feed

http://[yourdomain]/tweetledee/searchrss.php?q=[search-query]

Tweet search RSS feed | Non-Cached

http://[yourdomain]/tweetledee/searchrss_nocache.php?q=[search-query]

User timeline JSON

http://[yourdomain]/tweetledee/userjson.php

User timeline JSON | Non-Cached

http://[yourdomain]/tweetledee/userjson_nocache.php

User timeline JSON (pretty printed)

http://[yourdomain]/tweetledee/userjson_pp.php

User timeline JSON (pretty printed) | Non-Cached

http://[yourdomain]/tweetledee/userjson_pp_nocache.php

User timeline RSS feed

http://[yourdomain]/tweetledee/userrss.php

User timeline RSS feed | Non-Cached

http://[yourdomain]/tweetledee/userrss_nocache.php

Download Tweetledee

Please use one of the buttons on the right side of this screen. You will receive a compressed directory that contains all of the Tweetledee files.

Git users can clone the project with one of the following links:

https://github.com/chrissimpkins/tweetledee.git | git@github.com:chrissimpkins/tweetledee.git

Subversion users can checkout the project with the following URL :

https://github.com/chrissimpkins/tweetledee

Usage

There are a number of available options for the returned JSON and RSS data. For example, you can change the number of returned tweets, switch user timelines, exclude retweets and replies, and retrieve tweets based upon a search query. These are all documented as comments in the respective PHP files.

For more detailed treatment of usage, head over to this page to see examples of Tweetledee in action.

Get Help

Need help? Here's the support page.