Introduction

Words API is organized around RESTful principles. JSON will be returned in all responses from the API, including errors.

Access to the API is provided by Rapid API.

Authentication

To authorize, pass in your RapidAPI key as a X-Mashape-Key header:

# These code snippets use an open-source library. http://unirest.io/ruby
response = Unirest.get "https://wordsapiv1.p.mashape.com/words/soliloquy",
  headers:{
    "X-Mashape-Key" => "<required>",
    "Accept" => "application/json"
  }

# These code snippets use an open-source library. http://unirest.io/python
response = unirest.get("https://wordsapiv1.p.mashape.com/words/soliloquy",
  headers={
    "X-Mashape-Key": "<required>",
    "Accept": "application/json"
  }
)

// These code snippets use an open-source library. http://unirest.io/php
$response = Unirest\Request::get("https://wordsapiv1.p.mashape.com/words/soliloquy",
  array(
    "X-Mashape-Key" => "<required>",
    "Accept" => "application/json"
  )
);

# With shell, you can just pass the correct header with each request
curl "https://wordsapiv1.p.mashape.com/words/soliloquy"
  -H "X-Mashape-Key: <required>"

// These code snippets use an open-source library. http://unirest.io/nodejs
unirest.get("https://wordsapiv1.p.mashape.com/words/soliloquy")
.header("X-Mashape-Key", "<required>")

Make sure to replace <required> with your API key.

Access to the API is provided by RapidAPI. You'll need to a valid RapidAPI account to connect.

You must replace required with your Rapid API key.

Words

Get a Word

# These code snippets use an open-source library. http://unirest.io/ruby
response = Unirest.get "https://wordsapiv1.p.mashape.com/words/soliloquy",
  headers:{
    "X-Mashape-Key" => "<required>",
    "Accept" => "application/json"
  }

// These code snippets use an open-source library. http://unirest.io/php
$response = Unirest\Request::get("https://wordsapiv1.p.mashape.com/words/soliloquy",
  array(
    "X-Mashape-Key" => "<required>",
    "Accept" => "application/json"
  )
);

# These code snippets use an open-source library. http://unirest.io/python
response = Unirest.get "https://wordsapiv1.p.mashape.com/words/soliloquy",
  headers={
    "X-Mashape-Key": "<required>",
    "Accept": "application/json"
  }
)

curl "https://wordsapiv1.p.mashape.com/words/soliloquy"
  -H "X-Mashape-Key: <required>"

// These code snippets use an open-source library. http://unirest.io/nodejs
unirest.get("https://wordsapiv1.p.mashape.com/words/soliloquy")
.header("X-Mashape-Key", "<required>")
.header("Accept", "application/json")
.end(function (result) {
  console.log(result.status, result.headers, result.body);
});

The above command returns JSON structured like this:

{  
   "results":[  
      {  
         "definition":"speech you make to yourself",
         "partOfSpeech":"noun",
         "synonyms":[  
            "monologue"
         ],
         "typeOf":[  
            "speech",
            "voice communication",
            "speech communication",
            "spoken communication",
            "spoken language",
            "language",
            "oral communication"
         ],
         "derivation":[  
            "soliloquize"
         ]
      },
      {  
         "definition":"a (usually long) dramatic speech intended to give the illusion of unspoken reflections",
         "partOfSpeech":"noun",
         "typeOf":[  
            "actor's line",
            "speech",
            "words"
         ],
         "derivation":[  
            "soliloquize"
         ]
      }
   ],
   "syllables":{  
      "count":4,
      "list":[  
         "so",
         "lil",
         "o",
         "quy"
      ]
   },
   "pronunciation":{  
      "all":"sə'lɪləkwi"
   }
}

To retrieve all details of a word, make a GET request to the API endpoint with the word itself as the final part of the URL.

Unless you ask for specific details of word, the results of a call to the Words api will return everything known about a word, grouped by definition.

HTTP Request

GET https://wordsapiv1.p.mashape.com/words/{word}

Get Word Details

# These code snippets use an open-source library. http://unirest.io/ruby
response = Unirest.get "https://wordsapiv1.p.mashape.com/words/lovely/synonyms",
  headers:{
    "X-Mashape-Key" => "<required>",
    "Accept" => "application/json"
  }

# These code snippets use an open-source library. http://unirest.io/python
response = Unirest.get "https://wordsapiv1.p.mashape.com/words/lovely/synonyms",
  headers={
    "X-Mashape-Key": "<required>",
    "Accept": "application/json"
  }
)

// These code snippets use an open-source library. http://unirest.io/php
$response = Unirest\Request::get("https://wordsapiv1.p.mashape.com/words/lovely/synonyms",
  array(
    "X-Mashape-Key" => "<required>",
    "Accept" => "application/json"
  )
);

curl https://wordsapiv1.p.mashape.com/words/lovely/synonyms
  -H "Authorization: <required>"

unirest.get("https://wordsapiv1.p.mashape.com/words/lovely/synonyms")
.header("X-Mashape-Key", "<required>")
.header("Accept", "application/json")
.end(function (result) {
  console.log(result.status, result.headers, result.body);
});

The above command returns JSON structured like this:

{  
   "synonyms":[  
      "adorable",
      "endearing",
      "cover girl",
      "pin-up"
   ]
}

To retrieve a specific set of details of a word, for instance, a word's synonyms, append the detail type to the URL string.

These are the types of details you can retrieve:

definitions

The meaning of the word, including its part of speech.

synonyms

Words that can be interchanged for the original word in the same context.

antonyms

Words that have the opposite context of the original word.

examples

Example sentences using the word.

typeOf

Words that are more generic than the original word. Also known as hypernyms.

For example, a hatchback is a type of car.

hasTypes

Words that are more specific than the original word. Also known as hyponyms.

For example, purple has types violet, lavender, mauve, etc.

partOf

The larger whole to which this word belongs. Also known as holonyms.

For example, a finger is part of a hand, a glove, a paw, etc.

hasParts

Words that are part of the original word. Also known as meronyms.

For example, a building has parts such as roofing, plumbing etc.

instanceOf

Words that the original word is an example of.

For example, Einstein is an instance of a physicist.

hasInstances

Words that are examples of the original word.

For example, president has instances such as theodore roosevelt, van buren, etc.

similarTo

Words that similar to the original word, but are not synonyms.

For example, red is similar to bloody.

also

Phrases to which the original word belongs.

For example, bump is used in the phrase bump off.

entails

Words that are implied by the original word. Usually used for verbs.

For example, rub entails touch.

memberOf

A group to which the original word belongs.

For example, dory is a member of the family zeidae.

hasMembers

Words that belong to the group defined by the original word.

For example, a cult has members called cultists.

substanceOf

Substances to which the original word is a part of.

For example, water is a substance of sweat.

hasSubstances

Substances that are part of the original word.

For example, wood has a substance called lignin.

inCategory

The domain category to which the original word belongs.

For example, chaotic is in category physics.

hasCategories

Categories of the original word.

For example, math has categories such as algebra, imaginary, numerical analysis, etc.

usageOf

Words that the original word is a domain usage of.

For example, advil is a useage of the trademark, etc.

hasUsages

Words that are examples of the domain the original word defines.

For example, colloquialism is a domain that includes examples like big deal, blue moon, etc.

inRegion Regions where the word is used.

For example, chips is used in region Britain.

regionOf

A region where words are used.

For example, Canada is the region of pogey.

pertainsTo

Words to which the original word is relevant

For example, .22-caliber pertains to caliber.

HTTP Request

GET https://wordsapiv1.p.mashape.com/words/{word}/{detail type}

Pronunciation

# These code snippets use an open-source library. http://unirest.io/ruby
response = Unirest.get "https://wordsapiv1.p.mashape.com/words/effect",
  headers:{
    "X-Mashape-Key" => "<required>",
    "Accept" => "application/json"
  }

# These code snippets use an open-source library. http://unirest.io/python
response = Unirest.get "https://wordsapiv1.p.mashape.com/words/effect",
  headers={
    "X-Mashape-Key": "<required>",
    "Accept": "application/json"
  }
)

// These code snippets use an open-source library. http://unirest.io/php
$response = Unirest\Request::get("https://wordsapiv1.p.mashape.com/words/effect",
  array(
    "X-Mashape-Key" => "<required>",
    "Accept" => "application/json"
  )
);

curl https://wordsapiv1.p.mashape.com/words/effect
  -H "Authorization: <required>"

unirest.get("https://wordsapiv1.p.mashape.com/words/effect")
.header("X-Mashape-Key", "<required>")
.header("Accept", "application/json")
.end(function (result) {
  console.log(result.status, result.headers, result.body);
});

The above command returns JSON structured like this:

{  
   "results":[  
      ...
   ],
   "syllables":{  
      "count":2,
      "list":[  
         "ef",
         "fect"
      ]
   },
   "pronunciation":{  
      "noun":"'ɪ,fɛkt",
      "verb":",ɪ'fɛkt"
   }
}

Results from the API will include information on how to pronounce the word, using the International Phonetic Alphabet (IPA).

The pronunciation object may contain more than one key/value pair, if the word is pronounced differently depending on the part of speech it is used as. For instance, the word "effect" is pronounced differently if it is used as a noun than it is as a verb.

If a word is pronounced the same regardless of the part of speech it is used as, the pronunciation object will contain a key called "all", whose value is the pronunciation of the word in all cases.

Please note: The IPA uses a single quote character to indicate which phenome should receive the primary stress. The single quote character can cause problems in some parsers, so take care.

HTTP Request

GET https://wordsapiv1.p.mashape.com/words/{word}

Rhymes

# These code snippets use an open-source library. http://unirest.io/ruby
response = Unirest.get "https://wordsapiv1.p.mashape.com/words/dog/rhymes",
  headers:{
    "X-Mashape-Key" => "<required>",
    "Accept" => "application/json"
  }

# These code snippets use an open-source library. http://unirest.io/python
response = Unirest.get "https://wordsapiv1.p.mashape.com/words/dog/rhymes",
  headers={
    "X-Mashape-Key": "<required>",
    "Accept": "application/json"
  }
)

// These code snippets use an open-source library. http://unirest.io/php
$response = Unirest\Request::get("https://wordsapiv1.p.mashape.com/words/dog/rhymes",
  array(
    "X-Mashape-Key" => "<required>",
    "Accept" => "application/json"
  )
);

curl https://wordsapiv1.p.mashape.com/words/dog/rhymes
  -H "Authorization: <required>"

unirest.get("https://wordsapiv1.p.mashape.com/words/dog/rhymes")
.header("X-Mashape-Key", "<required>")
.header("Accept", "application/json")
.end(function (result) {
  console.log(result.status, result.headers, result.body);
});

The above command returns JSON structured like this:

{  
   "word":"dog",
   "rhymes":{  
      "all":[  
         "decalogue",
         "demagogue",
         "antilog",
         "apologue",
         "backlog",
         "bulldog",
         "dialog",
         "dialogue",
         "duologue",
         "emmenagogue",
         "epilogue",
         "firedog",
         "galactagogue",
         "hangdog",
         "hog",
         "hogg",
         "ideologue",
         "log",
         "monologue",
         "sheepdog",
         "sundog",
         "underdog",
         "warthog",
         "waterdog"
      ]
   }
}

WordsAPI can be used to find words that rhyme. Rhymes are not returned as part of a normal request, so you must call the Rhymes endpoint to retrieve rhymes of a word.

The rhymes result will include an object containing the word you requested, and one or more sub-objects that each contain a list of rhyming words. Each sub-object represents the part of speech that the rhymes are for.

For instance, "dog" can be both a noun and a verb. However, it is pronounced the same in both cases, so the result of the call to the Rhymes endpoint results in a single sub-object, called "all".

However, "wind" sounds different if you're using it as a noun (that's a lot of wind) than it does as a verb (the river winds through the hills). The result of calling the Rhymes endpoint for wind returns two arrays, one for wind as a noun, and another for wind as a verb.

HTTP Request

GET https://wordsapiv1.p.mashape.com/words/{word}/rhymes

Frequency

# These code snippets use an open-source library. http://unirest.io/ruby
response = Unirest.get "https://wordsapiv1.p.mashape.com/words/apartment/frequency",
  headers:{
    "X-Mashape-Key" => "<required>",
    "Accept" => "application/json"
  }

# These code snippets use an open-source library. http://unirest.io/python
response = Unirest.get "https://wordsapiv1.p.mashape.com/words/apartment/frequency",
  headers={
    "X-Mashape-Key": "<required>",
    "Accept": "application/json"
  }
)

// These code snippets use an open-source library. http://unirest.io/php
$response = Unirest\Request::get("https://wordsapiv1.p.mashape.com/words/apartment/frequency",
  array(
    "X-Mashape-Key" => "<required>",
    "Accept" => "application/json"
  )
);

curl https://wordsapiv1.p.mashape.com/words/apartment/frequency
  -H "Authorization: <required>"

unirest.get("https://wordsapiv1.p.mashape.com/words/apartment/frequency")
.header("X-Mashape-Key", "<required>")
.header("Accept", "application/json")
.end(function (result) {
  console.log(result.status, result.headers, result.body);
});

The above command returns JSON structured like this:

{  
   "word":"apartment",
   "frequency":{  
      "zipf":4.82,
      "perMillion":65.76,
      "diversity":0.17
   }
}

When you retrieve a word, it will have a frequency score, ranging from approximately 1 to 7. A higher number means the word is used more frequently.

While the /words/{word} endpoint returns just a frequency score, calling the /words/{word}/frequency endpoint will return more details.

zipf

The same number returned from the main endpoint, this is a log10 number representing the frequency of the word. For more details, see this paper.

perMillion

This is the number of times the word is likely to appear in any English corpus, per million words.

diversity

A scale ranging from 0 - 1 that represents the likelyhood the word will appear in a document that is part of a corpus. A greater diversity score may be related to how fast a word can be recalled by a person.

HTTP Request

GET https://wordsapiv1.p.mashape.com/words/{word}/frequency

Searching

# These code snippets use an open-source library. http://unirest.io/ruby
response = Unirest.get "https://wordsapiv1.p.mashape.com/words?letterPattern=^a.{4}$",
  headers:{
    "X-Mashape-Key" => "<required>",
    "Accept" => "application/json"
  }

# These code snippets use an open-source library. http://unirest.io/python
response = Unirest.get "https://wordsapiv1.p.mashape.com/words?letterPattern=^a.{4}$",
  headers={
    "X-Mashape-Key": "<required>",
    "Accept": "application/json"
  }
)

// These code snippets use an open-source library. http://unirest.io/php
$response = Unirest\Request::get("https://wordsapiv1.p.mashape.com/words?letterPattern=^a.{4}$",
  array(
    "X-Mashape-Key" => "<required>",
    "Accept" => "application/json"
  )
);

curl https://wordsapiv1.p.mashape.com/words?letterPattern=^a.{4}$
  -H "Authorization: <required>"

unirest.get("https://wordsapiv1.p.mashape.com/words?letterPattern=^a.{4}$")
.header("X-Mashape-Key", "<required>")
.header("Accept", "application/json")
.end(function (result) {
  console.log(result.status, result.headers, result.body);
});

The above command returns JSON structured like this:

{  
   "query":{  
      "letterPattern":"^a.{4}$",
      "limit":100,
      "page":1
   },
   "results":{  
      "total":805,
      "data":[  
         "aalst",
         "aalto",
         "aarau",
         "aaron",
         "abaca",
         "abaci",
         "aback",
         "abaco",
         ... 
         "addax",
         "adder"
      ]
   }
}

You can search for words using any combination of the parameters listed below.

letterPattern

Find words whose letters match a regular expression.

For instance, to find all 5 letters words that start with the letter 'a', you would use:

https://wordsapiv1.p.mashape.com/words/?letterPattern=^a.{4}$

Be sure to properly encode your regular expression before you make your HTTP request.

letters

Find words with a specific number of letters.

For instance, to find all 6 letter words, you would use:

https://wordsapiv1.p.mashape.com/words/?letters=6

lettersMin

Find words with at least the specified number of letters.

For instance, to find all words with at least 12 letters, you would use:

https://wordsapiv1.p.mashape.com/words/?lettersMin=12

lettersMax

Find words with at most the specified number of letters.

For instance, to find all words with at most 4 letters, you would use:

https://wordsapiv1.p.mashape.com/words/?lettersMax=4

pronunciationPattern

Find words whose pronunciation matches a regular expression.

For instance, to find all words that end with the "æm" sound (as in the end of "diagram"), you would use:

https://wordsapiv1.p.mashape.com/words/?pronunciationPattern=.*æm$

Be sure to properly encode your regular expression before you make your HTTP request.

sounds

Find words with a specific number of sounds, based on the number of IPA phonemes used in the pronunciation.

For instance, to find words with 5 phonemes, you would use:

https://wordsapiv1.p.mashape.com/words/?sounds=5

soundsMin

Find words with at least the specified number of sounds.

For instance, to find all words with at least 12 phonemes, you would use:

https://wordsapiv1.p.mashape.com/words/?soundsMin=12

soundsMax

Find words with at most the specified number of phonemes.

For instance, to find all words with at most 4 phonemes, you would use:

https://wordsapiv1.p.mashape.com/words/?soundsMax=4

partOfSpeech

Find words with at least one definition whose part of speech matches the specified value.

For instance, to find all verbs:

https://wordsapiv1.p.mashape.com/words/?partOfSpeech=verb

hasDetails

Find words that have at least one instance of the detail type. See the documentation for Word Details for a complete list of detail types you can search for.

To find words with more than one type of detail, send a comma separated list.

For instance, to find words that have a "typeOf" detail type:

https://wordsapiv1.p.mashape.com/words/?hasDetails=typeOf

limit

The most number of results to return in one request. Must be between 1 and 100. Default is 100.

page The page of results to return. Default is 1.

HTTP Request

GET https://wordsapiv1.p.mashape.com/words?letterPattern=^a.{4}$

Random Words

# These code snippets use an open-source library. http://unirest.io/ruby
response = Unirest.get "https://wordsapiv1.p.mashape.com/words?random=true",
  headers:{
    "X-Mashape-Key" => "<required>",
    "Accept" => "application/json"
  }

# These code snippets use an open-source library. http://unirest.io/python
response = Unirest.get "https://wordsapiv1.p.mashape.com/words?random=true",
  headers={
    "X-Mashape-Key": "<required>",
    "Accept": "application/json"
  }
)

// These code snippets use an open-source library. http://unirest.io/php
$response = Unirest\Request::get("https://wordsapiv1.p.mashape.com/words?random=true",
  array(
    "X-Mashape-Key" => "<required>",
    "Accept" => "application/json"
  )
);

curl https://wordsapiv1.p.mashape.com/words?random=true
  -H "Authorization: <required>"

unirest.get("https://wordsapiv1.p.mashape.com/words?random=true")
.header("X-Mashape-Key", "<required>")
.header("Accept", "application/json")
.end(function (result) {
  console.log(result.status, result.headers, result.body);
});

The above command returns JSON structured like this:

{  
   "word":"ventriloquist",
   "frequency":3.39,
   "results":[  
      {  
         "definition":"a performer who projects the voice into a wooden dummy",
         "partOfSpeech":"noun",
         "typeOf":[  
            "performer",
            "performing artist"
         ],
         "derivation":[  
            "ventriloquism",
            "ventriloquy"
         ]
      }
   ],
   "syllables":{  
      "count":4,
      "list":[  
         "ven",
         "tril",
         "o",
         "quist"
      ]
   },
   "pronunciation":{  
      "all":"vɛn'trɪləkwɪst"
   }
}

You can use the Search capability to find a random word matching your search criteria.

Just append random=true to your request. Only one word will be returned.

HTTP Request

GET https://wordsapiv1.p.mashape.com/words?random=true

Errors

Words API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with the Words API servers.

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
404	Not Found -- No matching word was found.
500	Internal Server Error -- We had a problem with our server. Try again later.