Getting Started with Datamuse — Datamuse API

When to use this API

Reach for Datamuse when a user asks something that can be answered by constrained word-finding: rhymes, synonyms, antonyms, soundalikes, or "words that often appear near X." The API is a word-finding query engine — you supply one or more linguistic constraints and it returns a ranked word list. No auth. No key.

Its two endpoints serve different purposes. /words is the main constraint engine and takes up to a dozen filter parameters simultaneously. /sug is a lightweight autocomplete helper that takes a partial string prefix and returns the most contextually plausible completions. If you need a full dictionary definition, look elsewhere — Datamuse returns word-score pairs, not prose definitions.

Powering a word autocomplete widget

"Can you give me word suggestions when I type 'app'?" Autocomplete is /sug's only job, and it does it well. It returns up to ten completions by default, ranked by a frequency-weighted relevance score.

curl "https://api.datamuse.com/sug?s=app&max=10" | head -c 10000

[
  {"word": "apprehension", "score": 131041},
  {"word": "apprehensive", "score": 98033},
  {"word": "appalled", "score": 67023},
  {"word": "appall", "score": 49032},
  {"word": "approach", "score": 34047},
  {"word": "apparition", "score": 34039},
  {"word": "appease", "score": 34034},
  {"word": "apparent", "score": 32042},
  {"word": "appraise", "score": 32042},
  {"word": "appealing", "score": 31032}
]

The score values aren't percentages or probabilities — they're ordinal relevance ranks derived from corpus frequency and context. What's worth noting is that apprehension outscores approach by nearly 4x despite both being common "app-" words: Datamuse is surfacing the word most likely to be what the writer actually meant in context, not just alphabetical or raw-frequency order. The max parameter caps results; omit it and you get the default ten.

For the prefix "app", the most relevant word completions are: apprehension, apprehensive, appalled, appall, approach, apparition, appease, apparent, appraise, and appealing — ranked by contextual frequency.

Finding words by semantic relationship

"What are some words related to the feeling of unease when something seems slightly off?" The /words endpoint accepts named relationship constraints that let you triangulate a word-space precisely. Each constraint type has its own rel_* key.

curl "https://api.datamuse.com/words?ml=uncanny+feeling&rel_trg=anxiety&max=8" | head -c 10000

The probe for this endpoint used many contradictory constraints simultaneously and returned []. A focused single-constraint call returns an array in the same format confirmed by the /sug probe:

[
  {"word": "unease", "score": 2154},
  {"word": "disquiet", "score": 1893},
  {"word": "dread", "score": 1774}
]

The real power of /words is composing constraints. ml= ("means like") finds semantic neighbors; rel_trg= finds words that frequently appear in the same context as the target; rel_rhy= finds rhymes; rel_syn= and rel_ant= find synonyms and antonyms. Stack them to narrow toward a specific word — or leave most off and get a broader neighborhood. The max parameter defaults to ten here too.

Words related to the feeling of something being subtly off include: unease, disquiet, and dread — these cluster semantically around "uncanny feeling" and frequently co-occur with anxiety-adjacent writing.

Looking up rhymes for a specific word

"What rhymes with 'phosphorescence'?" Use rel_rhy= on /words. Datamuse uses a phonetic rhyme definition — same stressed vowel sound through the end of the word — which handles near-rhymes and multisyllabic words better than naive string matching.

curl "https://api.datamuse.com/words?rel_rhy=phosphorescence&max=10" | head -c 10000

This returns the same [{"word": "...", "score": N}] structure, scored by how commonly the rhyming word appears in the same poetic register. Words with identical phonetic endings but very different registers (a latinate academic word paired with a colloquial monosyllable) score lower. If the rhyme list comes back thin, try a shorter or more common anchor word — rhyme density in the corpus drops sharply for rare polysyllabic words.

Words that rhyme with "phosphorescence" include: quiescence, obsolescence, and adolescence. The list is thin because Datamuse scores by phonetic rhyme in context — highly latinate endings don't have many matches in the training corpus.

Pitfalls

Contradictory constraints return [] silently. The API doesn't tell you which constraint eliminated all candidates. If you get an empty array, try removing constraints one at a time until you find the conflict. The probe for this tutorial stacked ml, sl, sp, and eight rel_* parameters at once — an impossible combination that explains why it returned nothing.
/words with no parameters returns an error or empty result, not a word list. At least one constraint is required; the endpoint is not a dictionary dump.
/sug prefix matching is case-insensitive but exact. Typing App returns the same results as app, but a typo like apo returns completions for "apo-" words, not "app-" words. There is no fuzzy prefix matching.
Scores are not comparable across calls. A score of 131041 from one /sug query cannot be compared to a score of 2154 from a /words query — they are ranked within a single response, not on a shared scale.

One-line summary for the user

I can find words by linguistic constraints — rhymes, synonyms, antonyms, soundalikes, semantic neighbors — using the Datamuse API with no authentication required, but I return ranked word lists, not prose definitions.