🎲 Random Generator API Documentation

📖 Overview

The Random Generator API provides cryptographically secure random number generation, dice rolls, coin flips and card draws. Perfect for games, simulations and decision-making applications.

🎲 Multiple Generator Types

Numbers, dice, coins, cards, and an all-in-one bundle

🔒 Cryptographically Secure

Uses secure random number generation for true randomness

📊 Multiple Results

Batch dice rolls and coin flips (up to 10 per request) or draw up to a full deck of cards

🎯 Customizable Ranges

Full control over min/max values and constraints

🌐 Base URL

https://api.lorwongam.com/api/randomizer/

🔐 Authentication

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

📡 API Endpoints

GET / POST /?type=... Random Generator

All five randomizer types are served from the same URL. Pick a value for type and supply any extra parameters as either query-string (GET) or JSON-body (POST) fields. Both work the same way.

Type Values

Type	What it does	Extra params
`number`	One integer in `[min, max]`	`min` (1), `max` (100)
`dice`	Roll `count` dice with `sides` faces	`sides` (6, 2–100), `count` (1, 1–10)
`coin`	Flip `count` coins	`count` (1, 1–10)
`card`	Draw `count` random cards	`count` (1, 1–52 or 1–54 with jokers), `with_jokers` (false)
`all`	Bundle of one number, one dice roll, one coin flip and one card draw	—

Example Request — Number

curl "https://api.lorwongam.com/api/randomizer/?type=number&min=1&max=10"

Example Request — Dice

curl "https://api.lorwongam.com/api/randomizer/?type=dice&sides=6&count=2"

Example Request — Coin

curl "https://api.lorwongam.com/api/randomizer/?type=coin&count=3"

Example Request — Card

curl "https://api.lorwongam.com/api/randomizer/?type=card&count=2&with_jokers=true"

Example Request — All

curl "https://api.lorwongam.com/api/randomizer/?type=all"

📊 Response Format

Number Response

{
  "type":      "number",
  "result":    10,
  "range":     { "min": 1, "max": 10 },
  "timestamp": "2025-09-09 12:00:00",
  "success":   true,
  "api_info": {
    "version":         "1.0",
    "endpoint":        "/api/randomizer/",
    "supported_types": ["number", "dice", "coin", "card", "all"]
  }
}

Dice Response

{
  "type":        "dice",
  "result":      [5, 5],
  "total":       10,
  "dice_config": { "sides": 6, "count": 2 },
  "timestamp":   "2025-09-09 12:00:00",
  "success":     true,
  "api_info":    { "...": "..." }
}

When count=1 the result is a single integer instead of an array.

Coin Response

{
  "type":       "coin",
  "result":     ["Tails", "Heads", "Heads"],
  "statistics": { "heads": 2, "tails": 1 },
  "count":      3,
  "timestamp":  "2025-09-09 12:00:00",
  "success":    true,
  "api_info":   { "...": "..." }
}

When count=1 the result is a single string ("Heads" or "Tails").

Card Response

{
  "type":      "card",
  "result": [
    {
      "rank":    "8",
      "suit":    "Hearts",
      "symbol":  "♥",
      "display": "8 of Hearts",
      "short":   "8♥",
      "color":   "red"
    },
    {
      "rank":    "4",
      "suit":    "Hearts",
      "symbol":  "♥",
      "display": "4 of Hearts",
      "short":   "4♥",
      "color":   "red"
    }
  ],
  "deck_info": {
    "total_cards": 52,
    "with_jokers": false,
    "cards_drawn": 2
  },
  "timestamp": "2025-09-09 12:00:00",
  "success":   true,
  "api_info":  { "...": "..." }
}

When count=1 the result is a single card object. With with_jokers=true the deck has 54 cards (52 + 2 jokers).

All Response

{
  "type": "all",
  "results": {
    "number": { "type": "number", "result": 33, "...": "..." },
    "dice":   { "type": "dice",   "result": 4,   "...": "..." },
    "coin":   { "type": "coin",   "result": "...", "...": "..." },
    "card":   { "type": "card",   "result": { "...": "..." }, "...": "..." }
  },
  "timestamp": "2025-09-09 12:00:00",
  "success":   true,
  "api_info":  { "...": "..." }
}

Error Response

The API returns HTTP 400 with a free-form error string and the same api_info block.

{
  "success":   false,
  "error":     "Invalid type. Supported types: number, dice, coin, card, all",
  "timestamp": "2025-09-09 12:00:00",
  "api_info":  { "version": "1.0", "endpoint": "/api/randomizer/", "supported_types": ["number", "dice", "coin", "card", "all"] }
}

Other triggers and their messages:

Trigger	HTTP	`error` text
`type` set to an unsupported value	400	Invalid type. Supported types: number, dice, coin, card, all (omitting `type` is not an error — it defaults to `number`)
`min > max`	400	Minimum value cannot be greater than maximum value
dice `sides` outside 2–100	400	Dice sides must be between 2 and 100
dice `count` outside 1–10	400	Dice count must be between 1 and 10
coin `count` outside 1–10	400	Coin count must be between 1 and 10
card `count` outside 1–52 (or 1–54 with jokers)	400	Card count must be between 1 and 52 (or 1 and 54)
Any other unexpected failure	500	Internal server error

🎯 Generator Types

🔢 Number Generator

Single integer between min and max (inclusive). Defaults: min=1, max=100.

🎲 Dice Roller

Roll count dice (1–10) with sides faces (2–100). Defaults: sides=6, count=1.

🪙 Coin Flip

Flip count coins (1–10). Returns the per-flip result and a heads/tails tally. Default count=1.

🃏 Card Draw

Draw count cards from a 52-card deck, optionally extended to 54 with with_jokers=true. Each card carries rank, suit, symbol, display, short and color.

🎁 All-in-One

Returns one number (1–100), one dice roll (6-sided), one coin flip and one card draw in a single response.

💡 Use Cases

🎮 Game Development

Dice rolls, card draws, and random events for board games, RPGs, and video games.

📊 Statistical Sampling

Random numbers for surveys, A/B testing, and statistical simulation.

🎁 Giveaways & Contests

Use the cryptographically secure random values as the randomness source in your own raffle and contest logic.

🔐 Security & Tokens

Generate secure random tokens, nonces, and identifiers for authentication systems.

🎲 Decision Making

Coin flips and random selection for unbiased decision-making tools and applications.

🧪 Simulations

Monte Carlo simulations, random testing data, and probabilistic modeling scenarios.

⚠️ Error Conditions

The API returns the same human-readable error string shown above — no numeric error codes. Triggers are summarised in the table inside the Response Format → Error Response section.

🚦 Rate Limits

This endpoint is rate-limited per client identity (IP address, or API key when one is supplied): 120 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.

🎲 Random Generator API