Oxford Dictionary API

A TypeScript library for interacting with the Oxford Dictionary API. This library provides a comprehensive interface to access dictionary entries, translations, lemmas, inflections, thesaurus data, and more.

Features

• 🔍 Dictionary Entries - Get detailed word definitions, pronunciations, and examples
• 🌐 Translations - Access translations between different languages
• 📚 Thesaurus - Find synonyms and antonyms
• 🔤 Lemmas & Inflections - Get word forms and grammatical variations
• 📝 Sentences - Retrieve example sentences
• 🔎 Search - Search for words with various filters
• 🛠️ Utility Functions - Access metadata, filters, fields, and more

Installation

npm install oxford-dictionary-api-client

Quick Start

import { OxfordDictionary } from "oxford-dictionary-api-client";

// Initialize the client
const dictionary = new OxfordDictionary(
  "your-app-id",
  "your-app-key",
  "https://od-api.oxforddictionaries.com/api/v2"
);

// Get word entries
const entries = await dictionary.entries("en", "hello");
console.log(entries);

API Reference

Constructor

new OxfordDictionary(appId: string, appKey: string, baseUrl: string)

• appId - Your Oxford Dictionary API application ID
• appKey - Your Oxford Dictionary API application key
• baseUrl - The base URL for the API (default: https://od-api.oxforddictionaries.com/api/v2)

Core Methods

entries(sourceLang, wordId, options?)

Get detailed dictionary entries for a word.

Options:

• domains (string) - Filter by domain (e.g., 'academic', 'business', 'medical')
• fields (string[]) - Array of fields to include in response (e.g., ['definitions', 'examples', 'pronunciations'])
• grammaticalFeatures (string) - Filter by grammatical features
• lexicalCategory (string) - Filter by lexical category (e.g., 'noun', 'verb', 'adjective')
• registers (string) - Filter by register (e.g., 'formal', 'informal', 'technical')
• strictMatch (boolean) - Use strict matching (default: false)

const entries = await dictionary.entries("en", "hello", {
  fields: ["definitions", "examples"],
  lexicalCategory: "noun",
  strictMatch: true,
});

translations(sourceLang, targetLang, wordId, options?)

Get translations for a word between languages.

Options:

• domains (string) - Filter by domain (e.g., 'academic', 'business', 'medical')
• fields (string[]) - Array of fields to include in response (e.g., ['translations', 'definitions'])
• grammaticalFeatures (string) - Filter by grammatical features
• lexicalCategory (string) - Filter by lexical category (e.g., 'noun', 'verb', 'adjective')
• registers (string) - Filter by register (e.g., 'formal', 'informal', 'technical')
• strictMatch (boolean) - Use strict matching (default: false)

const translations = await dictionary.translations("en", "es", "hello", {
  fields: ["translations"],
  strictMatch: true,
});

words(sourceLang, query, options?)

Search for words with various filters.

Options:

• domains (string) - Filter by domain (e.g., 'academic', 'business', 'medical')
• fields (string[]) - Array of fields to include in response (e.g., ['definitions', 'examples'])
• grammaticalFeatures (string) - Filter by grammatical features
• lexicalCategory (string) - Filter by lexical category (e.g., 'noun', 'verb', 'adjective')
• registers (string) - Filter by register (e.g., 'formal', 'informal', 'technical')
• strictMatch (boolean) - Use strict matching (default: false)

const words = await dictionary.words("en", "hello", {
  domains: "academic",
  lexicalCategory: "noun",
});

lemmas(sourceLang, wordId, options?)

Get lemmas (base forms) of a word.

Options:

• grammaticalFeatures (string) - Filter by grammatical features
• lexicalCategory (string) - Filter by lexical category (e.g., 'noun', 'verb', 'adjective')

const lemmas = await dictionary.lemmas("en", "running", {
  lexicalCategory: "verb",
});

inflections(sourceLang, wordId, options?)

Get inflected forms of a word.

Options:

• strictMatch (boolean) - Use strict matching (default: false)

const inflections = await dictionary.inflections("en", "run", {
  strictMatch: true,
});

thesaurus(sourceLang, wordId, options?)

Get thesaurus data (synonyms, antonyms).

Options:

• fields (string[]) - Array of fields to include in response (e.g., ['synonyms', 'antonyms'])
• strictMatch (boolean) - Use strict matching (default: false)

const thesaurus = await dictionary.thesaurus("en", "happy", {
  fields: ["synonyms", "antonyms"],
});

sentences(sourceLang, wordId, options?)

Get example sentences for a word.

Options:

• strictMatch (boolean) - Use strict matching (default: false)

const sentences = await dictionary.sentences("en", "hello", {
  strictMatch: true,
});

Search Methods

search.entries(sourceLang, query, options?)

Search for dictionary entries.

Options:

• limit (number) - Maximum number of results to return (default: 50)
• offset (number) - Number of results to skip for pagination (default: 0)
• prefix (boolean) - Use prefix matching (default: false)

const searchResults = await dictionary.search.entries("en", "hello", {
  limit: 10,
  offset: 0,
  prefix: true,
});

search.thesaurus(sourceLang, query, options?)

Search for thesaurus entries.

Options:

• limit (number) - Maximum number of results to return (default: 50)
• offset (number) - Number of results to skip for pagination (default: 0)
• prefix (boolean) - Use prefix matching (default: false)

const thesaurusSearch = await dictionary.search.thesaurus("en", "happy", {
  limit: 5,
});

search.translations(sourceLang, targetLang, query, options?)

Search for translations.

Options:

• limit (number) - Maximum number of results to return (default: 50)
• offset (number) - Number of results to skip for pagination (default: 0)
• prefix (boolean) - Use prefix matching (default: false)

const translationSearch = await dictionary.search.translations(
  "en",
  "es",
  "hello",
  {
    limit: 10,
  }
);

Utility Methods

utility.dictionaryNames(options?)

Get available dictionary names.

Options:

• sourceLang (string) - Source language code (e.g., 'en', 'es', 'fr')
• targetLang (string) - Target language code (e.g., 'en', 'es', 'fr')

const dictionaries = await dictionary.utility.dictionaryNames({
  sourceLang: "en",
  targetLang: "es",
});

utility.filters(endpoint?)

Get available filters.

Parameters:

• endpoint (string, optional) - Specific endpoint to get filters for (e.g., 'entries', 'thesaurus')

const filters = await dictionary.utility.filters("entries");

utility.fields(endpoint?)

Get available fields.

Parameters:

• endpoint (string, optional) - Specific endpoint to get fields for (e.g., 'entries', 'thesaurus')

const fields = await dictionary.utility.fields("entries");

utility.lexicalCategories(sourceLang, targetLang?)

Get lexical categories.

Parameters:

• sourceLang (string) - Source language code (e.g., 'en', 'es', 'fr')
• targetLang (string, optional) - Target language code (e.g., 'en', 'es', 'fr')

const categories = await dictionary.utility.lexicalCategories("en", "es");

utility.registers(sourceLang, targetLang?)

Get available registers.

Parameters:

• sourceLang (string) - Source language code (e.g., 'en', 'es', 'fr')
• targetLang (string, optional) - Target language code (e.g., 'en', 'es', 'fr')

const registers = await dictionary.utility.registers("en", "es");

utility.domains(sourceLang, targetLang?)

Get available domains.

Parameters:

• sourceLang (string) - Source language code (e.g., 'en', 'es', 'fr')
• targetLang (string, optional) - Target language code (e.g., 'en', 'es', 'fr')

const domains = await dictionary.utility.domains("en", "es");

utility.grammaticalFeatures(sourceLang, targetLang?)

Get grammatical features.

Parameters:

• sourceLang (string) - Source language code (e.g., 'en', 'es', 'fr')
• targetLang (string, optional) - Target language code (e.g., 'en', 'es', 'fr')

const features = await dictionary.utility.grammaticalFeatures("en", "es");

Response Types

The library provides comprehensive TypeScript types for all API responses:

• Entries - Dictionary entries
• Lemmas - Word lemmas
• Inflections - Word inflections
• Thesaurus - Thesaurus data
• Sentences - Example sentences
• Search - Search results

Error Handling

The library throws errors for failed API requests:

try {
  const entries = await dictionary.entries("en", "nonexistentword");
} catch (error) {
  console.error("API Error:", error);
}

Getting API Credentials

To use this library, you need to register for an Oxford Dictionary API account:

1. Visit Oxford Dictionary API
2. Sign up for a free account
3. Create a new application to get your App ID and App Key

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.