This is the official Ruby gem for the Wordnik API. We’re constantly adding methods to the API, and we’ll keep this gem up-to-date.

Documentation: docs.wordnik.com/api/methods

API Key Signup: api.wordnik.com/signup/

Support: groups.google.com/group/wordnik-api

Let’s fire up an irb session:

$ irb
>> require 'wordnik-ruby'
=> true

First, initialize your API client with your api_key and (optionally) your username and password.

NOTE: if you don’t supply a username/password, you won’t be able to access all of the api methods.

>> wordnik=Wordnik.new({:api_key=>'your_api_key'})
=> #<Wordnik:0x110e964 @api_key="your_api_key">
>> wordnik.authenticated?
=> false

Optionally, you can also pass in your username and password when you initialize.

This will allow you to access all api methods, including writing to the Wordnik database.

>> wordnik=Wordnik.new({:api_key=>'your_api_key', :username=>'your_username', :password=>'your_password'})
=> #<Wordnik:0x110e964 @api_key="your_api_key", @auth_token=>"temporary_auth_token", @user_id=>12345>
>> wordnik.authenticated?
=> true

Find a word:

>> cat = Word.find('cat')
=> #<Word:0x601a30 @id=27568, @rel_type=nil, @wordstring="cat">

Get that word’s definitions:

>> cat_definitions = cat.definitions
=> [#<Definition:0x583fb8 @part_of_speech="noun", @text="Any animal belonging to the natural family Felidae, ... ]

Get that word’s example sentences:

>> cat_examples = cat.examples
=> [#<Example:0x5499e4 @url=nil, @rating=755.66016, @year=1992, @display="That mountain cat is a very confused young hunter, ...]

Get that word’s related words (for all your thesaurus needs):

>> cat_related = cat.related
=> {"synonym"=>[#<Word:0x35a0fc @id=nil, @rel_type="synonym", @wordstring="kitten">, #<Word:0x358bd0 @id=nil, @rel_type="synonym", @wordstring="catamaran">, ...], ...}

Retrieve all of the authenticated user’s public lists:

>> wordnik.lists
=> [#<List:0x12e4f54 @word_count=0, @id=25594, @permalink_id="test-list--2", @created_at="2010-05-26T23:28:56.342+0000", @user_name="altay", @updated_at="2010-05-26T23:28:56.342+0000", @description="just a test", @name="test list", @user_id=1026985, @type="PUBLIC">]

Create a public list for the authenticated user:

>> animal_list = wordnik.create_list('animals', 'my favorite animals')
=> #<List:0x129a990 @word_count=0, @id=25593, @permalink_id="animals--2", @created_at="2010-05-26T23:28:28.000+0000", @user_name="altay", @updated_at="2010-05-26T23:28:28.000+0000", @description="my favorite animals", @name="animals", @user_id=1026985, @type="PUBLIC">

See the words in a list:

>> animal_list.words
=> []   # no words yet!

Add a word to this list:

>> animal_list.add_word('dog')
=> [{"userName"=>"altay", "numberLists"=>65, "numberCommentsOnWord"=>19, "userId"=>1026985, "createdAt"=>"2010-05-26T23:31:49.000+0000", "wordstring"=>"dog"}]

Add another word to this list:

>> animal_list.add_word('carrot')
=> [{"userName"=>"altay", "numberLists"=>28, "numberCommentsOnWord"=>0, "userId"=>1026985, "createdAt"=>"2010-05-26T23:33:20.000+0000", "wordstring"=>"carrot"}, {"userName"=>"altay", "numberLists"=>65, "numberCommentsOnWord"=>19, "userId"=>1026985, "createdAt"=>"2010-05-26T23:31:49.000+0000", "wordstring"=>"dog"}]

Fooled you! A carrot is not an animal. Let’s remove that word from animal_list:

>> animal_list.remove_word('carrot')
=> [{"userName"=>"altay", "numberLists"=>65, "numberCommentsOnWord"=>19, "userId"=>1026985, "createdAt"=>"2010-05-26T23:31:49.000+0000", "wordstring"=>"dog"}]

I’m sick of collecting animals. Let’s destroy this list:

>> animal_list.destroy
=> nil

Copyright © 2009 John McGrath / Altay Guvench / Wordnik.com. See LICENSE for details.