Core library for Twitter4R, which provides Ruby bindings for the Twitter REST API



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)