Kotlin Oxford Dictionaries

Kotlin client for the Oxford Dictionaries API.

This projects aims to facilitate the interaction with the Oxford Dictionaries API. A complete documentation for the API can be reached at: https://developer.oxforddictionaries.com/documentation.

Contents

• Kotlin Oxford Dictionaries
  • Supported endpoints
  • Install
  • Authentication App Key and Id
  • Usage & Examples
    • Retrieve entries for the word 'ace'
    • Retrieve entries for the word 'ace' with complex query
    • Retrieve grammatical features for 'en-us' language

Supported endpoints

The API currently supports all endpoints.

endpoints

Api	Supported?
/api/v2/entries/{source_lang}/{word_id}:	✅
/api/v2/lemmas/{source_lang}/{word_id}:	✅
/api/v2/translations/{source_lang_translate}/{target_lang_translate}/{word_id}:	✅
/api/v2/thesaurus/{lang}/{word_id}:	✅
/api/v2/sentences/{source_lang}/{word_id}:	✅
/api/v2/words/{source_lang}:	✅
/api/v2/inflections/{source_lang}/{word_id}:	✅
Search
/api/v2/search/translations/{source_lang_search}/{target_lang_search}:	✅
/api/v2/search/{source_lang}:	✅
/api/v2/search/thesaurus/{source_lang}	✅
Utility
/api/v2/domains/{source_lang}:	✅
/api/v2/domains/{source_lang_domains}/{target_lang_domains}:	✅
/api/v2/fields:	✅
/api/v2/fields/{endpoint}:	✅
/api/v2/filters:	✅
/api/v2/filters/{endpoint}:	✅
/api/v2/grammaticalFeatures/{source_lang}:	✅
/api/v2/grammaticalFeatures/{source_lang_grammatical}/{target_lang_grammatical}:	✅
/api/v2/languages:	✅
/api/v2/lexicalCategories/{source_lang}:	✅
/api/v2/lexicalCategories/{source_lang_lexical}/{target_lang_lexical}:	✅
/api/v2/registers/{source_lang}:	✅
/api/v2/registers/{source_lang_registers}/{target_lang_registers}:	✅

Install

All needed to start using the project is to add the dependency

Maven

<dependency>
  <groupId>com.github.sparkmuse</groupId>
  <artifactId>kotlin-oxford-dictionaries</artifactId>
  <version>1.0.8</version>
</dependency>

Gradle Kotlin DSL

implementation("com.github.sparkmuse:kotlin-oxford-dictionaries:1.0.8")

Gradle

implementation 'com.github.sparkmuse:kotlin-oxford-dictionaries:1.0.8'

Authentication App Key and Id

Oxford Dictionaries comes with three price tiers: Prototype, Developer and Research. A key can be obtained by following the link https://developer.oxforddictionaries.com/?tag=#plans.

Use the AppId and AppKey when creating the client.

Usage & Examples

Use the OxfordClient class to interact with the API.

Retrieve entries for the word 'ace'

kotlin

@Test
fun `retrieve entries for the word 'ace'`() {

    val appId = System.getenv("APP_ID")
    val appKey = System.getenv("APP_KEY")
    val baseUrl = "https://od-api.oxforddictionaries.com/api/v2"

    val oxfordClient = OxfordClient(appId, appKey, baseUrl)

    val entries = oxfordClient.entries("ace")

    assertNotNull(entries)
}

java

@Test
@DisplayName("retrieve entries for the word 'ace'")
void entries() {

    String appId = System.getenv("APP_ID");
    String appKey = System.getenv("APP_KEY");
    String baseUrl = "https://od-api.oxforddictionaries.com/api/v2";

    OxfordClient oxfordClient = new OxfordClient(appId, appKey, baseUrl);

    RetrieveEntry entries = oxfordClient.entries("ace");

    assertNotNull(entries);
}

Retrieve entries for the word 'ace' with complex query

kotlin

@Test
fun `gets entries for the word 'ace' with complex query`() {

    val appId = System.getenv("APP_ID")
    val appKey = System.getenv("APP_KEY")
    val baseUrl = "https://od-api.oxforddictionaries.com/api/v2"

    val oxfordClient = OxfordClient(appId, appKey, baseUrl)

    val query = EntryQuery(
        word = "ace",
        sourceLanguage = LanguageMonolingual.English_us,
        fields = listOf(DataField.definitions),
        lexicalCategory = listOf("noun"),
        strictMatch = true
    )

    val entries = oxfordClient.entries(query)
    assertNotNull(entries)
}

java

@Test
@DisplayName("gets entries for the word 'ace' with complex query")
void complexQueryEntries() {

    String appId = System.getenv("APP_ID");
    String appKey = System.getenv("APP_KEY");
    String baseUrl = "https://od-api.oxforddictionaries.com/api/v2";

    OxfordClient oxfordClient = new OxfordClient(appId, appKey, baseUrl);

    EntryQuery query = new EntryQuery(
            "ace",
            LanguageMonolingual.English_us,
            List.of(DataField.definitions),
            List.of(),
            List.of("noun"),
            List.of(),
            List.of(),
            true);
    RetrieveEntry entries = oxfordClient.entries(query);

    assertNotNull(entries);
}

Retrieve grammatical features for 'en-us' language

kotlin

@Test
fun `gets grammatical features for 'en-us' language`() {

    val appId = System.getenv("APP_ID")
    val appKey = System.getenv("APP_KEY")
    val baseUrl = "https://od-api.oxforddictionaries.com/api/v2"

    val oxfordClient = OxfordClient(appId, appKey, baseUrl)

    val query = GrammaticalFeatureMonolingualQuery(
        sourceLanguage = LanguageMonolingual.English_us
    )

    val grammaticalFeature = oxfordClient.grammaticalFeatures(query)
    assertNotNull(grammaticalFeature)
}

java

@Test
@DisplayName("gets grammatical features for 'en-us' language")
void grammaticalFeatures() {

    String appId = System.getenv("APP_ID");
    String appKey = System.getenv("APP_KEY");
    String baseUrl = "https://od-api.oxforddictionaries.com/api/v2";

    OxfordClient oxfordClient = new OxfordClient(appId, appKey, baseUrl);

    GrammaticalFeatureMonolingualQuery query =
            new GrammaticalFeatureMonolingualQuery(LanguageMonolingual.English_us);

    RetrieveGrammaticalFeature grammaticalFeature = oxfordClient.grammaticalFeatures(query);
    assertNotNull(grammaticalFeature);
}