• JSONP with the Wordnik API

    Posted Jul 26, 2011

    The Wordnik API supports JSONP syntax, meaning you can specify a function in any request and the Wordnik API will pad the response in your method name. This makes it easy to pass the response of any Wordnik API call back to your javascript-based code for asynchronous execution.

    To use the JSONP feature, simply add a query param to any request:

    callback={your_function_name}

    For example:

    http://api.wordnik.com/v4/word.json/cat/definitions?limit=1&callback=alert

    Will produce the following response:

    alert(
  [
    {
      word: "cat"
      text: "A small carnivorous mammal ..."
      score: 0
      partOfSpeech: "noun"
      sourceDictionary: "ahd-legacy"
      sequence: "0"
    }
  ]
)

  • Using our Batch API syntax

    Posted May 31, 2011

    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 Cat, 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/v4/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..."
         word: "cat"
         title: "Timegod's World"
         rating: 755.66016
         exampleId: 281222695
         documentId: 22330027
     } ]
   }
   {
      responseName: "related"
      responsePosition: 3
      responseContent: [ {
         words: [
            "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"
   }
}

  • Transition Guide to the v4 Wordnik API

    Posted Mar 1, 2011

    The v3 API will be maintained and supported until June 1st, 2011. After that, all requests to api.wordnik.com/api will automatically be routed to the v4 API. After September 1st, 2011, the v3 path will be disabled.

    We will strive to maintain consistency between the v3 and v4 APIs. Bugs will be addressed in both versions when possible and new features will be added only to the v4 API. Furthermore, data in some features may stop seeing updates. Again, we will avoid this but it is inevitable that at some point, differences may arise such that we can only support the current production API.

    We're here to help with your migration. Check out our documentation page for an interactive API shell that shows raw XML and JSON responses from our API which can make troubleshooting your client much simpler. In addition there's usually someone available to help out just about any time of the day. We only use real humans for answering support questions!

    Here is a comprehensive list of changes between v3 and v4 of the Wordnik API.

    Word Resource

    The word resource has both request parameter and response changes which help make the API interactions more standard.

    /word.{format}/{word}

    Request Differences

    • useLiteral has been removed and replaced with useCanonical. The features are roughly the opposite of each other--if you passed literal=true, you should pass useCanonical=false
    • useSuggest has been renamed includeSuggestions

    Response Differences

    • The response object is now called wordObject
    • The id field has been removed
    • The word itself has been renamed to word from wordstring

    /word.{format}/{word}/examples

    Request Changes

    • showDuplicates has been renamed includeDuplicates
    • source has been renamed contentProvider

    Response changes

    • the wordstring attribute in each example has been renamed word
    • display has been renamed text
    • scoreId has been removed

    /word.{format}/{word}/definitions

    Request changes

    • showRelated has been renamed includeRelated
    • tags has been renamed includeTags

    Response changes

    • headword has been renamed word
    • The definitions object no longer contain the id attribute

    /word.{format}/{word}/frequency

    Request changes

    • startAt has been renamed startYear
    • endAt has been renamed endYear

    Response changes

    • wordId is no longer returned
    • The input word is now returned

    /word.{format}/{word}/related

    Request changes

    • none

    Response changes

    • the wordstrings response array has been renamed words
    • relType has been renamed relationshipType

    /word.{format}/{word}/pronunciations

    Request changes

    • type has been renamed typeFormat

    Response changes

    • none

    Words Resource

    /words.{format}/randomWord

    Request changes

    • length has been removed. You can now set minLength and maxLength
    • There are a number of new parameters available in this API, please see the docs for a full list.

    Response changes

    • The wordstring in the response has been renamed word

    /words.{format}/randomWords

    Request changes

    • None

    Response changes

    • The wordstring in the response has been renamed word

    WordLists Resource

    /wordList.{format}/{wordListId}/words

    Request changes

    • The format of data used in the POST (add words) methods has changed. wordstring has been replaced with word:

    JSON:

    [{"word":"cat"},{"word":"dog"}]

    XML:

    <words>
 <word>cat</word>
 <word>dog</word>
</words>

    /wordList.{format}/{wordListId}/deleteWords

    Request changes

    • As above, the method body attribute names have been changed from wordstring to word

    Suggest Resource

    We implemented the suggest resource to function as an autocomplete for word lookups. This has worked well but we have had a number of requests for more features, including selecting parts of speech, different ways to sort, wildcards, etc. To accommodate these requests, plus to add other functionality, this resource has been deprecated in favor of a word search API.

    Old resource:

    /suggest.{format}/{wordFragment}

    New resource:

    /words.{format}/search/{wordFragment}

    Behavioral changes

    • The word search method is now case sensitive. You can toggle this mode by passing caseSensitive=false in the request

    Request changes

    • The wordFragment supports wildcards using an extended glob syntax. You can use @ as a single-character vowel wildcard, and # as a single-character consonant wildcard.
    • A number of filters can be applied to the input; see the docs for a full list.

    Response changes

    • matches has been renamed to totalResults
    • more has been removed
    • searchTerm element removed. The search term is always the first element in the response array, unless passing skip > 0
    • match has been renamed searchResults

    Word of the Day

    The functionality in the wordoftheday.{format} resource has been moved to the words resource.

    Old resource:

    /wordoftheday.{format}/

    New resource:

    /words.{format}/wordOfTheDay

    Behavioral differences

    • The definitions response now contains the sourceDictionary and optionally the partOfSpeech for the definition
    • The examples response now contains both URLs and titles.
    • There is a contentProvider field, currently this is always an object identifying wordnik

  • Help Methods via API

    Posted Feb 10, 2011

    Our new developer site has a REST API interface which calls our own API. If you're not the flashy, graphics types (you know who you are), you can now introspect our API by calling the endpoints directly:

    This mechanism offers a lot of options, plus it gives us a chance to eat our own dogfood. APIs everywhere. We'll soon offer the model schemas by the same mechanism, and will post here once that's available.

    JSON/XML/HTML? Now you have your choice!

  • Audio Pronunciations are Available via API

    Posted Feb 10, 2011

    Hi everyone,

    We're happy to announce that we are now delivering audio pronunciations over our API. You can see the request info on the /docs page.

    You request audio metadata via API and receive a time-expiring download URL. Currently the audio files are limited to MP3 pronunciations from the American Heritage Dictionary. We'll be offering the excellent Macmillan audio files shortly, as well as those created by users.

    Feedback welcome!

The Log

When stuff's going on with API, we talk about it here: new features, implementation details, etc.