Fetching contributors…
Cannot retrieve contributors at this time
117 lines (87 sloc) 3.82 KB

wordnik rubygem

This is the official Wordnik rubygem. It fully wraps Wordnik's v4 API. Refer to to play around in the live API sandbox. All the methods you see there are implemented in this ruby gem.


gem install wordnik

Or, add the wordnik gem to your project's Gemfile.rb:

gem 'wordnik'

Then from your project's root, run:


If you're using Wordnik in a rails app, drop this into config/initializers/wordnik.rb:

Wordnik.configure do |config|
  config.api_key = '12345abcde'               # required
  config.username = 'bozo'                    # optional, but needed for user-related functions
  config.password = 'cl0wnt0wn'               # optional, but needed for user-related functions
  config.response_format = 'json'             # defaults to json, but xml is also supported
  config.logger ='/dev/null')     # defaults to Rails.logger or Set to'/dev/null') to disable logging.

Example Standalone Usage

%w(rubygems wordnik).each {|lib| require lib}

Wordnik.configure do |config|
	config.api_key = 'YOUR_API_KEY_HERE'

# Definitions
Wordnik.word.get_definitions('lemurs', :use_canonical => true)
Wordnik.word.get_definitions('fish', :part_of_speech => 'verb,noun')
Wordnik.word.get_definitions('scoundrel', :limit => 20, :source_dictionaries => "ahd,wiktionary,wordnet")

# Examples
Wordnik.word.get_examples('wrangle', :limit => 10, :skip => 10) # pagination

# Related Words
Wordnik.word.get_related('sad', :type => 'synonym')
Wordnik.word.get_related('bowls', :type => 'hypernym', :use_canonical => true)

# Search
Wordnik.words.search_words(:query => 'dog')
Wordnik.words.search_words(:query => 'cal*', :min_dictionary_count => 3)
Wordnik.words.search_words(:query => '*tin*', :include_part_of_speech => 'verb', :min_length => 5, :max_length => 20)

For a full list of available methods, check out the Wordnik API documentation. When you make a request using our web-based API sandbox, the response output will show you how to make the equivalent ruby request. w00t!


The wordnik gem uses rspec 2. To run the test suite, just type rake or bundle exec rake spec in the gem's base directory.


  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
  • Fork the project
  • Start a feature/bugfix branch
  • Commit and push until you are happy with your contribution
  • Make sure to add tests for the feature/bugfix. This is important so we don't break it in a future version unintentionally.


rake swagger                  # um, don't do this unless the API has changed
edit lib/wordnik/version.rb   # bump the version number
rake spec                     # test
git commit -am "newness"      # commit
git push origin master        # push
rake release                  # release


  • Thanks to Jason Adams for graciously turning over the wordnik gem name.
  • HTTP requests are made using Typhoeus, a modern code version of the mythical beast with 100 serpent heads.


  • If you are using the Wordnik gem on Heroku, you'll need to use a stack that is compatible with Typhoeus. As of 2012-08, this means the Cedar stack.