Random Word List API

The random word list API generates a list of words at random of a set length. It’s a great option when you need multiple words for use cases such as word games or writing prompts.

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 List 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-list:
    get:
      summary: Random Word List Generator
      parameters:
        - name: word_count
          in: query
          description: The number of words to generate - minimum value of 2, maximum value of 25 (defaults to 3)
          required: false
          schema:
            type: integer
        - name: is_common
          in: query
          description: If the random words 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
        - name: min_length
          in: query
          description: The minimum length of the random words - 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 words - maximum value of 15, minimum value of 2 or min_length query param if set (defaults to 15)
          required: false
          schema:
            type: integer
      responses:
        "200":
          description: A JSON object containing an array of random words
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RandomWordListResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse"
        "422":
          $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:
    RandomWordListResponse:
      type: object
      properties:
        random_words:
          description: An array of random words generated
          type: array
          items:
            type: string
          example: ["HELLO", "GOODBYE"]
      required:
        - random_words

Example Request

curl --request GET \
	--url 'https://word-checker-api.p.rapidapi.com/v1/generator/random-word-list?word_count=$WORD_COUNT&is_common=$IS_COMMON&min_length=$MIN_LENGTH&max_length=$MAX_LENGTH' \
	--header 'x-rapidapi-host: word-checker-api.p.rapidapi.com' \
	--header 'x-rapidapi-key: $YOUR_RAPID_API_KEY'

Request Parameters

Query Parameters

• WORD_COUNT: The number of words to generate - minimum value of 2, maximum value of 25 (defaults to 3).
• IS_COMMON: If the random words should be in a list of common English words - 1 for a common word, 0 to use the full word list (defaults to 0).
• MIN_LENGTH: The minimum length of the random words - 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 words - maximum value of 15, minimum value of 2 or min_length query param if set (defaults to 15).

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 containing an array of the random words generated.

{ "random_words": ["CIRCLE", "DISPLAY", "CONSTRUCTION"] }

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 cannot be less than 2."
}

When there is not enough matching words that match the conditions of your query parameters, a TOO_NARROW_SEARCH error response like below is returned with a 422 status code.

{
  "error": "TOO_NARROW_SEARCH",
  "error_hint": "Search criteria was too narrow, could not return the desired word count."
}

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