Datamuse Words API

openapi: 3.1.0
info:
  title: Datamuse Suggestions Words API
  description: 'The Datamuse API is a word-finding query engine for developers. It returns lists of

    words (and optional metadata) matching a combination of semantic, phonetic, orthographic,

    and vocabulary constraints, plus context ranking hints. The API powers OneLook,

    OneLook Thesaurus, RhymeZone, Rimar.io, and CivicSearch.


    Two operations are exposed:


    * `GET /words` — find words matching a rich set of constraint and ranking parameters.

    * `GET /sug` — return autocomplete suggestions for a partially-entered string.


    The service is free for non-commercial use up to 100,000 requests per day with no

    API key required. Commercial use, higher rate limits, and custom vocabularies are

    available via a paid commercial agreement.

    '
  version: 1.1.0
  termsOfService: https://www.datamuse.com/api/
  contact:
    name: Datamuse API Support
    url: https://www.datamuse.com/api/
  license:
    name: Datamuse Free Non-Commercial Use
    url: https://www.datamuse.com/api/
servers:
- url: https://api.datamuse.com
  description: Datamuse production API
tags:
- name: Words
  description: Word-finding queries combining semantic, phonetic, orthographic, and vocabulary constraints.
paths:
  /words:
    get:
      summary: Find Words Matching Constraints
      description: 'Find words matching any combination of constraints. Constraints may be combined

        freely; results are ranked by relationship strength for semantic constraints,

        otherwise by frequency. Optional metadata flags add definitions, parts of speech,

        syllable counts, pronunciations, and corpus frequency to each result.

        '
      operationId: getWords
      tags:
      - Words
      parameters:
      - $ref: '#/components/parameters/MeansLike'
      - $ref: '#/components/parameters/SoundsLike'
      - $ref: '#/components/parameters/SpelledLike'
      - $ref: '#/components/parameters/RelJja'
      - $ref: '#/components/parameters/RelJjb'
      - $ref: '#/components/parameters/RelSyn'
      - $ref: '#/components/parameters/RelTrg'
      - $ref: '#/components/parameters/RelAnt'
      - $ref: '#/components/parameters/RelSpc'
      - $ref: '#/components/parameters/RelGen'
      - $ref: '#/components/parameters/RelCom'
      - $ref: '#/components/parameters/RelPar'
      - $ref: '#/components/parameters/RelBga'
      - $ref: '#/components/parameters/RelBgb'
      - $ref: '#/components/parameters/RelRhy'
      - $ref: '#/components/parameters/RelNry'
      - $ref: '#/components/parameters/RelHom'
      - $ref: '#/components/parameters/RelCns'
      - $ref: '#/components/parameters/Vocabulary'
      - $ref: '#/components/parameters/Topics'
      - $ref: '#/components/parameters/LeftContext'
      - $ref: '#/components/parameters/RightContext'
      - $ref: '#/components/parameters/Max'
      - $ref: '#/components/parameters/Metadata'
      - $ref: '#/components/parameters/QueryEcho'
      - $ref: '#/components/parameters/Ipa'
      responses:
        '200':
          description: A ranked list of matching words.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Word'
        '400':
          description: Malformed request (unknown parameter or invalid value).
        '429':
          description: Too many requests — exceeded the 100,000 requests/day free tier limit.
components:
  parameters:
    Topics:
      name: topics
      in: query
      description: Up to five space- or comma-separated topic words that skew results toward the indicated document theme.
      schema:
        type: string
      example: technology computers
    RelJjb:
      name: rel_jjb
      in: query
      description: Popular adjectives modifying the given noun, per Google Books Ngrams.
      schema:
        type: string
    RelCom:
      name: rel_com
      in: query
      description: Direct holonyms ("comprises").
      schema:
        type: string
    RelCns:
      name: rel_cns
      in: query
      description: Consonant matches — words with the same consonant skeleton.
      schema:
        type: string
    RelAnt:
      name: rel_ant
      in: query
      description: Antonyms (WordNet).
      schema:
        type: string
    RelHom:
      name: rel_hom
      in: query
      description: Homophones — words pronounced the same.
      schema:
        type: string
    LeftContext:
      name: lc
      in: query
      description: Left context — a single word appearing immediately to the left of the target word.
      schema:
        type: string
    RelBga:
      name: rel_bga
      in: query
      description: Frequent followers — words that frequently appear immediately after the query word.
      schema:
        type: string
    Metadata:
      name: md
      in: query
      description: "Metadata flags — a string composed of single-letter codes requesting lexical\nmetadata for each result:\n  * `d` — definitions (and `defHeadword` for inflected forms)\n  * `p` — parts of speech (n, v, adj, adv, u)\n  * `s` — syllable count (`numSyllables`)\n  * `r` — pronunciation (Arpabet; combine with `ipa=1` for IPA)\n  * `f` — corpus frequency (per million words, Google Books Ngrams)\n"
      schema:
        type: string
      example: dpsrf
    SoundsLike:
      name: sl
      in: query
      description: Sounds like — phonetic constraint requiring results pronounced similarly to the input.
      schema:
        type: string
      example: jirraf
    RelPar:
      name: rel_par
      in: query
      description: Direct meronyms ("part of").
      schema:
        type: string
    RelTrg:
      name: rel_trg
      in: query
      description: Triggers — words statistically associated with the query word in the same piece of text.
      schema:
        type: string
    Max:
      name: max
      in: query
      description: Maximum number of results to return.
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 100
    Ipa:
      name: ipa
      in: query
      description: When set to `1` and pronunciation metadata is requested, return IPA-format pronunciations instead of Arpabet.
      schema:
        type: integer
        enum:
        - 0
        - 1
    Vocabulary:
      name: v
      in: query
      description: Vocabulary identifier. Default English (`en`, 550k terms) or `es` for Spanish (500k terms). Custom vocabularies available on request.
      schema:
        type: string
        enum:
        - en
        - es
        default: en
    SpelledLike:
      name: sp
      in: query
      description: Spelled like — orthographic constraint with wildcards (`*` any chars, `?` single char). URL-encode the value.
      schema:
        type: string
      example: hipp*
    RelBgb:
      name: rel_bgb
      in: query
      description: Frequent predecessors — words that frequently appear immediately before the query word.
      schema:
        type: string
    RelNry:
      name: rel_nry
      in: query
      description: Approximate (near) rhymes.
      schema:
        type: string
    MeansLike:
      name: ml
      in: query
      description: Means like — semantic constraint requiring results with meaning related to the input string (reverse-dictionary lookup).
      schema:
        type: string
      example: ringing in the ears
    RelJja:
      name: rel_jja
      in: query
      description: Popular nouns modified by the given adjective, per Google Books Ngrams.
      schema:
        type: string
    RelRhy:
      name: rel_rhy
      in: query
      description: Perfect rhymes.
      schema:
        type: string
    RightContext:
      name: rc
      in: query
      description: Right context — a single word appearing immediately to the right of the target word.
      schema:
        type: string
    RelGen:
      name: rel_gen
      in: query
      description: Direct hyponyms ("more general than").
      schema:
        type: string
    RelSpc:
      name: rel_spc
      in: query
      description: Direct hypernyms ("kind of").
      schema:
        type: string
    RelSyn:
      name: rel_syn
      in: query
      description: Synonyms (WordNet).
      schema:
        type: string
    QueryEcho:
      name: qe
      in: query
      description: Query echo — prepend a result describing the query string from the named parameter, useful for one-shot metadata lookups.
      schema:
        type: string
  schemas:
    Word:
      type: object
      description: A word returned from the /words endpoint.
      required:
      - word
      properties:
        word:
          type: string
          description: The matched word or short phrase.
          example: giraffe
        score:
          type: integer
          description: Relationship-strength or popularity score; relative within the result set.
          example: 1075
        numSyllables:
          type: integer
          description: Syllable count (returned when `md=s` is requested).
          example: 2
        tags:
          type: array
          description: 'Lexical tags returned when metadata flags are requested. May include

            parts-of-speech codes (`n`, `v`, `adj`, `adv`, `u`), pronunciation entries

            prefixed `pron:`, and frequency entries prefixed `f:`.

            '
          items:
            type: string
          example:
          - n
          - pron:JH ER0 AE1 F
          - f:0.422043
        defs:
          type: array
          description: Definitions returned when `md=d` is requested. Each entry is prefixed by its part-of-speech code.
          items:
            type: string
          example:
          - "n\ttall spotted East African mammal with a long neck"
        defHeadword:
          type: string
          description: Base headword form returned for inflected words when definitions are requested.