Datamuse

Implementation notes

When to use Datamuse

Datamuse is a word-finding query engine: give it a constraint and it returns ranked words that satisfy it. Means-like (ml), sounds-like (sl), spelled-like (sp) with wildcards, and a family of relation constraints — rel_rhy for rhymes, rel_ant for antonyms, rel_trg for topically triggered words, rel_jja and rel_jjb for noun-adjective pairs — cover most of what you would otherwise build a thesaurus and a phonetic index to achieve. No key, no signup, 100,000 requests a day, and latency low enough to hang off a keystroke. Use it for autocomplete and suggestion UIs, crossword and word-game helpers, songwriting and poetry tools, and search query expansion. It is not a dictionary: there are no definitions unless you request metadata flags, and no etymology or usage notes at all. It is a retrieval engine for the question of what word goes here, and it is unusually good at exactly that.

Common pitfalls

• max caps at 1000 and defaults to 100. Asking for more does not error, it silently returns 1000. There is also no offset or pagination parameter, so 1000 results is the hard ceiling for any single query — broadening the result set means varying the constraints, not paging.
• Constraints intersect, and an over-constrained query returns an empty array with HTTP 200 rather than an error. Something like ml=ocean&sp=t???&rel_rhy=motion is perfectly valid and returns nothing, with no signal about which constraint killed it. Build queries by adding one constraint at a time, and in code treat an empty result as a cue to relax a constraint rather than as a failure.
• No authentication means no per-application quota. The 100,000/day budget is per IP, so on shared hosting, behind NAT, or on a serverless platform you are pooling with other tenants and can be throttled by traffic that is not yours. There is no dashboard showing remaining budget — you discover the ceiling when responses start failing.
• The score field ranks results within a single query and is not comparable across queries. A score of 5000 from a rel_rhy query means nothing next to 5000 from an ml query; the values are unnormalized and their scale shifts with the constraint type. Use score for ordering only, never as a confidence threshold or a cross-query filter.

Quick start (bash)

# words meaning roughly ocean, starting with b
curl -s 'https://api.datamuse.com/words?ml=ocean&sp=b*&max=5' | jq -r '.[].word'
# over-constrained queries return [] with HTTP 200, never an error
curl -s 'https://api.datamuse.com/words?ml=ocean&rel_rhy=motion&sp=t???'

Embed this badge

Add a live status badge to your README, docs, or website.

Markdown

[![Datamuse Status](https://api.freeapi.watch/badge/datamuse.svg)](https://freeapi.watch/datamuse)

HTML

<a href="https://freeapi.watch/datamuse"><img src="https://api.freeapi.watch/badge/datamuse.svg" alt="Datamuse Status"/></a>