Core library for Twitter4R, which provides Ruby bindings for the Twitter REST API
Failed to load latest commit information.
config Commented out require_path from gemspec Feb 18, 2009
examples Changed HTTP param name from old :count to :per_page Aug 29, 2010
lib Fix for issue twitter4r/twitter4r-core#10 Jul 18, 2011
scripts Remove old API usages (need to investigate) & add new sanity checks Jul 11, 2011
.gitignore Added to the file pattern ignore list. Sep 7, 2010
MIT-LICENSE Initial import Sep 9, 2008 Minor fixes for twitter4r/twitter4r-core#11 Jul 18, 2011
Rakefile Upgraded to RSpec 2.x beta and fixed consumer token override logic bug. Sep 4, 2010
TODO Updated TODO Mar 17, 2009
pkg-info.yml Added t4r* scripts to the RubyGem distribution. Oct 18, 2010



Twitter4R provides an object based API to query or update your Twitter account via pure Ruby. It hides the ugly HTTP/REST code from your code.


gem install twitter4r

Getting Started

Add the twitter4r dependency to your Gemfile:

gem 'twitter4r', :require => 'twitter'

Set your OAuth consumer key and token like so:

Twitter.configure do |config|
  config.oauth_consumer_token = CONSUMER_KEY_HERE
  config.oauth_consumer_secret = CONSUME_SECRET_HERE

To create a client object with access tokens:

  client = => {
      :key => ACCESS\_KEY, :secret => ACCESS\_SECRET
  client.status(:post, "Your awesome less than 140 characters tweet goes here!!! #with #hashtag #goodness")

Usage Examples

Twitter4R starting with version 0.1.1 and above is organized into seven parts:

  • Configuration API
  • Friendship API
  • Messaging API
  • Model API
  • Status API
  • Timeline API
  • User API


Library supports:

  • OAuth support for authentication with the REST and Search APIs
  • API access
  • Customizability of API endpoints such that any compliant API can be accessed (not just and's)
  • Uses lightweight native JSON under the hood as opposed to heavyweight XML parsing (which is what other Ruby Twitter client libraries use) REST API coverage includes:

  • Status posting and retrieving
  • User information
  • Profile updates and retrieval
  • Favorites add, remove, retrieve
  • Direct messaging post, remove, read
  • Friendship adding, removing, blocking
  • Geolocation embedding inside of statuses and reading from statuses
  • Rate limit status access
  • Trends retrieval and trend location querying Search API coverage includes:

  • Searching with various options




  • Kaiichi Matsunaga - proxy code suggestion
  • Sergio Santos <> - message paging code suggestion
  • Adam Stiles - URI.encode => CGI.escape fix
  • Carl Crawley - Friendship get => post fix
  • Christian Johansen - in_reply_to attributes in Twitter::Status
  • Harry Love - added attributes to Twitter::Status
  • Filipe Giusti - fixed users/show issue that changed from under us, also inspired the v0.5.2 bugfix release by submitting great issue example code.
  • Seth Cousins - added HTTP timeout option and provided a patch that inspired the OAuth support for Twitter4R
  • John McKerrell <@mcknut on twitter> - added geo attribute to Twitter::Message.

Design Suggestions:

  • Bosco So - making Twitter::Error a RuntimeError instead of an Exception to prevent irb from crashing out.

External Dependencies

  • Ruby 1.8 (tested with 1.8.6)
  • RSpec gem 1.0.0+ (tested with 1.1.3)
  • JSON gem 0.4.3+ (tested with versions: 1.1.1 and 1.1.2)
  • jcode (for unicode support)