Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Core library for Twitter4R, which provides Ruby bindings for the Twitter REST API
Failed to load latest commit information.
bin Added t4r* scripts to the RubyGem distribution.
config Commented out require_path from gemspec
examples Changed HTTP param name from old :count to :per_page
lib Fix for issue twitter4r/twitter4r-core#10
scripts Remove old API usages (need to investigate) & add new sanity checks
spec Revise RSpec example to be consistent with current specfications
tasks Fix rdoc Rake task
.gitignore Added to the file pattern ignore list.
.rspec Moved spec/spec.opts to .rspec as per rspec 2.x conventions.
CHANGES Updated CHANGES and modified gemspec
Gemfile Update version of rspec and add rake dependencies
MIT-LICENSE Initial import Minor fixes for twitter4r/twitter4r-core#11
Rakefile Upgraded to RSpec 2.x beta and fixed consumer token override logic bug.



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)
Something went wrong with that request. Please try again.