Making requests to the API

This step-by-step guide shows you how to build a request to the API using Python, one of many popular programming languages. There are code samples for other programming languages available in our Documentation.

Authentication

Each request requires an app_id and app_key to act as authentication. These are generated automatically when you create an account and are found on your App Credentials page. An incorrect or missing app_id or app_key will result in a 403 Authentication failed error.

We will use the ‘requests’ and ‘json’ python libraries to assist in making our request.

import  json
import  requests
app_id = "<my_app_id>"
app_key = "<my_app_key>"

GET request

The basic syntax of a URL request to the API is shown below:

url = "https://od-api.oxforddictionaries.com/api/v2/<endpoint>/<language_code>/<word_id>"

endpoint

Oxford Dictionaries API offers many different functions split into different endpoints. These include ‘entries’ (retrieve dictionary information about a word), ‘thesaurus’ (retrieve similar words), and ‘sentences’ (retrieve example sentences for a word). The full list and URL structure is available in the Documentation.

language_code

Oxford Dictionaries API contains many different languages each identified using a language code. You can find the language code for each on the Supported Languages page. In this example, we’ll look up the US English dictionary, the New Oxford American Dictionary, which has the language code en-us.

word_id

Word_id is a unique identifier that is very similar to an entry spelling. This is the word you are looking up.

Remember:

Some words are inflections, e.g., running, which don’t have an entry in the dictionary of their own. In this case, you will first use the Lemmas endpoint to retrieve the root form, which is then your word_id, e.g., running > run.
Don’t worry about encoding your word_id. The API does this for you. Example: `après-ski` will be converted to `apr%C3%A8s-ski`.
It is best practice to pass your word_id in lower case. You can use .lower() in Python to do this for you.

import json
import requests
app_id  = "<my_app_id>"
app_key  = "<my_app_key>"
endpoint = "entries"
language_code = "en-us"
word_id = "example"
url = "https://od-api.oxforddictionaries.com/api/v2/" + endpoint + "/" + language_code + "/" + word_id.lower()

Let's go!

Using the requests library in Python you can now send the HTTP request to the API and pass your authentication as headers. Below, we then parse and display the json output from the response.

import json
import requests
app_id  = "<my_app_id>"
app_key  = "<my_app_key>"
endpoint = "entries"
language_code = "en-us"
word_id = "example"
url = "https://od-api.oxforddictionaries.com/api/v2/" + endpoint + "/" + language_code + "/" + word_id.lower()
r = requests.get(url, headers = {"app_id": app_id, "app_key": app_key})
print("code {}\n".format(r.status_code))
print("text \n" + r.text)
print("json \n" + json.dumps(r.json()))

Advanced filtering

If you find that the API returns more data than you need, you can restrict the response to only return specified features.

Filters

Filters restrict which records are returned as part of the response. For example, you may only wish to see the noun form of a word.

lexicalCategory=<comma-separated-values> For example: lexicalCategory=noun or lexicalCategory=noun,verb
grammaticalFeatures=<comma-separated-values>. For instance: grammaticalFeatures=singular

Projections of fields

Projections of fields determine which parts of each record are returned with the response. For example, you may prefer only to see the word’s definitions, or its etymology, or pronunciation.

fields=<comma-separated-fields>

definitions
domains
etymologies
examples
pronunciations
regions
registers
variantForms

You can see which filters and projections are available for each endpoint by making a request to our Utility endpoints. Take a look at the Documentation to see how.

Have fun!