Documentation

You can use an interactive version of this documentation on Mashape!

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 Mashape.

 

API ENDPOINT

https://wordsapiv1.p.mashape.com/words/


Authentication

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

 

curl https://wordsapiv1.p.mashape.com/words/soliloquy

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.

 

HTTP Status Code Summary

  • 200 OK - Everything worked as expected.
  • 400 Bad Request - Often missing a required parameter, or a paramater was not the right type.
  • 401 Unauthorized - No access token, or it isn't valid.
  • 404 Not Found - The requested item doesn't exist.
  • 429 Too Many Requests - Rate limit exceeded.
  • 500 Server Error - Something went wrong with Words API.

Words

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.

 

curl https://wordsapiv1.p.mashape.com/words/soliloquy { "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" } }

Word Details

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 it's 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.

 

curl https://wordsapiv1.p.mashape.com/words/lovely/synonyms { "synonyms": [ "adorable", "endearing", "cover girl", "pin-up" ] }
curl https://wordsapiv1.p.mashape.com/words/finger/partOf { "partOf": [ "mitt", "manus", "paw", "hand", "glove" ] }
curl https://wordsapiv1.p.mashape.com/words/chaotic/inCategory { "inCategory": [ "physics" ] }
curl https://wordsapiv1.p.mashape.com/words/god/hasInstances { "hasInstances": [ "lohan", "morpheus", "quetzalcoatl", "bodhisattva", "boddhisatva", "arhat", "hypnos", "arhant", "demogorgon", "jehovah", "allah", "godhead", "yahweh", "jhvh", "god almighty", "lord", "divine", "jahvey", "maker", "jahweh", "almighty", "yhvh", "wahvey", "creator", "yahve", "yhwh", "yahveh", "yahwe" ] }
curl https://wordsapiv1.p.mashape.com/words/effect/hasTypes { "hasTypes": [ "serve", "carry out", "carry through", "execute", "fulfil", "fulfill", "draw", "get", "precipitate", "hasten", "induce", "rush", "stimulate", "accomplish", "action", "tout ensemble", "mark", "image", "figure", "coattails effect", "materialisation", "materialization", "offspring", "aftereffect", "aftermath", "backwash", "wake", "bandwagon effect", "brisance", "butterfly effect", "by-product", "byproduct", "change", "coriolis effect", "dent", "domino effect", "harvest", "impact", "wallop", "influence", "knock-on effect", "branch", "offset", "offshoot", "outgrowth", "product", "placebo effect", "position effect", "repercussion", "reverberation", "response", "fallout", "side effect", "spillover", "backdate", "carry", "bring to bear", "sound effect", "special effect", "bummer" ] }

Syllables

Results from the API will include the number of syllables in the word, if known, along with a list of syllables.

 

curl https://wordsapiv1.p.mashape.com/words/extemporize { "results": [ ... ], "syllables": { "count": 4, "list": [ "ex", "tem", "po", "rize" ] }, "pronunciation": { "all": "ɪk'stɛmpə,raɪz" } }

Pronunciation

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.

 

curl https://wordsapiv1.p.mashape.com/words/effect { "results": [ ... ], "syllables": { "count": 2, "list": [ "ef", "fect" ] }, "pronunciation": { "noun": "'ɪ,fɛkt", "verb": ",ɪ'fɛkt" } }

Rhymes

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.

 

curl https://wordsapiv1.p.mashape.com/words/dog/rhymes { "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" ] } } curl https://wordsapiv1.p.mashape.com/words/wind/rhymes { "word": "wind", "rhymes": { "noun": [ "determined", "downwind", "headwind", "lind", "rescind", "sind", "skinned", "tailwind", "thin-skinned", "tinned", "twinned", "undetermined", "upwind", "whirlwind", "woodwind" ], "verb": [ "designed", "affined", "behind", "bind", "blind", "combined", "confined", "disinclined", "find", "grind", "hind", "humankind", "inclined", "kind", "mankind", "mastermind", "mind", "purblind", "rebind", "refined", "remind", "rind", "sand-blind", "snow-blind", "spellbind", "streamlined", "unassigned", "unbind", "unconfined", "undefined", "undesigned", "unkind", "unlined", "unrefined", "unsigned", "unwind", "well-defined", "womankind", "word-blind" ] } }

Frequency

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.

 

curl https://wordsapiv1.p.mashape.com/words/apartment/frequency { "word" : "apartment", "frequency": { "zipf": 4.82, "perMillion": 65.76, "diversity": 0.17 } } curl https://wordsapiv1.p.mashape.com/words/you/frequency { "word" : "you", "frequency": { "zipf": 7.61, "perMillion": 40395.27, "diversity": 1 } }

Search

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.

 

curl https://wordsapiv1.p.mashape.com/words?letterPattern=^a.{4}$ { "query": { "letterPattern": "^a.{4}$", "limit": 100, "page": 1 }, "results": { "total": 805, "data": [ "aalst", "aalto", "aarau", "aaron", "abaca", "abaci", "aback", "abaco", ... "addax", "adder" ] } } curl https://wordsapiv1.p.mashape.com/words?letterPattern=^a.{4}$&page=2 { "query": { "letterPattern": "^.{5}$", "page": 2, "limit": 100 }, "results": { "total": 10495, "data": [ "abram", "abris", "abuja", "abuna", "abura", "abury", "abuse", "abuzz", "abyla", "abysm", ... "aegir", "aegis", "aegle" ] } } curl https://wordsapiv1.p.mashape.com/words?pronunciationPattern=.*æm$letterPattern=.*chm$&lettersMax=7 { "query": { "letterPattern": ".*chm$", "pronunciationPattern": ".*\u00e6m$", "limit": 100, "page": 1 }, "results": { "total": 1, "data": [ "drachm" ] } } curl https://wordsapiv1.p.mashape.com/words/?hasDetails=hasUsages,hasCategories { "query": { "hasDetails": "hasUsages,hasCategories", "limit": 100, "page": 1 }, "results": { "total": 7, "data": [ "humor", "humour", "trademark", "wit", "witticism", "wittiness", "yiddish" ] } }

Random Word

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.

 

curl https://wordsapiv1.p.mashape.com/words/?random=true { "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" } } curl https://wordsapiv1.p.mashape.com/words/?letterPattern=^[a-zA-Z]*$&random=true { "word": "arcanum", "frequency": 2.02, "results": [ { "definition": "information known only to a special group", "partOfSpeech": "noun", "synonyms": [ "secret" ], "typeOf": [ "information", "info" ], "hasTypes": [ "cabbalah", "countersign", "esoterica", "kabala", "kabbala", "kabbalah", "parole", "password", "qabala", "qabalah", "watchword", "cabala", "word", "cabbala" ] } ], "syllables": { "count": 3, "list": [ "ar", "ca", "num" ] }, "pronunciation": { "all": "ɑr'keɪnəm" } }

Libraries

To help you integrate with Words API, the following libraries are available.