Announcing WordDice Public API

I recently deployed a handful transparent server-side tweak to WordDice that bring the API up-to scratch(reliability and logging wise) for being released for public use. Using the API in your programs is super simple.

API access

The API uses GET requests with URL parameters. The entry point for the API is:…

http://m1.worddice.com/publicApi.php

Response format

The WordDice API uses JSON for its responses. A typical response looks like the following(please note, the response below has been formatted to human readable JSON):

Input and output parameters

To keep the API simple, the response contains the same parameters as the input.

Field Input/Output Comment
tiles both The user tiles that generated the response. Input blank tiles are represented by a hyphen(-) and output with question marks(?). There is no limit on the number of tiles.
pattern both A optional pattern to filter and match responses against. Input wildcards are represented by a hyphen(-) and output with question marks(?).
buffer both The number of results per page when taking pages into consideration. Default value = 20.
page both The page number for the result set. Default value = 1.
totalPages output The total number of pages in the full result set.
pageWordCount output Number of results on the current page. This value will usually be the same as the buffer, however on the last page it can be less then the buffer.
resultWordCount output Total number of words in the full result set.
dictionaryName both The dictionary that is searched for matches. Default = sowpods. Other values = twl, unix.
matches output Array of ranked match objects. Words worth more points with fewer tiles are ranked higher.
match.w - The word that is matched.
match.s - The number of points that the word is worth.
match.ts - The number of points (tile score) that the player will be placing on the board.
html input Sets the Content-type HTML header to text/html text so that it displays in a web browser.

Examples

Sometimes the best way to learn is to look at examples. The following examples should give overview of how to use all the input parameters.

Parameters Description
tiles=tinsgte (html) Words that can be built with ‘TINSGTE’
tiles=tinsgte&pattern=a-p (html) Words that can be built with ‘TINSGTE’. Search for words that match ‘A?P’ as a pattern.
tiles=sasuhnt&page=3 (html) Page #3 of results for. Words that can be built with ‘SASUHNT’. (ie words ranked 41-60)
tiles=sasuhnt&page=3&buffer=12 (html) Page #3 of results for. Words that can be built with ‘SASUHNT’ with buffer size of 12. (ie words ranked 25-36)
tiles=asdf&dictionary=unix (html) Words that can be built with ‘ASDF’ when using a UNIX Dictionary (/usr/dict/words)

Leave a Reply