How to Build a Word Definition Widget with WordsAPI

One of the most common uses of WordsAPI is to let users look up definitions for words.  It's incredibly easy to accomplish - we'll do it in less than 100 lines of javascript.  If you want to see it in action, here it is.

We'll start by creating a simple form that will auto-suggest words as the user types. We'll add some simple styling using the Yahoo Pure css library.  We'll also add in an unordered list where the results will be displayed.

       
<form onsubmit="return false;" class="pure-form" style="border-top: 1px solid #eee;border-bottom:1px solid #eee;background:#fafafa;margin:30px 0;padding:20px 10px;text-align:center">
  <input id="user-input" autofocus type="text" placeholder="Type a word ..." style="width:100%;max-width:600px;outline:0" />
</form>
<ul id="definitions"></ul>

For the auto-complete functionality, we'll be including a small library from Pixabay. This library will handle populating the suggestion list that we get.  The library needs a function to call when the users types. We'll configure the library using the code below. The source attribute is a function that gets called when the user types. It sends in a term, and waits until a list of suggestions are provided.

       
new autoComplete({
  selector: "#user-input",
  minChars: 1,
  source: function(term, suggest) {
    getSuggestions(term).then(response => {
      suggest(response.results.data);
    });
  },
  onSelect: function(e, term, item) {
    getDefinitions(term).then(showDefinitions);
  }
});

The getSuggestions function is where we'll link into WordsAPI. You'll need your own API key, which you can get from here. The function makes use of the WordsAPI search capabilities by providing a letterPattern that will match any words that start with the letters the user has provided, as well as restricting the results to only words that have definitions.

       
function getSuggestions(input) {
  const url = `https://wordsapiv1.p.mashape.com/words/?letterPattern=^${input}.*&hasDetails=definitions`;
  return fetch(url, {
    method: "GET",
    headers: {
      "Content-Type": "application/json",
      "X-RapidAPI-Key": apiKey
    }
  }).then(resp => resp.json());
}

When the users selects a word from the suggestions list, the onSelect attribute of the autoComplete library will get called.  This will pass the results to the getDefinitions function, defined below.  This function again calls out to WordsAPI, this time to get the definitions of the selected word.

       
function getDefinitions(term) {
  const url = `https://wordsapiv1.p.mashape.com/words/${term}`;
  return fetch(url, {
    method: "GET",
    headers: {
      "Content-Type": "application/json",
      "X-RapidAPI-Key": apiKey
    }
  })
    .then(resp => resp.json())
    .then(resp => {
      return resp.results;
    });
}

Finally, we'll show the results in a list below the input field in our showDefinitions function.

       
function showDefinitions(definitions) {
  definitionList.innerHTML = "";
  definitions.forEach(definition => {
    const li = document.createElement("li");
    li.textContent = `${definition.partOfSpeech} - ${definition.definition}`;
    definitionList.appendChild(li);
  });
}

And that's it! You can see a fully working version at this CodePen.
posted on