Oxford Dictionaries API Documentation

Oxford Dictionaries API Documentation

The Oxford Dictionaries API allows easy access to our world-renowned dictionary content. Use the live documentation below to try it out, view real responses, and explore a growing number of code samples to help you get started.

The documentation below is populated with a restricted App Key and App ID to allow you to try out the basic functionality, but to get full use of the API you need to sign up for an account. Once you login to your account the base URL for your API requests will be shown here.

Take a look at the FAQ page for lots of tips on how to get things done.

Implementation notes

/api/v2/entries/{source_lang}/{word_id}:

Use this to retrieve definitions, pronunciations

The way in which a word is pronounced.

We generally give pronunciations both as sound files and in a phonetic spelling.

E.g. through “Pronunciation: /θruː/”

, example sentences, grammatical information

A grammatical feature provides extra information about a lexicalCategory (see below). E.g. a grammaticalFeature may say that a noun is plural, or that a verb is intransitive.

and word origins

An account of the origin and historical development of the word.

E.g. ‘grammar’ has the etymology “Late Middle English: from Old French gramaire, via Latin from Greek grammatikē (tekhnē) '(art) of letters', from gramma, grammat- 'letter of the alphabet, thing written'.”

.
TIP: Entries ONLY works for dictionary headwords. You may need to use the Lemmas endpoint first to link an inflected form back to its headword (e.g., pixels --> pixel). Use filters to limit the entry

A complete account of a particular word. This can include a word’s senses, definitions, translations, origin, and any phrases featuring the word.

information that is returned. For example, you may only require definitions and not everything else, or just pronunciations

The way in which a word is pronounced.

We generally give pronunciations both as sound files and in a phonetic spelling.

E.g. through “Pronunciation: /θruː/”

. The full list of filters can be retrieved from the filters Utility endpoint. You can also specify values within the filter using '='. For example 'grammaticalFeatures=singular'. Filters can also be combined.
Combining different filters will build a query using 'AND' operators, while if a filter contains more than one value will build a query using 'OR' operators. For example, a combination of filters like '?gramaticalFeatures=singular&lexicalCategory=noun,verb' will return entries which match the query ('noun' OR 'verb') AND 'singular'.

/api/v2/lemmas/{source_lang}/{word_id}:

Use this to check if a word exists in the dictionary, or what 'root' form it links to (e.g., swimming > swim). The response tells you the possible lemmas

Lemma is a general term for any headword, phrase, or other form that can be looked up.

E.g. ‘act’, ‘acting’, ‘act up’, ‘get one’s act together’ are all lemmas.

for a given inflected

An inflection is a change in the form of a word to express a grammatical function such as tense, mood, person, number, case, or gender.

Example: ‘foxes’ is an inflected form of ‘fox’.

word. This can then be combined with other endpoints to retrieve more information.
The results can be filtered by lexicalCategories and/or grammaticalFeatures. Filters can be combined. Combining different filters will build a query using 'AND' operators, while if a filter contains more than one value will build a query using 'OR' operators. For example, a combination of filters like '?gramaticalFeatures=singular&lexicalCategory=noun,verb' will return entries which match the query ('noun' OR 'verb') AND 'singular'.

/api/v2/search/translations/{source_lang_search}/{target_lang_search}:

Use this to find possible translations for a given word.

/api/v2/search/{source_lang}:

Use this to retrieve possible headword

The headword is the word being defined or translated.

matches for a given string of text. The results are calculated using headword matching, fuzzy matching, and lemmatization

Lemma is a general term for any headword, phrase, or other form that can be looked up.

E.g. ‘act’, ‘acting’, ‘act up’, ‘get one’s act together’ are all lemmas.

.

/api/v2/translations/{source_lang_translate}/{target_lang_translate}/{word_id}:

Use this to return translations for a given word. In the event that a word in the dataset does not have a direct translation, the response will be a definition

A complete account of a particular word. This can include a word’s senses, definitions, translations, origin, and any phrases featuring the word.

in the target language.

/api/v2/thesaurus/{lang}/{word_id}:

Use this to retrieve words that are similar/opposite in meaning to the input word (synonym

A word which is similar in meaning to another word, e.g. ‘enthusiastic’ is a synonym of ‘keen’.

/antonym

A word which is opposite in meaning to another word, e.g. ‘apathetic’ is an antonym of ‘enthusiastic’.

).
Tip: Some Entries responses contain sense-level links to a Thesaurus entry by the property "thesaurusLink". For instance:
  •                                             
                                                    {
                                                        "thesaurusLinks": [
                                                            {
                                                                "entry_id": "abide_by",
                                                                "sense_id": "t_en_gb0000029.003"
                                                            }
                                                        ]
                                                    }
                                                
                                            

/api/v2/sentences/{source_lang}/{word_id}:

Use this to retrieve sentences extracted from a corpus of real-world language, including news and blog content. This is available for English and Spanish. For English, the sentences are linked to the correct sense

A sense is a particular meaning of a word.

Example: the word ‘mouse’ has the following senses:

1) A small rodent that typically has a pointed snout, relatively large ears and eyes, and a long tail.

2) A small handheld device which is moved across a mat or flat surface to move the cursor on a computer screen.

of the word in the dictionary. In Spanish, they are linked at the headword

The headword is the word being defined or translated.

level.

/api/v2/stats/frequency/ngrams/{source_lang}/{corpus}/{ngram-size}:

This endpoint returns frequencies of ngrams of size 1-4 from our New Monitor Corpus. That is the number of times a word (ngram size = 1) or words (ngram size > 1) appear in the corpus. Ngrams are case sensitive ("I AM" and "I am" will have different frequency) and frequencies are calculated per word (true case) so "the book" and "the books" are two different ngrams. The results can be filtered based on query parameters. Parameters can be provided in PATH, GET or POST (form or json). The parameters in PATH are overridden by parameters in GET, POST and json (in that order). In PATH, individual options are separated by semicolon and values are separated by commas (where multiple values can be used). Example for bigrams (ngram of size 2): PATH: /tokens=a word,another word GET: /?tokens=a word&tokens=another word * POST (json):
  •                                             
                                                    {
                                                        "tokens": ["a word", "another word"]
                                                    }
                                                
                                            
Either "tokens" or "contains" has to be provided. Some queries with "contains" or "sort" can exceed the 30s timeout, in which case the API will return an error message with status code 503. You mitigate this by providing additional restrictions such as "minFrequency" and "maxFrequency". You can use the parameters "offset" and "limit" to paginate through large result sets. For convenience, the HTTP header "Link" is set on the response to provide links to "first", "self", "next", "prev" and "last" pages of results (depending on the context). For example, if the result set contains 50 results and the parameter "limit" is set to 25, the Links header will contain an URL for the first 25 results and the next 25 results. Some libraries such as python's requests can parse the header automatically and offer a convenient way of iterating through the results. For example: python def get_all_results(url): while url: r = requests.get(url) r.raise_for_status() for item in r.json()['results']: yield item url = r.links.get('next', {}).get('url')

/api/v2/stats/frequency/word/{source_lang}:

This endpoint provides the frequency of a given word, i.e., how many times that word appears in a large database of material (news articles, blogs, academic papers, etc.). This can be very useful for comparing words or determining it's prevalence in language. When multiple database records match the query parameters, the returned frequency is the sum of the individual frequencies. For example, if the query parameters are lemma=test, the returned frequency will include the verb "test", the noun "test" and the adjective "test" in all forms (Test, tested, testing, etc.) If you are interested in the frequency of the word "test" but want to exclude other forms (e.g., tested) use the option trueCase=test. Normally, the word "test" will be spelt with a capital letter at the beginning of a sentence. The option trueCase will ignore this and it will count "Test" and "test" as the same token. If you are interested in frequencies of "Test" and "test", use the option wordform=test or wordform=Test. Note that trueCase is not just a lower case of the word as some words are genuinely spelt with a capital letter such as the word "press" in Oxford University Press. Parameters can be provided in PATH, GET or POST (form or json). The parameters in PATH are overridden by parameters in GET, POST and json (in that order). In PATH, individual options are separated by semicolon and values are separated by commas (where multiple values can be used). Examples:
  • PATH: /lemma=test;lexicalCategory=noun
  • GET: /?lemma=test&lexicalCategory=noun
  • POST (json):
                                                    { "lemma": "test", "lexicalCategory": "noun"}
                                                
One of the options wordform/trueCase/lemma/lexicalCategory has to be provided.

/api/v2/stats/frequency/words/{source_lang}:

This endpoint provides a list of frequencies for a given word or words. Unlike the /word/ endpoint, the results are split into the smallest units. To exclude a specific value, prepend it with the minus sign ('-'). For example, to get frequencies of the lemma 'happy' but exclude superlative forms (i.e., happiest) you could use options 'lemma=happy;grammaticalFeatures=-degreeType:superlative'. Parameters can be provided in PATH, GET or POST (form or json). The parameters in PATH are overridden by parameters in GET, POST and json (in that order). In PATH, individual options are separated by semicolon and values are separated by commas (where multiple values can be used). The parameters wordform/trueCase/lemma/lexicalCategory also exist in a plural form, taking a lists of items. Examples: PATH: /wordforms=happy,happier,happiest GET: /?wordforms=happy&wordforms=happier&wordforms=happiest * POST (json): javascript { "wordforms": ["happy", "happier", "happiest"] } A more complex example of retrieving frequencies of multiple lemmas: { "lemmas": ["happy", "content", "cheerful", "cheery", "merry", "joyful", "ecstatic"], "grammaticalFeatures": { "adjectiveFunctionType": "predicative" }, "lexicalCategory": "adjective", "sort": ["lemma", "-frequency"] } Some queries with "collate" or "sort" can exceed the 30s timeout, in which case the API will return an error message with status code 503. You mitigate this by providing additional restrictions such as "minFrequency" and "maxFrequency". You can use the parameters "offset" and "limit" to paginate through large result sets. For convenience, the HTTP header "Link" is set on the response to provide links to "first", "self", "next", "prev" and "last" pages of results (depending on the context). For example, if the result set contains 50 results and the parameter "limit" is set to 25, the Links header will contain an URL for the first 25 results and the next 25 results. Some libraries such as python's requests can parse the header automatically and offer a convenient way of iterating through the results. For example: python def get_all_results(url): while url: r = requests.get(url) r.raise_for_status() for item in r.json()['results']: yield item url = r.links.get('next', {}).get('url')

/api/v2/domains/{source_lang}:

Returns a list of the available domains

Domain labels give the subject area of a word or sense (e.g. Music, Computing, Politics).

E.g. ‘cardiogram’ has the domain class “Medicine”.

for a given monolingual language dataset.

/api/v2/domains/{source_lang_domains}/{target_lang_domains}:

Returns a list of the available domains

Domain labels give the subject area of a word or sense (e.g. Music, Computing, Politics).

E.g. ‘cardiogram’ has the domain class “Medicine”.

for a given bilingual language dataset.

/api/v2/fields:

Returns a list of the available fields to construct API requests.

/api/v2/fields/{endpoint}:

Returns the lists of fields available to construct API requests for a given endpoint.

/api/v2/filters:

Returns a list of all the valid filters to construct API requests.

/api/v2/filters/{endpoint}:

Returns a list of all the valid filters by endpoint to construct API requests.

/api/v2/grammaticalFeatures/{source_lang_grammatical}/{target_lang_grammatical}:

Returns a list of the available grammatical features

A grammatical feature provides extra information about a lexicalCategory (see below). E.g. a grammaticalFeature may say that a noun is plural, or that a verb is intransitive.

for a given bilingual dataset.

/api/v2/languages:

Returns the names of monolingual and bilingual language datasets available in the API

/api/v2/lexicalCategories/{source_lang_lexical}/{target_lang_lexical}:

Returns a list of available lexical categories

The linguistic category of a word, e.g. the part of speech (‘noun’, ‘verb’, ‘adjective’ etc.), or other category (‘abbreviation’, ‘symbol’ etc.).

for a given bilingual dataset.

/api/v2/words/{source_lang}:

Use this endpoint to retrieve definitions, examples and other information for a given dictionary word or an inflection (e.g., running > run). The response contains information about the lemmas to which the given word/inflected form is linked.

The results can be filtered by lexicalCategories, domains, registers or grammaticalFeatures. Filters can be combined.

In addition, Users can use fields to project some of the properties.

Combining different filters will build a query using 'AND' operators, while if a filter contains more than one value it will build a query using 'OR' operators. For example, a combination of filters like '?gramaticalFeatures=singular&lexicalCategory=noun,verb' will return entries which match the query ('noun' OR 'verb') AND 'singular'.