👤 Username Generator API Documentation

📖 Overview

The Username Generator API produces memorable, themed usernames by pairing adjectives and nouns from one or more built-in word lists. Pick from nine curated themes (Fantasy, Professional, Nature, …), filter by length, optionally append numbers or symbols, and decide whether to deduplicate results. The actual word pool is English-only — there is no language parameter.

🎨 9 Themes

Fantasy, Professional, Science and Space, Computer Technology, Elements and Chemistry, Things, Body and Health, Nature, Space and Time — combine as many as you want in one request.

🔀 Flexible Mixing

One theme, an array themes[], or a comma-separated themes string — they all work and can be combined.

🔢 Optional Numbers & Symbols

Toggle random numbers and symbols independently; control the output length range.

📜 Catalogue Endpoint

Hit ?action=themes to get the full theme list and descriptions without generating anything.

🌐 Base URL

https://api.lorwongam.com/api/username-generator/

🔐 Authentication

No authentication required. This is a public API that can be accessed without any API keys or tokens.

📡 API Endpoints

GET / POST / Generate Usernames

Generate themed usernames. Parameters can be supplied via the query string or as a JSON POST body (same names in both). The default action generates usernames; pass ?action=themes to fetch the theme catalogue instead.

Request Parameters

Parameter	Type	Required	Default	Description
`action`	string	Optional	`generate`	Set to `themes` to return the catalogue of themes + descriptions instead of generating usernames. Any unknown value is treated as `generate`.
`theme`	string	Optional	`Fantasy`	A single theme name. Mutually compatible with `themes[]` and the comma form.
`themes[]`	string[]	Optional	—	Repeated query parameter (e.g. `themes[]=Fantasy&themes[]=Nature`) or an array in JSON body. Combine as many as you want.
`themes`	string	Optional	—	Comma-separated alternative to `themes[]`, e.g. `themes=Fantasy,Nature`.
`count`	integer	Optional	10	How many usernames to produce (1–50).
`min_length`	integer	Optional	6	Lower length bound in characters (must be ≥ 1).
`max_length`	integer	Optional	20	Upper length bound in characters (must be ≤ 50). Must be ≥ `min_length`.
`include_numbers`	boolean	Optional	false	Append a random number suffix to each username.
`include_symbols`	boolean	Optional	false	Append a random symbol suffix to each username.
`capitalize`	boolean	Optional	true	When true, words are kept in their dictionary capitalisation, e.g. `CelestialLeviathan`. When false, the result is lower-cased (e.g. `celestialleviathan`). Adjectives and nouns are always joined directly with no separator.
`avoid_repetition`	boolean	Optional	true	Drop duplicates within the same response. Set false to allow repeats.
`use_all_adjectives`	boolean	Optional	false	Pool adjectives from every theme instead of only the ones you selected.
`use_general_adjectives`	boolean	Optional	false	Mix in the always-available general-purpose adjective list alongside the chosen themes.
`custom_words`	string	Optional	`""`	A comma-separated string of extra words to mix into the pool (the endpoint expects a flat string, not an array).

Available Themes

Theme names are case-sensitive and written with title-case + spaces, exactly as below. The simplest way to confirm is to call ?action=themes at runtime.

Fantasy — Epic and mythical usernames for gaming and fantasy lovers

Professional — Suitable for business, LinkedIn, and professional networks

Science and Space — Science and space exploration themed usernames

Computer Technology — Tech and programming themed usernames

Elements and Chemistry — Science-inspired usernames with elements and compounds

Things — Everyday objects and items themed usernames

Body and Health — Body parts and health-themed usernames

Nature — Nature-inspired usernames with plants, animals, and landscapes

Space and Time — Usernames inspired by concepts of space and time

Example Request — Default (10 fantasy usernames)

curl "https://api.lorwongam.com/api/username-generator/?count=10"

Example Request — Multi-theme with numbers and symbols

curl "https://api.lorwongam.com/api/username-generator/?themes[]=Fantasy&themes[]=Nature&count=5&include_numbers=true&include_symbols=true&max_length=18"

Example Request — POST JSON

curl -X POST "https://api.lorwongam.com/api/username-generator/" \
  -H "Content-Type: application/json" \
  -d '{
    "themes": ["Computer Technology", "Professional"],
    "count":  8,
    "min_length": 8,
    "max_length": 24,
    "include_numbers": true,
    "use_general_adjectives": true
  }'

Example Request — List themes

curl "https://api.lorwongam.com/api/username-generator/?action=themes"

📊 Response Format

Generation success

{
  "success": true,
  "data": {
    "usernames": [
      "CelestialLeviathan",
      "ElectricThunder",
      "StormyDragon"
    ],
    "count": 3,
    "options_used": {
      "themes": ["Fantasy"],
      "min_length": 6,
      "max_length": 20,
      "count": 3,
      "include_numbers": false,
      "include_symbols": false,
      "capitalize": true,
      "avoid_repetition": true,
      "use_all_adjectives": false,
      "use_general_adjectives": false,
      "custom_words": ""
    }
  },
  "generation_info": {
    "themes": ["Fantasy"],
    "theme_count": 1,
    "length_range": "6-20 characters",
    "features": {
      "numbers": "excluded",
      "symbols": "excluded",
      "capitalization": "enabled"
    }
  },
  "timestamp": "2026-09-02 15:41:07"
}

`action=themes` success

{
  "success": true,
  "themes": [
    "Fantasy", "Professional", "Science and Space", "Computer Technology",
    "Elements and Chemistry", "Things", "Body and Health", "Nature", "Space and Time"
  ],
  "theme_descriptions": {
    "Fantasy":              "Epic and mythical usernames for gaming and fantasy lovers",
    "Professional":         "Suitable for business, LinkedIn, and professional networks",
    "Science and Space":    "Science and space exploration themed usernames",
    "Computer Technology":  "Tech and programming themed usernames",
    "Elements and Chemistry": "Science-inspired usernames with elements and compounds",
    "Things":               "Everyday objects and items themed usernames",
    "Body and Health":      "Body parts and health-themed usernames",
    "Nature":               "Nature-inspired usernames with plants, animals, and landscapes",
    "Space and Time":       "Usernames inspired by concepts of space and time"
  }
}

Validation error

All 400-class responses share this shape: { success:false, error:"Validation failed", messages:[...] }. HTTP 400 is returned.

{
  "success": false,
  "error":   "Validation failed",
  "messages": ["Count must be between 1 and 50"]
}

{
  "success": false,
  "error":   "Validation failed",
  "messages": ["Invalid themes: banana"]
}

💡 Use Cases

🌐 Social Media

Generate unique usernames for social media platforms, forums, and online communities.

🎮 Gaming Platforms

Create gaming handles and character names for multiplayer games and platforms.

📧 Email Accounts

Generate professional or creative email addresses for new user registrations.

💼 Professional Profiles

Create professional usernames for business platforms and networking sites.

🏢 Application Users

Provide username suggestions during user registration flows in web and mobile apps.

🎨 Creative Projects

Generate character names for stories, screenplays, or creative writing projects.

⚠️ Error Codes

The API does not return a numeric code field. All validation errors come back with HTTP 400 and the shape { success:false, error:"Validation failed", messages:[...] }. Typical messages include:

Sample message	Cause
`"Count must be between 1 and 50"`	`count` is outside the allowed range
`"Invalid themes: <names>"`	One or more supplied theme names do not exist (typo, wrong case, unsupported)
`"min_length must be ..."`	`min_length`/`max_length` values are out of bounds or `max_length` < `min_length`

🔗 Integration Examples

Registration form

// Suggest 5 professional usernames with a numeric fallback.
fetch('/api/username-generator/?themes[]=Professional&count=5&include_numbers=true')
  .then(r => r.json())
  .then(data => {
    if (!data.success) {
      data.messages.forEach(m => console.warn(m));
      return;
    }
    data.data.usernames.forEach(name => {
      console.log('Suggestion:', name);
    });
  });

Themed character names

// Generate fantasy character names for an RPG.
fetch('/api/username-generator/', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    themes: ['Fantasy', 'Space and Time'],
    count:  20,
    capitalize: true,
    max_length: 22
  })
})
  .then(r => r.json())
  .then(data => data.data.usernames);

Fetch the theme catalogue

fetch('/api/username-generator/?action=themes')
  .then(r => r.json())
  .then(data => {
    console.log(data.themes);              // ["Fantasy", "Professional", ...]
    console.log(data.theme_descriptions);  // { Fantasy: "...", Professional: "...", ... }
  });

🚦 Rate Limits

This endpoint is rate-limited per client identity (IP address, or API key when one is supplied): 60 requests per minute. When the budget is exhausted the API responds with HTTP 429 and includes X-RateLimit-* headers so clients can self-throttle. The exact policy is configured in api/includes/api_config.php.

👤 Username Generator API