Wordnik Documentation

Methods

tonytam — Thu, 04 Nov 2010 17:33:07 +0000

Last updated September 7, 2010

API Overview

Wordnik supports a REST API with XML or JSON-formatted responses.

The general form for requests is:

http://api.wordnik.com/api/{RESOURCE}.{FORMAT}/{PARAMETERS}

Replace {RESOURCE}, {FORMAT}, and {PARAMETERS} for your specific use case. For example, this url will return the definitions for the word “cat,” in JSON format:

http://api.wordnik.com/api/word.json/cat/definitions?api_key={YOUR_API_KEY}

Response format
Currently, we offer XML and JSON as response formats. In all request urls, simply replace {FORMAT} with either “xml” or “json”.

API Key
All requests must be signed with your Wordnik API key, either as a url parameter, or as a header. Don’t have an API key? Get yours here.

API example code and client libraries
Currently, we provide example code and client libraries for Java, Python, Ruby, PHP, and Javascript. You can find it on Github, here.

All currently-available resources and methods are detailed below. Happy hacking!

Word lookup with spelling suggestions

Fetch the word you requested, along with its canonical Wordnik ID, assuming it is found in our corpus. You can pass additional parameters to retrieve spelling suggestions. (This can power “Did you mean …?” functionality.)

Method: GET
Header: api_key={your key}
URL: http://api.wordnik.com/api/word.{FORMAT}/{WORD}
Requires auth_token? NO

Parameters:
Enable the suggester, which will return an array of suggestions, if available:

useSuggest=true

If the suggester is enabled (with useSuggest=true), simply return the best match:

literal=false

If, for example, the client looks up “Zeebra” with useSuggest=true and literal=false, the word “zebra” is automatically returned with no other suggestions.

Examples:

XML example:

http://api.wordnik.com/api/word.xml/cat


   27568
   cat

JSON example:

http://api.wordnik.com/api/word.json/cat

{
    "id": 27568,
    "wordstring": "cat"
}

With “useSuggest=true”:

XML example:

http://api.wordnik.com/api/word.xml/Zeebra?useSuggest=true


   5008170
   Zeebra
   
      zebra

JSON example:

http://api.wordnik.com/api/word.json/Zeebra?useSuggest=true

{
    "id": 5008170,
    "suggestions": [
        "zebra"
    ],
    "wordstring": "Zeebra"
}

With “useSuggest=true” and “literal=false”:

XML example:

http://api.wordnik.com/api/word.xml/Zeebra?useSuggest=true&literal=false


  87264
  zebra

JSON example:

http://api.wordnik.com/api/word.json/Zeebra?useSuggest=true&literal=false

{
    "id": 87264,
    "wordstring": "zebra"
}

Bi-gram phrases

Fetch interesting bi-gram phrases containing your word.

Method: GET
Header: api_key={your key}
URL: http://api.wordnik.com/api/word.{FORMAT}/{WORD}/phrases
Requires auth_token? NO

Parameters:
Limit the number of results returned:

limit={NUMBER_OF_RESULTS}
count={NUMBER_OF_RESULTS} (deprecated)

Examples:

XML example:

http://api.wordnik.com/api/word.xml/Christmas/phrases


  
    353
    12.414364902158674
     20.877889275429855
    Christmas
    Eve
  
  
    268
    10.707678907779517
    18.77376809823729
    Christmas
    tree
  
  ...

JSON example:

http://api.wordnik.com/api/word.json/Christmas/phrases

[
    {
        "gram1": "Christmas",
        "gram2": "Eve",
        "mi": 12.414364902158674,
        "wlmi": 20.877889275429855
    },
    {
        "gram1": "Christmas",
        "gram2": "tree",
        "mi": 10.707678907779517,
        "wlmi": 18.773768098237291
    },
    ...

Word definitions

Fetch a word's definitions from the Century Dictionary, Webster GCIDE, and Wordnet dictionaries. Refer to the Dictionary Model schema (XSD) here on Github.com.

Method: GET
Header: api_key={your key}
URL: http://api.wordnik.com/api/word.{FORMAT}/{WORD}/definitions
Requires auth_token? NO

Parameters:
You can specify the number of results returned.

limit={NUMBER_OF_RESULTS}

You can let the API select the canonical form of the word.

useCanonical={true|false}

You can scope the request to one of the supported source dictionaries

sourceDictionary={SOURCE_DICTIONARY}

The available source dictionaries are:

ahd
century
wiktionary
webster
wordnet

You can also specify one or many part-of-speech types to return definitions for:

partOfSpeech=noun,adj,adverb,...

The available partOfSpeech values are:

noun
verb
adjective
adverb
idiom
article
abbreviation
preposition
prefix
interjection
suffix
conjunction
adjective-and-adverb
noun-and-adjective
noun-and-verb-transitive
noun-and-verb
past-participle
imperative
noun-plural
proper-noun-plural
verb-intransitive
proper-noun
adjective-and-noun
imperative-and-past-participle
pronoun
verb-transitive
noun-and-verb-intransitive
adverb-and-preposition
proper-noun-posessive
noun-posessive

XML example:

http://api.wordnik.com/api/word.xml/cat/definitions


  
    
      
        Laying aside their often rancorous debate...
        Mark Derr (N. Y. Times, Nov. 2, 1999...
      
    
    Any animal belonging to the natural family...
    cat
    
      
        (Zoöl.)
      
    
    
      
        ☞ The domestic cat includes many...
      
    
    noun
    1.
  
  
    cat
    
      
        (Naut.)
      
    
    noun
    2.
  
  ...

JSON example:

http://api.wordnik.com/api/word.json/cat/definitions

[
    {
        "headword": "cat",
        "id": 3117132,
        "partOfSpeech": "noun",
        "seqString": "6.",
        "sequence": "9",
        "text": "A catamaran."
    },
    {
        "citations": [
            {
                "source": "Totten."
            }
        ],
        "exampleUses": [
            {
                "text": "to cat an anchor"
            }
        ],
        "headword": "cat",
        "id": 3117145,
        "labels": [
            {
                "text": "(Naut.)",
                "type": "fld"
            }
        ],
        "partOfSpeech": "verb-transitive",
        "sequence": "0",
        "text": "To bring to the cathead. See anchor."
    },
    ...
]

Example sentences

You can retrieve five example sentences for a word in Wordnik’s corpus. Each example contains the source document and a source URL, if it exists.

Method: GET
Header: api_key={your key}
URL: http://api.wordnik.com/api/word.{FORMAT}/{WORD}/examples
Requires auth_token? NO

Parameters:
You can let the API select the canonical form of the word.

useCanonical={true|false}

XML example:

http://api.wordnik.com/api/word.xml/cat/examples


  
    That mountain cat is a very confused ...
    22330027
    281222695
    3305513809
    
      711
      wordnik
    
    755.66016
    Timegod's World
    1992
  
  
    When a person who has worked hard and scored ...
    14411375
    96214469
    3379638015
    
      712
      spinner
    
    749.0
    http://www.pagalguy.com/forum/...
    2009
  
  ...

JSON example:

http://api.wordnik.com/api/word.json/cat/examples

[
    {
        "display": "That mountain cat is a very confused ...",
        "documentId": 22330027,
        "exampleId": 281222695,
        "provider": {
            "id": 711,
            "name": "wordnik"
        },
        "rating": 755.66016000000002,
        "scoreId": 3305513809,
        "title": "Timegod's World",
        "year": 1992
    },
    {
        "display": "When a person who has worked hard  ...",
        "documentId": 14411375,
        "exampleId": 96214469,
        "provider": {
            "id": 712,
            "name": "spinner"
        },
        "rating": 749.0,
        "scoreId": 3379638015,
        "url": "http://www.pagalguy.com/forum/...",
        "year": 2009
    },
    ...
]

Related Words

Retrieve related words for a particular word.

Method: GET
Header: api_key={your key}
URL: http://api.wordnik.com/api/word.{FORMAT}/{WORD}/related
Requires auth_token? NO

Parameters:
Limit the number of results:

limit={NUMBER_OF_RESULTS}  default: 1000

You can let the API select the canonical form of the word.

useCanonical={true|false}

You can specify the part of speech to fetch related items for:

partOfSpeech={PART_OF_SPEECH} default: all

You can specify which relationship type(s) to return:

type={RELATIONSHIP_TYPE} default: all

You can scope the request to a single dictionary:

sourceDictionary={SOURCE_DICTIONARY}

Note: This parameter can accept multiple types. Comma-separate the values, e.g.:

type=synonym,antonym,same-context

The available relationship types are:

synonym: words with very similar meanings (beautiful: pretty)
antonym: words with opposite meanings (beautiful: ugly)
form: words with the same stem (dog: dogs, dogged, doggish)
hyponym: a word that is more specific (‘chair’ is a hyponym of ‘furniture’)
variant: a different spelling for the same word: color and colour are
variants
verb-stem: Pass in a verb like “running” and get the stem, which is
“run.”
verb-form: Pass in “run” and find different verb forms, like
“running”, “ran”, and “runs.”
cross-reference: a related word; (bobcat: lynx)
same-context: Shows relationships between words which are often used
in the same manner. For instance “cheeseburger” and “pizza” are often
used the same way. Both also taste great.

XML example:

http://api.wordnik.com/api/word.xml/abate/related


  
    
      to abate in lands
    
  
  
    
      abated
      abating
    
  
  
    
      depress
      deduct
      blunt
      lessen
      decrease
      ...
    
  
  
    
      abates
      abated
      abating
    
  
  
    
      abating process
      abated arms
    
  
  
    
      preserver
      increase
      intensify
      build

JSON example:

http://api.wordnik.com/api/word.json/abate/related?count=100

[
    {
        "relType": "equivalent",
        "wordstrings": [
            "to abate in lands"
        ]
    },
    {
        "relType": "form",
        "wordstrings": [
            "abated",
            "abating"
        ]
    },
    {
        "relType": "synonym",
        "wordstrings": [
            "depress",
            "intermit",
            "lower",
            "relax",
            "abolish",
            "decrease",
            ...
        ]
    },
    {
        "relType": "verb-form",
        "wordstrings": [
            "abates",
            "abated",
            "abating"
        ]
    },
    {
        "relType": "cross-reference",
        "wordstrings": [
            "abating process",
            "abated arms"
        ]
    },
    {
        "relType": "antonym",
        "wordstrings": [
            "preserver",
            "increase",
            "intensify",
            "build"
        ]
    }
]

Word frequency data

You can see how often particular words occur in Wordnik corpus, ordered by year.

Method: GET
Header: api_key={your key}
URL: http://api.wordnik.com/api/word.{FORMAT}/{WORD}/frequency
Requires auth_token?  NO

You can let the API select the canonical form of the word.

useCanonical={true|false}

XML example:

http://api.wordnik.com/api/word.xml/cat/frequency


  
    21523
    2008
  
  
    41828
    2009
    ...
  -1:11966,1344:9,1485:14,1503:4, ...
  112461
  11966
  27568

JSON example:

http://api.wordnik.com/api/word.json/cat/frequency

{
    "frequency": [
        {
            "count": 21523,
            "year": 2008
        },
        {
            "count": 41828,
            "year": 2009
        },
        ...
    ],
    "frequencyString": "-1:11966,1344:9,1485:14,1503:4, ...",
    "totalCount": 112461,
    "unknownYearCount": 11966,
    "wordId": 27568
}

Word punctuation factor

You can see how common particular words occur with punctuation (period, question mark, exclamation point).

Method: GET
Header: api_key={your key}
URL: http://api.wordnik.com/api/word.{FORMAT}/{WORD}/punctuationFactor
Requires auth_token?  NO

You can let the API select the canonical form of the word.

useCanonical={true|false}

XML example:

http://api.wordnik.com/api/word.xml/cat/punctuationFactor

JSON example:

http://api.wordnik.com/api/word.json/cat/punctuationFactor

{
    "exclamationPointCount": 1787,
    "periodCount": 27245,
    "questionMarkCount": 1365,
    "totalCount": 112461,
    "wordId": 27568
}

Word autocomplete

The autocomplete service takes a word fragment — that is, a few letters — and returns words which start with that fragment. The results are based on corpus frequency, not static word lists, so you have access to more dynamic words in the language.

You can pass a “*” as a single-character wild-card in the request, so “t*e” would match “the”. The single-character wildcard will not substitute a null character in its place, so “the*” will first match “they” not “the”. You can pass multiple wildcards in a request.

Method: GET
Header: api_key={your key}
URL: http://api.wordnik.com/api/suggest.{FORMAT}/{FRAGMENT}
Requires auth_token?  NO

Parameters:
Specify the number of results returned:

limit={NUMBER_OF_RESULTS}
count={NUMBER_OF_RESULTS} (deprecated)

You can also specify the starting index for the results returned. This allows you to paginate through the matching values.

skip={STARTING_OFFSET}
startAt={STARTING_OFFSET} (deprecated)

You can specify to sort data by wordstring ascending (default is “sortBy=frequency”, descending)

sortBy=alpha

You can request that only words with dictionary definitions be returned:

hasDictionaryDef=true

XML example:

http://api.wordnik.com/api/suggest.xml/ca

JSON example:

http://api.wordnik.com/api/suggest.json/ca

{
    "match": [
        {
            "count": 0,
            "wordstring": "ca"
        },
        {
            "count": 11865734,
            "wordstring": "can"
        },
        {
            "count": 2595536,
            "wordstring": "came"
        },
        {
            "count": 2595536,
            "wordstring": "called"
        },
        {
            "count": 2188235,
            "wordstring": "case"
        },
        ...
    ],
    "matches": 11466,
    "more": 11451,
    "searchTerm": {
        "count": 252734,
        "wordstring": "ca"
    }
}

Word Search

You can search for words with a number of parameters including a GLOB-type word pattern syntax. In all parameters below, the default value is “unconstrained”.

Method: GET
Header: api_key={your key}
URL: http://api.wordnik.com/api/words.{FORMAT}/search
Requires auth_token?  NO

Parameters:

The GLOB word pattern to use as a filter (@=>one vowel, #=>one consonant, ?=>one character wildcard, *=>zero-to-many wildcard):

query={GLOB_PATTERN}

You can include or exclude words with specific parts of speech (see the definitions api for the full list):

includePartOfSpeech={CSV_PART_OF_SPEECH to include}
excludePartOfSpeech={CSV_PART_OF_SPEECH to exclude}

You can filter words which match a specific corpus frequency in Wordnik’s corpus:

minCorpusCount={MINIMUM_FREQUENCY}
maxCorpusCount={MAXIMUM_CORPUS_FREQUENCY}

You can use the number of dictionary definitions as a proxy for common & ambiguous words:

minDictionaryCount={MINIMUM_NUMBER_OF_DEFINITIONS}
maxDictionaryCount={MAXIMUM_NUMBER_OF_DEFINITIONS}

You can constrain the length of words being returned:

minLength={MIN_WORD_LENGTH}
maxLength={MAX_WORD_LENGTH}

You can paginate through the results:

skip={RECORDS_TO_SKIP}
limit={NUMBER_OF_RESULTS (default is 10)}

Example: Find words starting in “c” and having two consecutive vowels, ending in “p” with length between 4 and 7 characters.

XML response:

http://api.wordnik.com/api/words.xml/search?query=c@@*p&minLength=4&maxLength=7

JSON response:

http://api.wordnik.com/api/words.json/search?query=c@@*p&minLength=4&maxLength=7

[
    {
        count: 85240
        wordstring: "coup"
    }
    {
        count: 6802
        wordstring: "coop"
    }
    ...
]

Word-of-the-Day

Fetch Wordnik’s Word-of-the-Day, including definitions and example sentences.

Method: GET
Header: api_key={your key}
URL: http://api.wordnik.com/api/wordoftheday.{FORMAT}
Requires auth_token?  NO

XML example:

http://api.wordnik.com/api/wordoftheday.xml


  
    (noun) A bar of steel attached by one end to ...
  
  
    (noun) Any piece of wood or metal wedged ...
  
  
    (noun) A young salmon.
  
  
    (noun) A prop used to support coal in a mine.
  
  
    (verb) To stop a vehicle with a sprag.
    
    But I'll put a sprag in your wheel afore you gang far.
    
    For all that, it's a sheer impossibility that ...
  
  
    The 'Silesian' method includes a "soldier sprag"  ...
  
  
    A new worker's attempts to "sprag," or stop the ...
  
  A sprag is sometimes also called a 'dart' or a 'dagger'.
  sprag

JSON example:

http://api.wordnik.com/api/wordoftheday.json

{
    "definition": [
        {
            "text": "(noun) A bar of steel attached by one end ..."
        },
        {
            "text": "(noun) Any piece of wood or metal wedged ..."
        },
        {
            "text": "(noun) A young salmon."
        },
        {
            "text": "(noun) A prop used to support coal in a mine."
        },
        {
            "text": "(verb) To stop a vehicle with a sprag."
        }
    ],
    "example": [
        {
            "text": "But I'll put a sprag in your wheel afore you gang far."
        },
        {
            "text": "For all that, it's a sheer impossibility that  ..."
        },
        {
            "text": "The 'Silesian' method includes a \"soldier  ..."
        },
        {
            "text": "A new worker's attempts to \"sprag,\" or stop  ..."
        }
    ],
    "id": 204,
    "note": "A sprag is sometimes also called a 'dart' or a 'dagger'.",
    "publishDate": "2010-05-19T02:00:00.000+0000",
    "wordstring": "sprag"
}

Random Word

Fetch a random word from the Wordnik corpus.

Method: GET
Header: api_key={your key}
URL: http://api.wordnik.com/api/words.{format}/randomWord
Requires auth_token?  NO

Parameters:
Only return words where there is a definition available:

hasDictionaryDef=true

XML example:

http://api.wordnik.com/api/words.xml/randomWord


  17968399
  dragonarmies

JSON example:

{
    "id": 351810,
    "wordstring": "visitors"
}

Random Words

Fetch multiple random words from the Wordnik corpus. You can apply similar constraints to the Word Search to filter the results. The old “hasDictionaryDef” will be removed in the v4 API–it’s equivalent to passing “minDictionaryCount=1″.

Method: GET
Header: api_key={your key}
URL: http://api.wordnik.com/api/words.{format}/randomWords
Requires auth_token?  NO

Parameters:
You can include or exclude words with specific parts of speech (see the definitions api for the full list):

includePartOfSpeech={CSV_PART_OF_SPEECH to include}
excludePartOfSpeech={CSV_PART_OF_SPEECH to exclude}

You can filter words which match a specific corpus frequency in Wordnik’s corpus:

minCorpusCount={MINIMUM_FREQUENCY}
maxCorpusCount={MAXIMUM_CORPUS_FREQUENCY}

You can use the number of dictionary definitions as a proxy for common & ambiguous words:

minDictionaryCount={MINIMUM_NUMBER_OF_DEFINITIONS}
maxDictionaryCount={MAXIMUM_NUMBER_OF_DEFINITIONS}

You can constrain the length of words being returned:

minLength={MIN_WORD_LENGTH}
maxLength={MAX_WORD_LENGTH}

You can paginate through the results:

skip={RECORDS_TO_SKIP}
limit={NUMBER_OF_RESULTS (default is 5)}

http://api.wordnik.com/api/words.json/randomWords?minLength=4&maxLength=7

XML response:


  
    92367
    resist
  
  
    1355748
    no-fly
  
  ...

JSON example:

[
  {
    id: 303792
    wordstring: "noetic"
  }
  {
    id: 207183
    wordstring: "squid"
  }
  ...
]

Text Pronunciations

Fetch a word’s text pronunciation from the Wornik corpus, in arpabet and/or gcide-diacritical format.

Method: GET
Header: api_key={your key}
URL: http://api.wordnik.com/api/word.{FORMAT}/{WORD}/pronunciations
Requires auth_token?  NO

You can let the API select the canonical form of the word.

useCanonical={true|false}

XML example:

http://api.wordnik.com/api/word.xml/computer/pronunciations


  
    0
    (kŏm*pūt"ẽr)
    gcide-diacritical
  
  
    0
    K AH0 M P Y UW1 T ER0
    arpabet

JSON example:

http://api.wordnik.com/api/word.json/computer/pronunciations

[
    {
        "id": 0,
        "raw": "(k\u014fm*p\u016bt\"\u1ebdr)",
        "rawType": "gcide-diacritical",
        "seq": 0
    },
    {
        "id": 0,
        "raw": "K AH0 M P Y UW1 T ER0",
        "rawType": "arpabet",
        "seq": 0
    }
]

Authentication

Certain methods — currently, user accounts and list-related CRUD operations — are only available to you if you pass a valid auth_token in the header of the request. This method logs you in to Wordnik via the API and returns an auth_token which you can then use to make other requests.

Method: GET
Header: api_key={your key}
URL: https://api.wordnik.com/api/account.{FORMAT}/authenticate/{USERNAME}?password={PASSWORD}
Requires auth_token?  NO

JSON example:

http://api.wordnik.com/api/account.json/authenticate/your_username?password=your_password

{"token"=>"your_auth_token", "userId"=>'your_user_id'}

API Usage

You can always check your API key usage by calling the apiTokenStatus resource. This call does not count against your API usage.

Method: GET
Header: api_key={your key}
URL: https://api.wordnik.com/api/account.{FORMAT}/apiTokenStatus
Requires auth_token?  NO

JSON example:

http://api.wordnik.com/api/account.json/apiTokenStatus

{"valid"=>true,
"token"=> "your_api_key",
"totalRequests"=>{requests_in_reset_period},
"expiresInMillis"=>9223372036854776000,
"remainingCalls"=>{calls_left_in_reset_period},
"resetsInMillis"=>{milliseconds_before_next_reset}}

Lists

Get all lists

This method will fetch all of the authenticated user’s word lists.

Method: GET
Headers: api_key={YOUR API_KEY}, auth_token={YOUR AUTH_TOKEN}
URL: https://api.wordnik.com/api/wordLists.{FORMAT}
Requires auth_token?  YES
Requires https?  YES

JSON example:

http://api.wordnik.com/api/wordLists.json

[{
  "userName"=>{YOUR_USERNAME},
  "name"=>"animals",
  "updatedAt"=>"2010-05-27T20:40:11.000+0000",
  "numberWordsInList"=>3,
  "id"=>25607,
  "userId"=>1026985,
  "type"=>"PUBLIC",
  "createdAt"=>"2010-05-27T20:40:11.000+0000",
  "description"=>"a trip to the zoo",
  "permalinkId"=>"animals--2"
}, ...]

Create a new list

This method will create a new list on behalf of the authenticated user.

Method: POST
Headers: api_key={YOUR API_KEY}, auth_token={YOUR AUTH_TOKEN}
URL: https://api.wordnik.com/api/wordLists.{FORMAT}
POST data: {name: {LIST_NAME}, description: {LIST_DESCRIPTION}, type: {'PUBLIC' or 'PRIVATE'} }
Requires auth_token?  YES
Requires https?  YES

JSON example:

http://api.wordnik.com/api/wordLists.json
(with POST data: {name: 'musical instruments', description: 'all the instruments i can think of', type: 'PUBLIC'}

{
  "userName"=>{YOUR_USERNAME},
  "name"=>"musical instruments",
  "updatedAt"=>"2010-05-27T20:58:52.821+0000",
  "numberWordsInList"=>0,
  "id"=>25608,
  "userId"=>1026985,
  "type"=>"PUBLIC",
  "createdAt"=>"2010-05-27T20:58:52.821+0000",
  "description"=>"all the instruments i can think of",
  "permalinkId"=>"musical-instruments--1"
}

Add a word to a list

This method will add a word to the given list, on behalf of the authenticated user.

Method: POST
Headers: api_key={YOUR API_KEY}, auth_token={YOUR AUTH_TOKEN}
URL: https://api.wordnik.com/api/wordList.{FORMAT}/{LIST.permalinkId}/words
POST data: [{'wordstring': {WORD}}]
Requires auth_token?  YES
Requires https?  YES

JSON example:

URL: https://api.wordnik.com/api/wordList.json/musical-instruments--1/words
with POST data: [{'wordstring': 'kazoo'}]

[{
  "userName"=>"altay",
  "numberLists"=>15,
  "numberCommentsOnWord"=>5,
  "userId"=>1026985,
  "createdAt"=>"2010-05-27T21:04:33.000+0000",
  "wordstring"=>"kazoo"
}]

Retrieve the words from a list

This method will return all the words from the given list.

Method: GET
Headers: api_key={YOUR API_KEY}, auth_token={YOUR AUTH_TOKEN}
URL: https://api.wordnik.com/api/wordList.{FORMAT}/{LIST.permalinkId}/words
Requires auth_token?  YES
Requires https?  YES

JSON example:

URL: https://api.wordnik.com/api/wordList.json/musical-instruments--1/words

[{
  "userName"=>"altay",
  "numberLists"=>15,
  "numberCommentsOnWord"=>5,
  "userId"=>1026985,
  "createdAt"=>"2010-05-27T21:04:33.000+0000",
  "wordstring"=>"kazoo"
}]

Delete a word from a list

This method will delete the given word from the given list.

Method: DELETE
Headers: api_key={YOUR API_KEY}, auth_token={YOUR AUTH_TOKEN}
URL: https://api.wordnik.com/api/wordList.{FORMAT}/{LIST.permalinkId}/deleteWords
DELETE body: [{'wordstring': '{WORD}'}]
Requires auth_token?  YES
Requires https?  YES

JSON example:

URL: https://api.wordnik.com/api/wordList.json/musical-instruments--1/deleteWords

nil

Delete a list

This method will delete the given list.

Method: DELETE
Headers: api_key={YOUR API_KEY}, auth_token={YOUR AUTH_TOKEN}
URL: https://api.wordnik.com/api/wordList.{FORMAT}/{LIST.permalinkId}
Requires auth_token?  YES
Requires https?  YES

JSON example:

URL: https://api.wordnik.com/api/wordList.json/musical-instruments--1

nil

Access Messages

Invalid API key
If you attempt to call any API methods with invalid or an incorrect API key you will see a message like below:


   unauthorized
   error

Rate limiting
If you have exceeded a limit assigned to your key, you will see this:


   exceeded access limits
   error

Invalid resource:
If you request a resource that doesn’t exist, you will see the following:


   invalid resource
   error

Too busy:
And finally, if the server is really busy it is possible to see this:


   too busy
   unable to {do what you asked}

Batch Requests

You can reduce your network calls by using our batch request mechanism. Batching is restricted to a single resource with the GET method but allows for variable query params and HTTP response codes. All calls in a request will be counted against the API access limiter.

A batch request is created by passing the “multi” query param and specifying resources and params with a positional suffix. Each batch item must designate a single resource, query params are optional.

For example, to fetch multiple resources for the word “Dog”, you can construct a request URI as follows:

// call the definitions resource
resource.1=definitions
// restrict to 2 definitions
limit.1=2
// use the canonical form of the word
useCanonical.1=true
// call the examples resource
resource.2=examples
// get just one example
limit.2=1
// use the canonical form of the word
useCanonical.2=true
// get related items
resource.3=related
// fetch synonyms
type.3=synonym
// fetch 5 synonyms
limit.3=5

This is constructed into the following (sort of long) query string:

http://api.wordnik.com/api/word.json/Cat?multi&resource.1=definitions&useCanonical.1&limit.1=2&resource.2=examples&limit.2=1&useCanonical.2=true&resource.3=related&type.3=synonym&limit.3=5&useCanonical.3=true

and gives a response as such:

{
   responseItems: [
   {
      responseName: "definitions"
      responsePosition: 1
      responseContent: [
      {
         id: 3117123
         text: "Any animal belonging to the..."
         …
      }
      {...}
   }
   {
      responseName: "examples"
      responsePosition: 2
      responseContent: [ {
         scoreId: 3305513809
         year: 1992
         provider: {
            name: "wordnik"
            id: 711
         }
         display: "That mountain cat is a..."
         wordstring: "cat"
         title: "Timegod's World"
         rating: 755.66016
         exampleId: 281222695
         documentId: 22330027
     } ]
   }
   {
      responseName: "related"
      responsePosition: 3
      responseContent: [ {
         wordstrings: [
            "Angora"
            "chap"
            "qualifier"
            "kitling"
            "Maltese"
         ]
         relType: "synonym"
     } ]
   }
] }

If you attempt to access an invalid resource or experience other non-200 HTTP responses, you will see a response message in the batch response:

   ...
   responseName: "nadanada"
   responsePosition: 3
   responseContent: {
      message: "invalid resource"
      type: "error"
   }
}

API-v.3.3 Changelog

tonytam — Thu, 04 Nov 2010 16:20:07 +0000

The changes between version 3.2 and version 3.3 of the Wordnik API are listed here.

Functionality Updates

We’ve released two new methods for finding interesting words, both of which are highly flexible and unique.

Word Search You can now search for words which match a certain criteria. Looking for a word starting with an “a”, containing two consecutive vowels, ending in a “p” with a length between 6 and 10 characters? How about ensuring it’s “common”? Or maybe ensuring that it’s rare? A noun but not a verb? We’ve got the API for you, check out our methods page for the word search api.

Random Words This functionality has been enhanced in the Wordnik API-you now have total control over what you get back. You can ask similar questions as with the Word Search but eliminate the word pattern and get up to 100 results back. Perfect for your word games.

API

tonytam — Wed, 03 Nov 2010 17:30:36 +0000

Wordnik API Version 3.3 is available

Wordnik is pleased to announce version 3.3 of our public API. Two new APIs have been released to help word game developers find weird and wonderful words with a great degree of control.

Take a look at the V3.3 Changelog and Methods pages for all the details. These new APIs are live and available now.

How Do I Get Access?

Our API is available now. You’ll first need to be approved and be assigned an access key. Please visit http://api.wordnik.com/signup to get one. As you’ll see on the signup site, we’re accepting applications based on manual review.

Once approved, you can access the API by passing your API token in your requests to our servers. For example:

curl -H "api_key:{token}" http://api.wordnik.com/api/word.json/cat/definitions

Replace {token} with a valid API token, of course.

Is This Service Really in Alpha?

Yes. Like all good things on the Internet, the API is under constant development. Some day we’ll graduate from alpha and call it beta. Follow @wordnikapi on Twitter for announcements on the service. We’ll be adding features to the API weekly, and exposing more nuggets from our full corpus. Of course you can also contact us the old-fashioned way, at apiteam@wordnik.com, with service-related issues, etc.

Wordnik wants your suggestions on making the API better. Please don’t hesitate to ask. No reasonable requests will be ignored.

What Kind of Data is Available?

You can get immediate access to the following information through our API:

Definitions from the The Century Dictionary
Frequency data reflecting occurrences in our alpha API corpus
Example sentences for words
An autocomplete service
Access to our Word of the Day

This list will grow weekly so please follow the Twitter updates and watch for emails to the email address we have for your Wordnik account.

More Important Info

The service is RESTful so the resources and operations should be easy to understand. We adhere to the following principles:

You need to specify the requested format of data in the URL.
Your key should be passed in the HTTP headers. In GET operations you can pass your key in the request parameters, but this is not the preferred method.
You will receive a 2xx HTTP response code if your request was successful. You can always attempt to parse the response message in this scenario.
If you want something that doesn’t exist, you’ll get a 404 response.
If you request a list of objects and that list is empty, you’ll receive an empty array with a 2xx status code.
If you receive a non-2xx or non-3xx response code, you should always receive an error message wrapped in an ApiResponse:

in JSON format:

{
 message: "word not found"
 type: "error"
}

in XML:


  word not found
  error

You can get data in either XML or JSON format. If you’re interested in our API then you probably know which format you’d prefer. The same data is served up for both formats.

Methods

Please see the Methods page for specific methods of making API requests.

Where to Go Next

The best place to start is to check out our sample code on our public GitHub repository:

git://github.com/wordnik/api-examples.git

Note that for any access to the API you’ll first need an approved API key!

Terms of Service

Please take a minute to read our brief Terms of Service before using the API.

API-v.3.2 Changelog

tonytam — Wed, 08 Sep 2010 04:11:29 +0000

The changes between version 3.1 and version 3.2 of the Wordnik API are listed here.

Functionality Updates

We have deployed a mechanism for letting the API automatically select the canonical form of the word you are interested in. Note there is not always a canonical form (bill and Bill are examples).

Wordnik’s API is case sensitive–we feel that there IS a difference between bill and Bill, turkey and Turkey, etc. This mechanism is one step in the direction of helping facilitate detecting the most likely case variation of a word.

Many of our API consumers are on mobile devices and limiting network calls is vital to both application and device performance. You can now batch requests into single API calls to speed up your client.

Please see the methods page for details.

Versioning

tonytam — Fri, 16 Apr 2010 09:35:15 +0000

An API signature should represent a contract between a client the provider–versioning those signatures can certainly be troublesome if the data you’re depending on changes often. At the same time often bugs arise and are killed which might require a change in either a resource path or its response data. To keep things moving as smoothly as possible, Wordnik is adopting the following versioning policy.

Whenever a new API version is released, Wordnik will attempt to maintain the previous version for at least four weeks.
The base URL /api/ will always point to the most current API version
Specific API versions will be addressable via path (/api-v3)

And finally, of course, we selfishly want people all on the same, most current version of the API. So new features will typically not be back ported to older versions.

Most Current API (Version 3):

http://api.wordnik.com/api/

Version 3 API (2010-3 release):

http://api.wordnik.com/api-v3/

Version 2 API (2009-12 release):

http://api.wordnik.com/api-v2/

API-v.3.1 Changelog

tonytam — Wed, 31 Mar 2010 17:30:26 +0000

The changes between version 3 and version 3.1 of the Wordnik API are listed here.

Functionality Updates

We have rolled out our first version of a did-you-mean suggester which helps select the proper case of a word and common misspellings. This is invoked with the existing word resource but with additional parameters. Please see the methods page for details.

You can now access interesting phrases for words with the newly released phrase API.

JSON calls can now pad responses for client-side execution (JSONP) by simply adding a callback parameter in the request:


http://api.wordnik.com/api/word.json/dog/examples?callback=doSomething

which will pad the response as:

doSomething({...})

Keep in mind that browser-side invocation of the API puts your API key out in the open.

Model Updates

There are new fields in the Example object to return the source of the example. You can get details from the XSD in Github.

Dictionary Model XSD

tonytam — Thu, 04 Mar 2010 06:52:57 +0000

You can get a downloadable version of this in GitHub

API-v.3 Changelog

tonytam — Thu, 04 Mar 2010 06:50:58 +0000

The changes between version 2 and version 3 of the Wordnik API are listed here.

API Version Update

Per our Versioning documentation, the most recent Wordnik API will be accessible via http://api.wordnik.com/api/{resource}.

General Changes

JSON format:

Hopefully this is the last major revision to our JSON support. We’ve switched to the Jackson JSON processor which conforms cleanly to the JSON spec, making the numerous client libraries much happier in the end. This means however that there some changes to the data format.

Values which are non-strings are again not quoted
Timestamps now follow the ISO-8601 format (yyyy-MM-dd’T'HH:mm:ss.SSSZ)
Requests with zero-length array results were getting an incorrect “null” string. This has been replaced with the appropriate empty array.
Arrays are no longer “named” by hashcode.

Model Updates

The Dictionary Model has been revamped. You can review the model XSD here: Dictionary Model XSD.

New Apis

Please see the Methods page for details on each of the new APIs below.

Added method to get definitions by part of speech
Added method to return related words (synonyms, antonyms, run-ons, etc)
Added dictionary examples

Terms of Service

tonytam — Mon, 21 Dec 2009 21:34:09 +0000

Our API is provided to you, the consumer, at no cost, providing you follow a few simple and straightforward rules.

Access
Access to our API is provided for you and only for you. Your applications can consume our data but you cannot provide direct access to our API to others either via sharing access keys, proxying requests for others, reproduction of data, etc. In addition, direct access to our API should not be provided to your end users.

If we suspect that your key has been shared, you will be notified and it will be changed. If it happens too frequently your access may be revoked.

Rate Limiting
In order to provide service to many users, we may restrict the total number of calls available to you, and/or the rate at which you make them. If we see you making too many requests we’ll attempt to contact you before changing your limits. If you need more access than you’re getting, contact us.

Local Copies of Data
You cannot make local copies of data retrieved from our API.

More Information
Questions? Comments? Suggestions? Please email us at apiteam@wordnik.com.

Signup

tonytam — Mon, 21 Dec 2009 21:33:53 +0000

Our API Signup page is momentarily off–please check back to http://api.wordnik.com/signup/ soon.