Skip to content

📙 A Ruby wrapper for the Oxford Dictionary API

License

Notifications You must be signed in to change notification settings

swcraig/oxford_dictionary

Repository files navigation

Build Status Test Coverage Code Climate Gem Version

OxfordDictionary

Ruby wrapper to consume the Oxford Dictionary API

Getting Started

$ gem install oxford_dictionary

# To use in your script/application
require 'oxford_dictionary'

After registering for an API key, setup the client:

client = OxfordDictionary::Client.new(app_id: 'ID', app_key: 'SECRET')
client = OxfordDictionary.new(app_id: 'ID', app_key: 'SECRET')

Usage Examples

This wrapper follows the schema laid out by the API quite closely. The data schema for the different API calls can be found here.

Entries
entry = client.entry(word: 'vapid', dataset: 'en-gb', params: {})

# Access the first entry
# Refer to the API documentation for the schema of the returned data structure
first_lexical_entry = entry.lexicalEntries.first

# With some filters
filters = { lexicalCategory: 'Verb', domains: 'Art'}
client.entry(word: 'truth', dataset: 'en-gb', params: filters)

# To have multiple values for a single filter use comma separated terms
filters = { lexicalCategory: 'Verb,Noun' }

# You can also search for the results for different datasets
# Refer to the Oxford Dictionaries documentation for all the
# possible datasets
client.entry(word: 'ace', dataset: 'es', params: {})

# You can query for results from a specific "field"
# Refer to the Oxford Dictionaries documentation for all the
# possible fields
client.entry(word: 'explain', dataset: 'en-gb', params: { fields: 'examples' })
Lemmas
client.lemma(word: 'condition', language: 'en', params: {})
Translations
client.translation(
  word: 'condition',
  source_language: 'en',
  target_language: 'es',
  params: {}
)
Sentences
client.sentence(word: 'paraphrase', language: 'en', params: {})
Search
client.search(language: 'en-gb', params: { q: 'vapid' })
Thesaurus
client.thesaurus(
  word: 'book',
  language: 'en',
  params: { fields: 'synonyms,antonyms'}
)
# Or use { fields: 'synonyms' } for just synonyms

Development

After checking out the repo, run bin/setup to install dependencies. Run bin/console for an interactive prompt that will allow you to experiment.

Contributing

Bug reports and pull requests are more than welcome! Please make tests for anything that is added. bundle exec rake will run rspec/rubocop.

Pull Requests

License

The gem is available as open source under the terms of the MIT License.