Skip to content
Go to file
Cannot retrieve contributors at this time
101 lines (74 sloc) 2.65 KB


rnjeesus interfaces with a simple API. It accepts GET requests and responds with JSON(P) or plain-text.

The API also exposes minimal statistics for the dataset returned.


Example URLs:

  • /api/1..10
    • 1 number between 1 and 10
  • /api/1..5@2
    • 2 numbers between 1 and 5
  • /api/1..100@10/dsc
    • 10 numbers between 1 and 100 in descending order
  • /api/-20..20@50/asc
    • 50 numbers between -20 and 20 in ascending order

Host & Path

The API is hosted at

All requests go through the /api base path.


  • lower (Required)
    • The lower bound (Integer)
  • upper (Required)
    • The upper bound (Integer)
  • quantity (Optional)
    • The amount of numbers (Integer)
    • Default: 1
  • order (Optional)
    • Ordering (ascending, descending, or unset) (String) "asc" or "dsc"
    • Default: unset (no order)

The signature for a request looks like /<lower>..<upper>[@<quantity>][/(asc|dsc)].

Query Strings

Use ?callback=myCallback to set a JSONP callback.

Similarly, ?raw=1 will set the response to be plain-text.


The API is rate-limited on a per-IP basis at 20 requests/minute allowing bursts of up to 5 concurrent requests.

If you're consistently hitting the rate-limit let me know and we can work it out.


The JSON response contains the following keys:

  • status (Boolean): If request was successful
  • message (String): Request feedback. If status is false, this will contain reasoning.
  • data (Object): Contains the randomly generated values and basic statistics on the dataset.
    • values (Array): Contains the values. Sorted in ascending or descending order if specified in the request.
    • statistics (Object): Contains the minimum, maximum, mean, and median values for the dataset.

The following is a sample of a successful JSON response:

  "status": true,
  "message": "The RNG genie has blessed you.",
  "data": {
    "values": [
    "statistics": {
      "minimum": 1,
      "maximum": 83,
      "mean": 43.57142857142857,
      "median": 48

For plain-text responses, the response body will contain either the RNG values delimitted by newlines or the request feedback message (if there was an error).

For example, a request to /api/1..10?raw=1 may return with:


However, if there's an obvious error (/api/100..10?raw=1):

Lower bound cannot be greater than upper bound.
You can’t perform that action at this time.