NAV Navbar
shell ruby python javascript php
  • Introduction
  • Authentication
  • Words
  • Errors
  • 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.

    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:

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

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

    Words that have the opposite context of the original word.

    Example sentences using the word.

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

    For example, a hatchback is a type of car.

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

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

    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.

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

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

    Words that the original word is an example of.

    For example, Einstein is an instance of a physicist.

    Words that are examples of the original word.

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

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

    For example, red is similar to bloody.

    Phrases to which the original word belongs.

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

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

    For example, rub entails touch.

    A group to which the original word belongs.

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

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

    For example, a cult has members called cultists.

    Substances to which the original word is a part of.

    For example, water is a substance of sweat.

    Substances that are part of the original word.

    For example, wood has a substance called lignin.

    The domain category to which the original word belongs.

    For example, chaotic is in category physics.

    Categories of the original word.

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

    Words that the original word is a domain usage of.

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

    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.

    For example, chips is used in region Britain.

    A region where words are used.

    For example, Canada is the region of pogey.

    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.

    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.

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

    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.

    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.

    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

    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

    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

    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.

    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

    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

    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

    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

    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

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

    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.