Random Word API

The random word API simply generates a word at random from our dictionary. You can request a word that contains specific letter patterns or is a specific length.

On this page

• Consuming the API
• Endpoint Open API Specification
• Example Request
• Request Parameters
• Example Response

Consuming the API

• Navigate to the Word Checker Rapid API page.
• You will need to setup a Rapid API account and application to use our APIs. We offer a free subscription package on Rapid API, however, you may need to switch to a paid subscription if your application traffic grows.
• Click on the endpoint titled GET Random Word Generator section.

Endpoint Open API Specification

openapi: 3.0.4

info:
  title: Word Checker Service
  description: API of word tools such as anagram solvers, random word generators, and more.
  version: 1.0.0

paths:
  /v1/generator/random-word:
    get:
      summary: Random Word Generator
      parameters:
        - name: first_letters
          in: query
          description: The letter(s) that the random word must begin with
          required: false
          schema:
            type: string
        - name: includes_letters
          in: query
          description: The letter(s) that the random word must include
          required: false
          schema:
            type: string
        - name: last_letters
          in: query
          description: The letter(s) that the random word must end with
          required: false
          schema:
            type: string
        - name: min_length
          in: query
          description: The minimum length of the random word - minimum value of 2, maximum value of 15 or max_length query param if set (defaults to 2)
          required: false
          schema:
            type: integer
        - name: max_length
          in: query
          description: The maximum length of the random word - maximum value of 15, minimum value of 2 or min_length query param if set (defaults to 15)
          required: false
          schema:
            type: integer
        - name: is_common
          in: query
          description: If the random word should be in a list of common English words - 1 for a common word, 0 to use the full word list (defaults to 0)
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
      responses:
        "200":
          description: A JSON object containing the random word
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RandomWordResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"

components:
  responses:
    ErrorResponse:
      description: A generic error responses with error code and hint
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                description: The error code
                type: string
                example: ERROR_CODE
              error_hint:
                description: A hint to resolve the error
                type: string
                example: Error hint
            required:
              - error
              - error_hint
    TooManyRequests:
      description: Too Many Requests
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                description: The error code
                type: string
                example: TOO_MANY_REQUESTS
              error_hint:
                description: A hint to resolve the error
                type: string
                example: You're making requests a bit too quickly. Please wait a moment and try again.
            required:
              - error
              - error_hint
  schemas:
    RandomWordResponse:
      type: object
      properties:
        random_word:
          description: The random word generated
          type: string
          example: HELLO
      required:
        - random_word

Example Request

curl --request GET \
	--url 'https://word-checker-api.p.rapidapi.com/v1/generator/random-word?first_letters=$FIRST_LETTERS&includes_letters=$INCLUDES_LETTERS&last_letters=$LAST_LETTERS&min_length=$MIN_LENGTH&max_length=$MAX_LENGTH&is_common=$IS_COMMON' \
	--header 'x-rapidapi-host: word-checker-api.p.rapidapi.com' \
	--header 'x-rapidapi-key: $YOUR_RAPID_API_KEY'

Request Parameters

Query Parameters

• FIRST_LETTERS: The letter(s) that the random word must begin with (defaults to any letters).
• INCLUDES_LETTERS: The letter(s) that the random word must include (defaults to any letters).
• LAST_LETTERS: The letter(s) that the random word must end with (defaults to any letters).
• MIN_LENGTH: The minimum length of the random word - minimum value of 2, maximum value of 15 or max_length query param if set (defaults to 2).
• MAX_LENGTH: The maximum length of the random word - maximum value of 15, minimum value of 2 or min_length query param if set (defaults to 15).
• IS_COMMON: If the random word should be in a list of common English words - 1 for a common word, 0 to use the full word list (defaults to 0).

Headers

• YOUR_RAPID_API_KEY: You’re Rapid API key to authenticate the request. See Rapid APIs docs.

Example Response

A successful response will be a JSON object simply containing the random word generated.

{ "random_word": "SALAD" }

If a response is unsuccessful, a standard error response will be returned. For example, the below represents an INVALID_LENGTH error.

{
  "error": "INVALID_LENGTH",
  "error_hint": "Minimum word length is greater than maximum word length."
}

When there are no matching words for the query parameters conditions, a NO_MATCHES error response like below is returned with a 404 status code.

{
  "error": "NO_MATCHES",
  "error_hint": "No words matched your search conditions."
}

The error_hint is meant for the application/server and may not always make sense to display to the end user.