Created: 2008-09-09 03:10
Updated: 2018-10-23 10:11
License: mit



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 <seth.cousins at gmail dot com> - 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)
Cookies help us deliver our services. By using our services, you agree to our use of cookies Learn more