Basic API (Release 4)

Introduction

The Basic API methods are sufficient to fetch true random values into your mobile app or web app. Each method produces a series of true random values, generated specifically for your client. Values can be generated with or without replacement. When replacement is used, each value is statistically independent from its predecessors. Successive invocations will always produce new values in a statistically independent fashion from previous requests.

The methods are intended to be simple to use to obtain true random values, but it is not intended to build applications that support non-repudiation. For such applications, please see the Signed API.

URL

The URL for invoking the Basic API is https://api.random.org/json-rpc/4/invoke

Changes from Release 3

  • A new optional parameter pregeneratedRandomization was added to the following methods:
    • generateIntegers
    • generateIntegerSequences
    • generateDecimalFractions
    • generateGaussians
    • generateStrings
    • generateUUIDs
    • generateBlobs

generateIntegers (method)

This method generates true random integers within a user-defined range. Your client must set the method property of its JSON-RPC request object to generateIntegers. The request must also contain an id member, which will be returned in the response.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

apiKey
Your API key, which is used to track the true random bit usage for your client.
n
How many random integers you need. Must be within the [1,1e4] range.
min
The lower boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range.
max
The upper boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range.

Optional Parameters

The following parameters are optional and can be included in the params object of your JSON-RPC request if you want functionality that is different from the default:

replacement (default value true)
Specifies whether the random numbers should be picked with replacement. The default (true) will cause the numbers to be picked with replacement, i.e., the resulting numbers may contain duplicate values (like a series of dice rolls). If you want the numbers picked to be unique (like raffle tickets drawn from a container), set this value to false.
base (default value 10)
Specifies the base that will be used to display the numbers. Values allowed are 2, 8, 10 and 16. This affects the JSON types and formatting of the resulting data as discussed below.
pregeneratedRandomization (default value null)
Allows the client to specify that the random values should be generated from a pregenerated, historical randomization instead of a one-time on-the-fly randomization. There are three possible cases:
  • If the caller specifies a null value (or does not specify a value), then RANDOM.ORG will generate true randomness specifically for the caller and will discard this randomness immediately after it has been used to generate the random values requested. This is the standard way of using a true random number generator.
  • If the caller specifies an object of the form { "date": "YYYY-MM-DD" } where YYYY-MM-DD is a date in ISO 8601 format, then RANDOM.ORG uses historical true randomness generated on the corresponding date. The date must be in the past or the current date in UTC time.
  • If the caller specifies an object of the form { "id": "PERSISTENT-IDENTIFIER" } where PERSISTENT-IDENTIFIER is a string, then RANDOM.ORG uses historical true randomness derived from the corresponding identifier in a deterministic manner. The identifier must have a length in the [1, 64] range.
The two non-null forms for the pregeneratedRandomization parameter causes RANDOM.ORG to generate the random values based on a pregenerated randomization, i.e., historical true randomness generated by RANDOM.ORG at some point in the past. This makes it possible for the client to replay a given sequence of numbers at a later stage, and also allows multiple parties in different locations to get the same numbers in a predictable fashion. These modes effectively turn RANDOM.ORG into a pseudo-random number generator.

Successful Response

If the numbers were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

random
This object encapsulates the random numbers and associated data. It contains the following properties.
data
An array containing the sequence of numbers requested. If the request specified base 10 (or did not specify a base and therefore defaults to 10), the elements in the array will be integers. Because JSON (according to RFC4627) only allows numbers to be written as decimal, the numbers will be typed as strings if a different base than 10 was specified in the request. Numbers in any base other than 10 will be padded with leading zeros up to the width required to display the chosen range.
completionTime
A string containing the timestamp in ISO 8601 format at which the request was completed.
bitsUsed
An integer containing the number of true random bits used to complete this request.
bitsLeft
An integer containing the (estimated) number of remaining true random bits available to the client.
requestsLeft
An integer containing the (estimated) number of remaining API requests available to the client.
advisoryDelay
An integer containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

Simple clients may not necessarily need all of the properties in the response. A minimal client could use only the random.data and advisoryDelay properties and ignore the rest of the response.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests six numbers in the [1,6] range. The replacement parameter is set to true, which means the numbers will be picked with replacement, i.e., can contain duplicate values. This makes them suitable for use as dice rolls.

{
    "jsonrpc": "2.0",
    "method": "generateIntegers",
    "params": {
        "apiKey": "6b1e65b9-4186-45c2-8981-b77a9842c4f0",
        "n": 6,
        "min": 1,
        "max": 6,
        "replacement": true
    },
    "id": 42
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
    	"random": {
            "data": [
                1, 5, 4, 6, 6, 4
            ],
            "completionTime": "2011-10-10 13:19:12Z"
        },
        "bitsUsed": 16,
        "bitsLeft": 199984,
        "requestsLeft": 9999,
        "advisoryDelay": 0
    },
    "id": 42
}

The random object contains the true random values (in the data array) produced as well as the completion time. Note that the completionTime specifies UTC time zone (‘Zulu time’) by the letter ‘Z’ after the clock time. Through the other fields in the result object, RANDOM.ORG also advises how many true random bits were used to satisfy the request (16) and how many bits (199,984) and requests (9,999) are left in the client's quota. It also advises the client that it can go ahead and issue the next request without delay (0 milliseconds).

Example 2

The following requests 52 numbers in the [1,52] range. The replacement parameter is set to false, meaning the numbers will be picked without replacement, i.e., duplicates will not occur. This makes them suitable to shuffle a deck of cards.

{
    "jsonrpc": "2.0",
    "method": "generateIntegers",
    "params": {
        "apiKey": "6b1e65b9-4186-45c2-8981-b77a9842c4f0",
        "n": 52,
        "min": 1,
        "max": 52,
	"replacement": false
    },
    "id": 3076
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                39, 24, 18, 46, 6, 52, 36, 30, 40, 42, 37, 4, 7, 20, 1, 44, 25, 9, 21,
                29, 51, 41, 14, 15, 48, 50, 31, 17, 3, 19, 45, 35, 2, 43, 26, 16, 5, 23,
                12, 8, 10, 47, 13, 33, 34, 49, 22, 11, 28, 27, 38, 32
	    ],
            "completionTime": "2011-10-10 13:19:12Z",
        },
	"bitsUsed": 296,
	"bitsLeft": 199704,
        "requestsLeft": 9999,
	"advisoryDelay": 2000
    },
    "id": 3076
}

The random object contains the true random numbers (in the data array) produced, as well as the completion time.

The remaining fields in the result object indicate how many true random bits were used to satisfy the request as well as how many bits and requests are left in the client's quota. The response also advises the client preferably to delay at least two seconds before issuing a new request.

Example 3

The following requests 512 bytes, i.e., numbers in the [0,255] range. No replacement parameter is given, which means the service will use the default value of true and the numbers will be picked with replacement, i.e., duplicates are allowed. The optional base parameter is used to indicate that the client wishes the numbers to be returned in hexadecimal form. The numbers could be used as seed material for a pseudo-random number generator.

{
    "jsonrpc": "2.0",
    "method": "generateIntegers",
    "params": {
        "apiKey": "6b1e65b9-4186-45c2-8981-b77a9842c4f0",
        "n": 512,
        "min": 0,
        "max": 255,
        "base": 16
    },
    "id": 4352
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
	        "90", "a6", "3e", "f7", "06", ...
            ],
            "completionTime": "2011-10-10 13:19:12Z"
        },
        "bitsUsed": 4096,
        "bitsLeft": 195904,
        "requestsLeft": 9999,
        "advisoryDelay": 0
    },
    "id": 4352
}

The random object contains the random data generated by the server. For brevity, only the first five bytes are shown in the response. Note that the data array contains strings rather than integers, because the numbers are formatted in base 16.

The service also advises how many true random bits were used to satisfy the request and how many bits and requests are left in the client's quota.

Example 4

The following requests three numbers in the [1,6] range. The replacement parameter is set to true, which means the numbers will be picked with replacement, i.e., can contain duplicate values. The client also specifies a value of type date for the optional pregeneratedRandomization parameter, meaning that the results will be historical randomness generated by RANDOM.ORG at some point in the past.

{
    "jsonrpc": "2.0",
    "method": "generateIntegers",
    "params": {
        "apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
        "n": 3,
        "min": 1,
        "max": 6,
        "replacement": true,
        "base": 10,
        "pregeneratedRandomization": {
            "date": "2010-12-31"
        }
    },
    "id": 12691
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                4, 5, 4
            ],
            "completionTime": "2021-03-25 21:38:06Z"
        },
        "bitsUsed": 0,
        "bitsLeft": 246374,
        "requestsLeft": 979,
        "advisoryDelay": 2350
    },
    "id": 12691
}

The random object contains the random integers returned by the server. By asking for pregenerated random values, any request with the same specifications, i.e. the same values for n, min, max, replacement and pregeneratedRandomization, will return the same data. This also applies to the equivalent method in the Signed API, see Example 7 of the generateSignedIntegers method.

The service also advises that no bits were used to satisfy the request, as the values are not generated on-the-fly. It also includes how many bits and requests are left in the client's quota.

Example 5

The following request differs from that in Example 4 only in that the optional pregeneratedRandomization parameter contains an id value instead of a date value.

{
    "jsonrpc": "2.0",
    "method": "generateIntegers",
    "params": {
        "apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
        "n": 3,
        "min": 1,
        "max": 6,
        "replacement": true,
        "base": 10,
        "pregeneratedRandomization": {
            "id": "foobar"
        }
    },
    "id": 12691
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                4, 6, 1
            ],
            "completionTime": "2021-03-25 21:36:39Z"
        },
        "bitsUsed": 0,
        "bitsLeft": 246374,
        "requestsLeft": 980,
        "advisoryDelay": 3030
    },
    "id": 12691
}

As in Example 4, the values in the data object were generated at some point in the past and any time a request with the same parameters is sent, the data returned will be identical.

generateIntegerSequences (method)

This method generates uniform or multiform sequences of true random integers within user-defined ranges. Uniform sequences all have the same general form (length, range, replacement and base) whereas these characteristics can vary for multiform sequences. Your client must set the method property of its JSON-RPC request object to generateIntegerSequences. The request must also contain an id member, which will be returned in the response.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

apiKey
Your API key, which is used to track the true random bit usage for your client.
n
An integer specifying the number of sequences requested. Must be within the [1, 1000] range.
length
This parameter specifies the lengths of the sequences requested. For uniform sequences, length must be an integer in the [1, 10000] range. For multiform sequences, length can be an array with n integers, each specifying the length of the sequence identified by its index. In this case, each value in length must be within the [1, 10000] range and the total sum of all the lengths must be in the [1, 10000] range.
min
This parameter specifies the lower boundaries of the sequences requested. For uniform sequences, min must be an integer in the [-1000000000, 1000000000] range. For multiform sequences, min can be an array with n integers, each specifying the lower boundary of the sequence identified by its index. In this case, each value in min must be within the [-1000000000, 1000000000] range.
max
This parameter specifies the upper boundaries of the sequences requested. For uniform sequences, max must be an integer in the [-1000000000, 1000000000] range. For multiform sequences, max can be an array with n integers, each specifying the upper boundary of the sequence identified by its index. In this case, each value in max must be within the [-1000000000, 1000000000] range.

Optional Parameters

The following parameters are optional and can be included in the params object of your JSON-RPC request if you want functionality that is different from the default:

replacement (default value true)
This parameter specifies whether the requested sequences should be picked with replacement. When numbers in a sequence are picked with replacement, the sequence may contain duplicate values (like a series of dice rolls). When picked without replacement, the numbers in the sequence will be unique (like raffle tickets drawn from a container). For uniform sequences, replacement must be a Boolean value where true indicates the sequences will be picked with replacement and false indicates that they will not. For multiform sequences, replacement can be an array with n Boolean values, each specifying whether the sequence identified by its index will be created with (true) or without (false) replacement.
base (default value 10)
This parameter specifies the base that will be used to display the numbers in the sequences. For uniform sequences, base must be an integer with with one of the values 2, 8, 10 or 16. For multiform sequences, base can be an array with n integer values taken from the same set, each specifying the base that will be used to display the sequence identified by its index. Use of the base parameter affects the JSON types and formatting of the resulting data as discussed in the documentation for the generateIntegers method.
pregeneratedRandomization (default value null)
Allows the client to specify that the random values should be generated from a pregenerated, historical randomization instead of a one-time on-the-fly randomization. There are three possible cases:
  • If the caller specifies a null value (or does not specify a value), then RANDOM.ORG will generate true randomness specifically for the caller and will discard this randomness immediately after it has been used to generate the random values requested. This is the standard way of using a true random number generator.
  • If the caller specifies an object of the form { "date": "YYYY-MM-DD" } where YYYY-MM-DD is a date in ISO 8601 format, then RANDOM.ORG uses historical true randomness generated on the corresponding date. The date must be in the past or the current date in UTC time.
  • If the caller specifies an object of the form { "id": "PERSISTENT-IDENTIFIER" } where PERSISTENT-IDENTIFIER is a string, then RANDOM.ORG uses historical true randomness derived from the corresponding identifier in a deterministic manner. The identifier must have a length in the [1, 64] range.
The two non-null forms for the pregeneratedRandomization parameter causes RANDOM.ORG to generate the random values based on a pregenerated randomization, i.e., historical true randomness generated by RANDOM.ORG at some point in the past. This makes it possible for the client to replay a given sequence of numbers at a later stage, and also allows multiple parties in different locations to get the same numbers in a predictable fashion. These modes effectively turn RANDOM.ORG into a pseudo-random number generator.

Successful Response

If the numbers were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

random
This object encapsulates the random numbers and associated data. It contains the following properties.
data
An array containing the sequences of numbers requested. The length of the data array will be the same as the length of n from the request, and the order of the sequences is the same as that specified in the request.
completionTime
A string containing the timestamp in ISO 8601 format at which the request was completed.
bitsUsed
An integer containing the number of true random bits used to complete this request.
bitsLeft
An integer containing the (estimated) number of remaining true random bits available to the client.
requestsLeft
An integer containing the (estimated) number of remaining API requests available to the client.
advisoryDelay
An integer containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

Simple clients may not necessarily need all of the properties in the response. A minimal client could use only the random.data and advisoryDelay properties and ignore the rest of the response.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests six numbers, five from the [1,69] range and one from [1,26]. The replacement parameter for both sequences is set to false, which means the numbers will be picked without replacement, i.e., will not contain duplicate values. This makes them suitable for use as a lottery tickets, for example for US Powerball.

{
    "jsonrpc": "2.0",
    "method": "generateIntegerSequences",
    "params": {
        "apiKey": "6b1e65b9-4186-45c2-8981-b77a9842c4f0",
        "n": 2,
        "length": [5, 1],
        "min": [1, 1],
        "max": [69, 26],
        "replacement": [false, false],
        "base": [10, 10]
    },
    "id": 45673
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                [28, 31, 41, 65, 42],
                [14]
            ],
            "completionTime": "2018-01-29 17:34:46Z"
        },
        "bitsUsed": 36,
        "bitsLeft": 833949,
        "requestsLeft": 199598,
        "advisoryDelay": 200
    },
    "id": 45673
}

The random object contains the true random values (in the data array) produced as well as the completion time. Note that the completionTime specifies UTC time zone (‘Zulu time’) by the letter ‘Z’ after the clock time. Through the other fields in the result object, RANDOM.ORG also advises how many true random bits were used to satisfy the request and how many bits and requests are left in the client's quota. It also advises the client that it can go ahead and issue the next request with a minimal delay.

Example 2

The following requests eight uniform randomizations of the [1,52] range. The replacement parameter is set to false, meaning the numbers will be picked without replacement, i.e., duplicates will not occur. This makes them suitable to shuffle decks of cards.

{
    "jsonrpc": "2.0",
    "method": "generateIntegerSequences",
    "params": {
        "apiKey": "6b1e65b9-4186-45c2-8981-b77a9842c4f0",
        "n": 8,
        "length": 52,
        "min": 1,
        "max": 52,
	"replacement": false,
        "base": 10
    },
    "id": 3076
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                [34, 23, 9, 43, 13, 8, 40, 20, 49, 24, 36, 4, 30, 26, 46, 52, 7, 32, 27, 25, 31, 33, 50, 28, 35, 17, 48, 45, 47, 39, 41, 2, 22, 18, 38, 44, 37, 3, 42, 14, 6, 16, 15, 19, 10, 21, 5, 29, 11, 12, 1, 51],
                [22, 29, 50, 1, 44, 46, 45, 4, 51, 17, 41, 8, 24, 34, 7, 52, 37, 14, 20, 5, 3, 40, 35, 32, 42, 25, 47, 30, 10, 12, 38, 36, 26, 27, 31, 18, 23, 6, 28, 49, 9, 16, 13, 2, 21, 15, 48, 39, 33, 19, 43, 11],
                [28, 2, 40, 19, 14, 48, 24, 34, 7, 47, 32, 11, 1, 36, 26, 20, 9, 29, 5, 39, 41, 30, 51, 15, 27, 44, 16, 25, 10, 33, 31, 37, 8, 45, 12, 6, 52, 50, 13, 18, 38, 23, 17, 43, 4, 46, 22, 21, 42, 49, 35, 3],
                [48, 12, 10, 11, 44, 38, 19, 24, 31, 28, 37, 47, 45, 33, 15, 7, 27, 5, 51, 35, 14, 29, 26, 46, 41, 42, 2, 50, 3, 21, 39, 40, 6, 1, 18, 13, 16, 25, 32, 34, 30, 52, 4, 49, 17, 9, 43, 8, 20, 23, 36, 22],
                [4, 30, 17, 26, 41, 5, 28, 21, 40, 23, 13, 10, 6, 24, 2, 25, 36, 15, 42, 32, 16, 35, 29, 50, 11, 44, 45, 22, 14, 7, 8, 1, 48, 33, 19, 51, 31, 27, 43, 52, 37, 34, 46, 47, 38, 12, 9, 20, 39, 49, 3, 18],
                [15, 40, 41, 14, 22, 48, 13, 21, 31, 4, 49, 50, 33, 17, 37, 44, 39, 18, 51, 12, 16, 7, 20, 32, 47, 34, 23, 26, 38, 8, 29, 19, 27, 24, 42, 28, 9, 43, 10, 2, 45, 35, 5, 46, 11, 25, 1, 3, 52, 36, 30, 6],
                [5, 48, 31, 41, 39, 26, 21, 16, 38, 27, 3, 49, 50, 51, 30, 9, 43, 20, 6, 37, 1, 47, 19, 45, 46, 22, 24, 52, 17, 23, 40, 36, 28, 2, 29, 18, 25, 8, 32, 34, 12, 13, 4, 10, 44, 33, 35, 11, 42, 15, 14, 7],
                [18, 45, 12, 4, 41, 40, 23, 2, 49, 26, 20, 27, 42, 37, 38, 13, 33, 48, 36, 21, 47, 24, 44, 32, 28, 15, 19, 31, 7, 14, 39, 1, 5, 9, 16, 3, 52, 46, 10, 43, 22, 35, 17, 30, 11, 29, 34, 51, 25, 8, 6, 50]
            ],
            "completionTime": "2018-01-29 17:37:57Z"
        },
        "bitsUsed": 2368,
        "bitsLeft": 831581,
        "requestsLeft": 199597,
        "advisoryDelay": 320
    },
    "id": 14478
}

The random object contains the true random numbers (in the data array) produced, as well as the completion time.

The remaining fields in the result object indicate how many true random bits were used to satisfy the request as well as how many bits and requests are left in the client's quota. The response also advises the client preferably to delay for a short time before issuing the next request.

Example 3

The following requests one random number from the [1,8] range and three from the [1,6]. Both sequences are generated with replacement. The numbers could be used as a 1d8+3d6 dice roll. In some fields (min and replacement), the caller gives an array of identical values and in another (base) a single value that will apply for all sequences. The two approaches are equivalent, and both are allowed by the API.

{
    "jsonrpc": "2.0",
    "method": "generateIntegerSequences",
    "params": {
        "apiKey": "6b1e65b9-4186-45c2-8981-b77a9842c4f0",
        "n": 2,
        "length": [1, 3],
        "min": [1, 1],
        "max": [8, 6],
        "replacement": [true, true],
        "base": 10
    },
    "id": 4352
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                [7],
                [6, 1, 4]
            ],
            "completionTime": "2018-01-29 17:41:11Z"
        },
        "bitsUsed": 11,
        "bitsLeft": 831537,
        "requestsLeft": 199593,
        "advisoryDelay": 200
    },
    "id": 4352
}

The random object contains the random data generated by the server. The client can sum the two sequences in order to get the total for the 1d8+3d6 dice roll.

The service also advises how many true random bits were used to satisfy the request and how many bits and requests are left in the client's quota.

Example 4

As in Example 1 above, the following requests six numbers, five from the [1,69] range and one from [1,26]. Duplicate values are not allowed. The client also specifies a value of type date for the optional pregeneratedRandomization parameter, meaning that the results will be historical true randomness generated by RANDOM.ORG at some point in the past.

{
    "jsonrpc": "2.0",
    "method": "generateIntegerSequences",
    "params": {
        "apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
        "n": 2,
        "length": [ 5, 1 ],
        "min": 1,
        "max": [ 69, 26 ],
        "replacement": false,
        "base": 10,
        "pregeneratedRandomization": {
            "date": "2010-12-31"
        }
    },
    "id": 12691
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                [ 57, 59, 7, 25, 15 ],
                [ 3 ]
            ],
            "completionTime": "2021-03-25 21:46:29Z"
        },
        "bitsUsed": 0,
        "bitsLeft": 246374,
        "requestsLeft": 977,
        "advisoryDelay": 1940
    },
    "id": 12691
}

The random object contains the random integer sequences returned by the server. By asking for pregenerated random values, any request with the same specifications, i.e. the same values for n, length, min, max, replacement and pregeneratedRandomization, will return the same data. This also applies to the equivalent method in the Signed API, see Example 6 of the generateSignedIntegerSequences method.

The service also advises that no bits were used to satisfy the request, as the values are not generated on-the-fly. It also includes how many bits and requests are left in the client's quota.

Example 5

The only difference between this request and that in Example 4, is that the pregeneratedRandomization parameter is supplied with an id value instead of a date value.

{
    "jsonrpc": "2.0",
    "method": "generateIntegerSequences",
    "params": {
        "apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
        "n": 2,
        "length": [ 5, 1 ],
        "min": 1,
        "max": [ 69, 26 ],
        "replacement": false,
        "base": 10,
        "pregeneratedRandomization": {
            "id": "foobar"
        }
    },
    "id": 12691
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                [ 59, 7, 63, 49, 69 ],
                [ 6 ]
            ],
            "completionTime": "2021-03-25 21:47:52Z"
        },
        "bitsUsed": 0,
        "bitsLeft": 246374,
        "requestsLeft": 976,
        "advisoryDelay": 1930
    },
    "id": 12691
}

As in Example 4, the values in the data object were generated at some point in the past and any time a request with the same parameters is sent, the data returned will be identical.

generateDecimalFractions (method)

This method generates true random decimal fractions from a uniform distribution across the [0,1) interval with a user-defined number of decimal places. Your client must set the method property of its JSON-RPC request object to generateDecimalFractions. The request must also contain an id member, which will be returned in the response.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

apiKey
Your API key, which is used to track the true random bit usage for your client.
n
How many random decimal fractions you need. Must be within the [1, 10000] range.
decimalPlaces
The number of decimal places to use. Must be within the [1, 14] range.

Optional Parameters

The following parameters are optional and can be included in the params object of your JSON-RPC request if you want functionality that is different from the default:

replacement (default value true)
Specifies whether the random numbers should be picked with replacement. The default (true) will cause the numbers to be picked with replacement, i.e., the resulting numbers may contain duplicate values (like a series of dice rolls). If you want the numbers picked to be unique (like raffle tickets drawn from a container), set this value to false.
pregeneratedRandomization (default value null)
Allows the client to specify that the random values should be generated from a pregenerated, historical randomization instead of a one-time on-the-fly randomization. There are three possible cases:
  • If the caller specifies a null value (or does not specify a value), then RANDOM.ORG will generate true randomness specifically for the caller and will discard this randomness immediately after it has been used to generate the random values requested. This is the standard way of using a true random number generator.
  • If the caller specifies an object of the form { "date": "YYYY-MM-DD" } where YYYY-MM-DD is a date in ISO 8601 format, then RANDOM.ORG uses historical true randomness generated on the corresponding date. The date must be in the past or the current date in UTC time.
  • If the caller specifies an object of the form { "id": "PERSISTENT-IDENTIFIER" } where PERSISTENT-IDENTIFIER is a string, then RANDOM.ORG uses historical true randomness derived from the corresponding identifier in a deterministic manner. The identifier must have a length in the [1, 64] range.
The two non-null forms for the pregeneratedRandomization parameter causes RANDOM.ORG to generate the random values based on a pregenerated randomization, i.e., historical true randomness generated by RANDOM.ORG at some point in the past. This makes it possible for the client to replay a given sequence of numbers at a later stage, and also allows multiple parties in different locations to get the same numbers in a predictable fashion. These modes effectively turn RANDOM.ORG into a pseudo-random number generator.

Successful Response

If the numbers were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

random
This object encapsulates the random numbers and associated data. It contains the following properties.
data
An array containing the sequence of numbers requested.
completionTime
A string containing the timestamp in ISO 8601 format at which the request was completed.
bitsUsed
An integer containing the number of true random bits used to complete this request.
bitsLeft
An integer containing the (estimated) number of remaining true random bits available to the client.
requestsLeft
An integer containing the (estimated) number of remaining API requests available to the client.
advisoryDelay
An integer containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

Simple clients may not necessarily need all of the properties in the response. A minimal client could use only the random.data and advisoryDelay properties and ignore the rest of the response.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests ten random decimal fractions with eight decimal places. The replacement parameter is set to true, which means the numbers will be picked with replacement, i.e., can contain duplicate values.

{
    "jsonrpc": "2.0",
    "method": "generateDecimalFractions",
    "params": {
        "apiKey": "6b1e65b9-4186-45c2-8981-b77a9842c4f0",
        "n": 10,
        "decimalPlaces": 8,
        "replacement": true
    },
    "id": 42
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
    	"random": {
            "data": [
                0.0753205, 0.59823072, 0.46109946, 0.28453638, 0.92390558,
                0.53087566, 0.48139983, 0.06829921, 0.1878, 0.10107864
            ],
            "completionTime": "2013-01-25 19:16:42Z"
        },
        "bitsUsed": 266,
        "bitsLeft": 199734,
        "requestsLeft": 8463,
        "advisoryDelay": 0
    },
    "id": 42
}

The random.data array within the result contains the true random numbers produced. Note that while eight decimal places are used, final zeroes are not shown, making some numbers appear to have fewer decimal places. Also note that the completionTime specifies UTC time zone (‘Zulu time’) by the letter ‘Z’ after the clock time. Through the other fields in the result object, RANDOM.ORG also advises how many true random bits were used to satisfy the request (266) and how many bits (199,734) and requests (8,463) are left in the client's quota. It also advises the client that it can go ahead and issue the next request without delay (0 milliseconds).

Example 2

The following requests four decimal fractions with two decimal places. The replacement parameter is set to false, meaning the numbers will be picked without replacement, i.e., duplicates will not occur.

{
    "jsonrpc": "2.0",
    "method": "generateDecimalFractions",
    "params": {
        "apiKey": "6b1e65b9-4186-45c2-8981-b77a9842c4f0",
        "n": 4,
        "decimalPlaces": 2,
	"replacement": false
    },
    "id": 3076
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
	        0.8, 0.94, 0.72, 0.2
	    ],
            "completionTime": "2013-01-25 19:21:15Z",
        },
	"bitsUsed": 27,
	"bitsLeft": 199973,
        "requestsLeft": 9999,
	"advisoryDelay": 2000
    },
    "id": 3076
}

The random object contains the true random numbers (in the data array) produced, as well as the completion time. Note that, as in example 1, final zeroes are not shown.

The remaining fields in the result object indicate how many true random bits were used to satisfy the request as well as how many bits and requests are left in the client's quota. The response also advises the client preferably to delay at least two seconds before issuing a new request.

Example 3

The following requests 1,000 decimal fractions with 14 decimal places. No replacement parameter is given, which means the service will use the default value of true and the numbers will be picked with replacement, i.e., duplicates are allowed.

{
    "jsonrpc": "2.0",
    "method": "generateDecimalFractions",
    "params": {
        "apiKey": "6b1e65b9-4186-45c2-8981-b77a9842c4f0",
        "n": 1000,
        "decimalPlaces": 14
    },
    "id": 4352
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                0.85890418365935, 0.86883621972704,
                0.42126293542103, 0.496355715084,
                ...
            ],
            "completionTime": "2013-01-25 19:24:33Z"
        },
        "bitsUsed": 66439,
        "bitsLeft": 133561,
        "requestsLeft": 4782,
        "advisoryDelay": 0
    },
    "id": 4352
}

The random object contains the random data generated by the server. For brevity, only the first four values are shown in the response. As in the previous examples, final zeroes are not shown.

The service also advises how many true random bits were used to satisfy the request and how many bits and requests are left in the client's quota. The service advises that the client can issue the next request without delay (0 milliseconds).

Example 4

The following requests three decimal fractions with an accuracy of three decimal places. Duplicate values are allowed as the replacement property is set to true. The client also specifies a value of type date for the optional pregeneratedRandomization parameter, meaning that the results will be historical true randomness generated by RANDOM.ORG at some point in the past.

{
    "jsonrpc": "2.0",
    "method": "generateDecimalFractions",
    "params": {
        "apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
        "n": 3,
        "decimalPlaces": 3,
        "replacement": true,
        "pregeneratedRandomization": {
            "date": "2010-12-31"
        }
    },
    "id": 29055
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                0.455, 0.954, 0.228
            ],
            "completionTime": "2021-03-09 16:19:18Z"
        },
        "bitsUsed": 0,
        "bitsLeft": 249929,
        "requestsLeft": 984,
        "advisoryDelay": 1620
    },
    "id": 29055
}

The random object contains the random decimal fractions returned by the server. By asking for pregenerated random values, any request with the same specifications, i.e. the same values for n, decimalPlaces, replacement and pregeneratedRandomization, will return the same data. This also applies to the equivalent method in the Signed API, see Example 4 of the generateSignedDecimalFractions method.

The service also advises that no bits were used to satisfy the request, as the values are not generated on-the-fly. It also includes how many bits and requests are left in the client's quota.

Example 5

The parameters used in this request are identical to those used in Example 4, differing only in that the pregeneratedRandomization contains an id value, instead of a date value.

{
    "jsonrpc": "2.0",
    "method": "generateDecimalFractions",
    "params": {
        "apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
        "n": 3,
        "decimalPlaces": 3,
        "replacement": true,
        "pregeneratedRandomization": {
            "id": "foobar"
        }
    },
    "id": 29055
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                0.464, 0.414, 0.489
            ],
            "completionTime": "2021-03-09 16:20:12Z"
        },
        "bitsUsed": 0,
        "bitsLeft": 249929,
        "requestsLeft": 981,
        "advisoryDelay": 1870
    },
    "id": 29055
}

As in Example 4, the values in the data object were generated at some point in the past and any time a request with the same parameters is made, the data returned will be identical.

generateGaussians (method)

This method generates true random numbers from a Gaussian distribution (also known as a normal distribution). The method uses a Box-Muller Transform to generate the Gaussian distribution from uniformly distributed numbers. Your client must set the method property of its JSON-RPC request object to generateGaussians. The request must also contain an id member, which will be returned in the response.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

apiKey
Your API key, which is used to track the true random bit usage for your client.
n
How many random numbers you need. Must be within the [1, 10000] range.
mean
The distribution's mean. Must be within the [-1000000, 1000000] range.
standardDeviation
The distribution's standard deviation. Must be within the [-1000000, 1000000] range.
significantDigits
The number of significant digits to use. Must be within the [2, 14] range.

Optional Parameters

The following parameter is optional and can be included in the params object of your JSON-RPC request if you want functionality that is different from the default:

pregeneratedRandomization (default value null)
Allows the client to specify that the random values should be generated from a pregenerated, historical randomization instead of a one-time on-the-fly randomization. There are three possible cases:
  • If the caller specifies a null value (or does not specify a value), then RANDOM.ORG will generate true randomness specifically for the caller and will discard this randomness immediately after it has been used to generate the random values requested. This is the standard way of using a true random number generator.
  • If the caller specifies an object of the form { "date": "YYYY-MM-DD" } where YYYY-MM-DD is a date in ISO 8601 format, then RANDOM.ORG uses historical true randomness generated on the corresponding date. The date must be in the past or the current date in UTC time.
  • If the caller specifies an object of the form { "id": "PERSISTENT-IDENTIFIER" } where PERSISTENT-IDENTIFIER is a string, then RANDOM.ORG uses historical true randomness derived from the corresponding identifier in a deterministic manner. The identifier must have a length in the [1, 64] range.
The two non-null forms for the pregeneratedRandomization parameter causes RANDOM.ORG to generate the random values based on a pregenerated randomization, i.e., historical true randomness generated by RANDOM.ORG at some point in the past. This makes it possible for the client to replay a given sequence of numbers at a later stage, and also allows multiple parties in different locations to get the same numbers in a predictable fashion. These modes effectively turn RANDOM.ORG into a pseudo-random number generator.

It should also be noted that Gaussians are always picked with replacement.

Successful Response

If the numbers were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

random
This object encapsulates the random numbers and associated data. It contains the following properties.
data
An array containing the sequence of numbers requested.
completionTime
A string containing the timestamp in ISO 8601 format at which the request was completed.
bitsUsed
An integer containing the number of true random bits used to complete this request.
bitsLeft
An integer containing the (estimated) number of remaining true random bits available to the client.
requestsLeft
An integer containing the (estimated) number of remaining API requests available to the client.
advisoryDelay
An integer containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

Simple clients may not necessarily need all of the properties in the response. A minimal client could use only the random.data and advisoryDelay properties and ignore the rest of the response.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests four random numbers from a Gaussian distribution with mean 0.0 and standard deviation 1.0, accurate up to eight significant digits.

{
    "jsonrpc": "2.0",
    "method": "generateGaussians",
    "params": {
        "apiKey": "6b1e65b9-4186-45c2-8981-b77a9842c4f0",
        "n": 4,
        "mean": 0.0,
        "standardDeviation": 1.0,
        "significantDigits": 8
    },
    "id": 42
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
    	"random": {
            "data": [
                0.4025041, -1.4918831, 0.64733849, 0.5222242
            ],
            "completionTime": "2013-01-25 19:16:42Z"
        },
        "bitsUsed": 106,
        "bitsLeft": 199894,
        "requestsLeft": 5442,
        "advisoryDelay": 0
    },
    "id": 42
}

The random.data array within the result contains the true random numbers produced. Note that while eight significant digits are used, final zeroes after the decimal points are not shown, making some numbers appear to have fewer significant digits. Also note that the completionTime specifies UTC time zone (‘Zulu time’) by the letter ‘Z’ after the clock time. Through the other fields in the result object, RANDOM.ORG also advises how many true random bits were used to satisfy the request (106) and how many bits (199,894) and requests (5,442) are left in the client's quota. It also advises the client that it can go ahead and issue the next request without delay (0 milliseconds).

Example 2

The following requests 2,000 random numbers from a Gaussian distribution with mean of 1,100 and standard deviation of 100, accurate up to four significant digits. This could be used to simulate the lifetimes of lightbulbs (measured in hours), as in example 10.3.5 of Handbook of Statistical Distributions with Applications.

{
    "jsonrpc": "2.0",
    "method": "generateGaussians",
    "params": {
        "apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
        "n": 2000,
        "mean": 1100,
        "standardDeviation": 100,
        "significantDigits": 4
    },
    "id": 374
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                1130, 973.3, 1215, 1012, 
                1007, 1157, 1079, 1183, 
                ...
	    ],
            "completionTime": "2021-03-10 12:59:09Z"
        },
        "bitsUsed": 26575,
        "bitsLeft": 196850,
        "requestsLeft": 973,
        "advisoryDelay": 2270
    },
    "id": 374
}

The random object contains the true random numbers (in the data array) produced, as well as the completion time. To save space, only the first eight values returned are shown above.

The remaining fields in the result object indicate how many true random bits were used to satisfy the request as well as how many bits and requests are left in the client's quota. The response also advises the client preferably to delay at least two seconds before issuing a new request.

Example 3

The following requests 100 random numbers from a Gaussian distribution with mean 140 and standard deviation 10, accurate to six significant digits.

{
    "jsonrpc": "2.0",
    "method": "generateGaussians",
    "params": {
        "apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
        "n": 100,
        "mean": 140,
        "standardDeviation": 10,
        "significantDigits": 6
    },
    "id": 374
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                142.903, 134.071, 150.727, 133.647,
                129.428, 145.847, 135.304, 139.781,
                ...
            ],
            "completionTime": "2021-03-10 13:08:47Z"
        },
        "bitsUsed": 1993,
        "bitsLeft": 194857,
        "requestsLeft": 972,
        "advisoryDelay": 2400
    },
    "id": 374
}

The random object contains the random data generated by the server. For brevity, only the first eight values are shown in the response. As in example 1, final zeroes after the decimal point are not shown.

The service also advises how many true random bits were used to satisfy the request and how many are left in the client's quota.

Example 4

The following requests five random numbers from a Gaussian distribution with mean 50 and standard deviation 10, where each value should be returned with up to four significant digits. The client also specifies a value of type date for pregeneratedRandomization, meaning that the results will be historical true randomness generated by RANDOM.ORG at some point in the past.

{
    "jsonrpc": "2.0",
    "method": "generateGaussians",
    "params": {
        "apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
        "n": 5,
        "mean": 50,
        "standardDeviation": 10,
        "significantDigits": 4,
        "pregeneratedRandomization": {
            "date": "2010-12-31"
        }
    },
    "id": 12691
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                56.98,
                53.79,
                41.23,
                41.17,
                41.69
            ],
            "completionTime": "2021-03-25 22:09:01Z"
        },
        "bitsUsed": 0,
        "bitsLeft": 246374,
        "requestsLeft": 974,
        "advisoryDelay": 2270
    },
    "id": 12691
}

The random object contains the random data returned by the server. By asking for pregenerated random values, any request with the same specifications, i.e. the same values for n, mean, standardDeviation, significantDigits and pregeneratedRandomization, will return the same data. This also applies to the equivalent method in the Signed API, see Example 5 of the generateSignedGaussians method.

The service also advises that no bits were used to satisfy the request, as the values are not generated on the spot. It also includes how many bits and requests are left in the client's quota.

Example 5

Like in Example 4 above, the following requests five random numbers from a Gaussian distribution with mean 50 and standard deviation 10, where each value should be returned with up to four significant digits. This time, however, an id value is added for the optional pregeneratedRandomization parameter.

{
    "jsonrpc": "2.0",
    "method": "generateGaussians",
    "params": {
        "apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
        "n": 5,
        "mean": 50,
        "standardDeviation": 10,
        "significantDigits": 4,
        "pregeneratedRandomization": {
            "id": "foobar"
        }
    },
    "id": 12691
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                51.45, 42.43, 46.58, 59.34, 36.39
            ],
            "completionTime": "2021-03-25 22:11:50Z"
        },
        "bitsUsed": 0,
        "bitsLeft": 246374,
        "requestsLeft": 972,
        "advisoryDelay": 2230
    },
    "id": 12691
}

As in Example 4, the values returned were generated at some point in the the past and any time a request with the same parameters is sent, the data returned will be identical.

generateStrings (method)

This method generates true random strings. Your client must set the method property of its JSON-RPC request object to generateStrings. The request must also contain an id member, which will be returned in the response.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

apiKey
Your API key, which is used to track the true random bit usage for your client.
n
How many random strings you need. Must be within the [1, 10000] range.
length
The length of each string. Must be within the [1, 32] range. All strings will be of the same length.
characters
A string that contains the set of characters that are allowed to occur in the random strings. The maximum number of characters is 128.

Optional Parameters

The following parameters are optional and can be included in the params object of your JSON-RPC request if you want functionality that is different from the default:

replacement (default value true)
Specifies whether the random strings should be picked with replacement. The default (true) will cause the strings to be picked with replacement, i.e., the resulting list of strings may contain duplicates (like a series of dice rolls). If you want the strings to be unique (like raffle tickets drawn from a container), set this value to false.
pregeneratedRandomization (default value null)
Allows the client to specify that the random values should be generated from a pregenerated, historical randomization instead of a one-time on-the-fly randomization. There are three possible cases:
  • If the caller specifies a null value (or does not specify a value), then RANDOM.ORG will generate true randomness specifically for the caller and will discard this randomness immediately after it has been used to generate the random values requested. This is the standard way of using a true random number generator.
  • If the caller specifies an object of the form { "date": "YYYY-MM-DD" } where YYYY-MM-DD is a date in ISO 8601 format, then RANDOM.ORG uses historical true randomness generated on the corresponding date. The date must be in the past or the current date in UTC time.
  • If the caller specifies an object of the form { "id": "PERSISTENT-IDENTIFIER" } where PERSISTENT-IDENTIFIER is a string, then RANDOM.ORG uses historical true randomness derived from the corresponding identifier in a deterministic manner. The identifier must have a length in the [1, 64] range.
The two non-null forms for the pregeneratedRandomization parameter causes RANDOM.ORG to generate the random values based on a pregenerated randomization, i.e., historical true randomness generated by RANDOM.ORG at some point in the past. This makes it possible for the client to replay a given sequence of numbers at a later stage, and also allows multiple parties in different locations to get the same numbers in a predictable fashion. These modes effectively turn RANDOM.ORG into a pseudo-random number generator.

Successful Response

If the strings were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

random
This object encapsulates the random numbers and associated data. It contains the following properties.
data
An array containing the strings requested.
completionTime
A string containing the timestamp in ISO 8601 format at which the request was completed.
bitsUsed
An integer containing the number of true random bits used to complete this request.
bitsLeft
An integer containing the (estimated) number of remaining true random bits available to the client.
requestsLeft
An integer containing the (estimated) number of remaining API requests available to the client.
advisoryDelay
An integer containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

Simple clients may not necessarily need all of the properties in the response. A minimal client could use only the random.data and advisoryDelay properties and ignore the rest of the response.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests eight strings of ten characters in length. The request specifies that only lowercase characters from the English alphabet are allowed. The replacement parameter is set to true, which means the strings will be picked with replacement, i.e., the response can contain duplicate strings.

{
    "jsonrpc": "2.0",
    "method": "generateStrings",
    "params": {
        "apiKey": "6b1e65b9-4186-45c2-8981-b77a9842c4f0",
        "n": 8,
        "length": 10,
        "characters": "abcdefghijklmnopqrstuvwxyz",
        "replacement": true
    },
    "id": 42
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
    	"random": {
            "data": [
                "grvhglvahj", "hjrmosjwed", "nivjyqptyy", "lhogeshsmi",
                "syilbgsytb", "birvcmgdrz", "wgclyynpcq", "eujwnhgonh"
            ],
            "completionTime": "2011-10-10 13:19:12Z"
        },
        "bitsUsed": 376,
        "bitsLeft": 199624,
        "requestsLeft": 9999,
        "advisoryDelay": 0
    },
    "id": 42
}

The random.data array within the result contains the true random strings produced. Note that the completionTime specifies UTC time zone (‘Zulu time’) by the letter ‘Z’ after the clock time. Through the other fields in the result object, RANDOM.ORG also advises how many true random bits were used to satisfy the request (376) and how many bits (199,624) and requests (9,999) are left in the client's quota. It also advises the client that it can go ahead and issue the next request without delay (0 milliseconds).

Example 2

The following requests ten strings of length eight. Allowable characters are all letters from the English alphabet (uppercase and lowercase letters are treated as separate characters) as well as decimal digits and a few special characters. The replacement parameter is set to false, meaning that strings will be generated without replacement, such that there will be no duplicates amongst them.

{
    "jsonrpc": "2.0",
    "method": "generateIntegers",
    "params": {
        "apiKey": "6b1e65b9-4186-45c2-8981-b77a9842c4f0",
        "n": 10,
        "length": 8,
        "characters": "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!#$%&*",
	"replacement": false
    },
    "id": 3076
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                "eXYDA6dj", "Pmx&aaF7", "E6%DuTar", "o!Bm1wvc", "lbigGD#U",
                "OdYwAJDR", "U#*jQoO!", "jggRa!B%", "uwPas!e9", "GzIJEomT"
	    ],
            "completionTime": "2011-10-10 13:19:12Z",
        },
	"bitsUsed": 487,
	"bitsLeft": 199513,
        "requestsLeft": 1274,
	"advisoryDelay": 2000
    },
    "id": 3076
}

The random object contains the true random strings (in the data array) produced, as well as the completion time.

The remaining fields in the result object indicate how many true random bits were used to satisfy the request as well as how many bits and requests are left in the client's quota. The response also advises the client preferably to delay at least two seconds before issuing a new request.

Example 3

The following requests sixteen strings of length four. All characters from the Danish and Norwegian alphabet are allowed. The replacement parameter is not given, which means the service will use the default value of true and the strings will be picked with replacement, i.e., duplicates are allowed.

{
    "jsonrpc": "2.0",
    "method": "generateStrings",
    "params": {
        "apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
        "n": 16,
        "length": 4,
        "characters": "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
    },
    "id": 15443
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                "kbQ", "Bhgx", "jNAL", "ceZV",
                "xGq", "trA", "gBA", "bRCg",
                "MpU", "jJo", "zAZd", "uhdX",
                "siz", "bfdo", "zsWA", "mAAE"
            ],
            "completionTime": "2021-03-18 13:32:52Z"
        },
        "bitsUsed": 375,
        "bitsLeft": 248405,
        "requestsLeft": 996,
        "advisoryDelay": 2360
    },
    "id": 15443
}

The random object contains the random data generated by the server. The service also advises how many true random bits were used to satisfy the request and how many bits and requests are left in the client's quota.

Example 4

The following requests four strings each containing four lowercase characters from the English alphabet. Duplicate strings are not allowed, as the replacement parameter is set to false. Additionally, the pregeneratedRandomization property is given a date value, meaning that the results will be historical true randomness generated by RANDOM.ORG at some point in the past.

{
    "jsonrpc": "2.0",
    "method": "generateStrings",
    "params": {
        "apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
        "n": 4,
        "length": 4,
        "characters": "abcdefghijklmnopqrstuvwxyz",
        "replacement": false,
        "pregeneratedRandomization": {
            "date": "2010-12-31"
        }
    },
    "id": 12691
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                "nhij", "dikv", "olsn", "koxq"
            ],
            "completionTime": "2021-03-25 22:19:49Z"
        },
        "bitsUsed": 0,
        "bitsLeft": 246374,
        "requestsLeft": 971,
        "advisoryDelay": 3150
    },
    "id": 12691
}

The data object contains the random strings returned by the server. By asking for pregenerated random values, any request with the same specifications, i.e. the same values for n, length, characters, replacement and pregeneratedRandomization, will return the same data. This also applies to the equivalent method in the Signed API, see Example 6 of the generateSignedStrings method.

The service also advises that no bits were used to satisfy the request, as the values are not generated on-the-fly. It also includes how many bits and requests are left in the client's quota.

Example 5

As in Example 4 above, the following requests four strings each containing four lowercase characters from the English alphabet and duplicates are not allowed. This time, however, the pregeneratedRandomization parameter contains an id value.

{
    "jsonrpc": "2.0",
    "method": "generateStrings",
    "params": {
        "apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
        "n": 4,
        "length": 4,
        "characters": "abcdefghijklmnopqrstuvwxyz",
        "replacement": false,
        "pregeneratedRandomization": {
            "id": "foobar"
        }
    },
    "id": 12691
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                "nntf", "hdjo", "ldpl", "qxan"
            ],
            "completionTime": "2021-03-25 22:22:23Z"
        },
        "bitsUsed": 0,
        "bitsLeft": 246374,
        "requestsLeft": 970,
        "advisoryDelay": 2200
    },
    "id": 12691
}

As in Example 4, any time a request with the same parameters is made, the data returned will be identical.

generateUUIDs (method)

This method generates version 4 true random Universally Unique IDentifiers (UUIDs) in accordance with section 4.4 of RFC 4122. Your client must set the method property of its JSON-RPC request object to generateUUIDs. The request must also contain an id member, which will be returned in the response.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

apiKey
Your API key, which is used to track the true random bit usage for your client.
n
How many random UUIDs you need. Must be within the [1, 1000] range.

Optional Parameters

The following parameter is optional and can be included in the params object of your JSON-RPC request if you want functionality that is different from the default:

pregeneratedRandomization (default value null)
Allows the client to specify that the random values should be generated from a pregenerated, historical randomization instead of a one-time on-the-fly randomization. There are three possible cases:
  • If the caller specifies a null value (or does not specify a value), then RANDOM.ORG will generate true randomness specifically for the caller and will discard this randomness immediately after it has been used to generate the random values requested. This is the standard way of using a true random number generator.
  • If the caller specifies an object of the form { "date": "YYYY-MM-DD" } where YYYY-MM-DD is a date in ISO 8601 format, then RANDOM.ORG uses historical true randomness generated on the corresponding date. The date must be in the past or the current date in UTC time.
  • If the caller specifies an object of the form { "id": "PERSISTENT-IDENTIFIER" } where PERSISTENT-IDENTIFIER is a string, then RANDOM.ORG uses historical true randomness derived from the corresponding identifier in a deterministic manner. The identifier must have a length in the [1, 64] range.
The two non-null forms for the pregeneratedRandomization parameter causes RANDOM.ORG to generate the random values based on a pregenerated randomization, i.e., historical true randomness generated by RANDOM.ORG at some point in the past. This makes it possible for the client to replay a given sequence of numbers at a later stage, and also allows multiple parties in different locations to get the same numbers in a predictable fashion. These modes effectively turn RANDOM.ORG into a pseudo-random number generator.

Successful Response

If the UUIDs were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

random
This object encapsulates the random UUIDs and associated data. It contains the following properties.
data
An array containing the sequence of UUIDs requested, represented as strings.
completionTime
A string containing the timestamp in ISO 8601 format at which the request was completed.
bitsUsed
An integer containing the number of true random bits used to complete this request.
bitsLeft
An integer containing the (estimated) number of remaining true random bits available to the client.
requestsLeft
An integer containing the (estimated) number of remaining API requests available to the client.
advisoryDelay
An integer containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

Simple clients may not necessarily need all of the properties in the response. A minimal client could use only the random.data and advisoryDelay properties and ignore the rest of the response.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests a single UUID.

{
    "jsonrpc": "2.0",
    "method": "generateUUIDs",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 1
    },
    "id": 15998
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                "47849fd4-b790-492e-8b93-c601a91b662d"
            ],
            "completionTime": "2013-02-11 16:42:07Z"
        },
        "bitsUsed": 122,
        "bitsLeft": 998532,
        "requestsLeft": 199996,
        "advisoryDelay": 1000
    },
    "id": 15998
}

The random.data array within the result contains the UUID produced. Note that the completionTime specifies UTC time zone (‘Zulu time’) by the letter ‘Z’ after the clock time. Through the other fields in the result object, RANDOM.ORG also advises how many true random bits were used to satisfy the request (122) and how many bits (998,532) and requests (199,996) are left in the client's quota. It also advises the client that it can go ahead and issue the next request after a short delay (1 second).

Example 2

The following requests eight UUIDs.

{
    "jsonrpc": "2.0",
    "method": "generateUUIDs",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000",
        "n": 8
    },
    "id": 17338
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                "04719bc6-1316-4ce8-bf08-543c66d886de",
                "12d4ebe3-a6a8-48b3-bdc7-fae11ee7ec91",
                "33ea274c-7921-4a09-bd26-cbdd189a2a8a",
                "b16ddfac-e63a-431c-96f8-6b9c4d39ca0f",
                "41d780b7-4274-40f6-8e9f-777e957c8745",
                "b4f476fb-5025-49a5-9106-7ff335d15bf0",
                "ae520ab6-b859-4aa2-9530-f93f1fd90d61",
                "6e57aa20-e4b2-42e2-bb75-6a67c01b2460"
            ],
            "completionTime": "2013-02-11 16:44:41Z"
        },
        "bitsUsed": 976,
        "bitsLeft": 997556,
        "requestsLeft": 199995,
        "advisoryDelay": 0
    },
    "id": 17338
}

The random object contains the true random UUIDs (in the data array) produced, as well as the completion time.

The remaining fields in the result object indicate how many true random bits were used to satisfy the request as well as how many bits and requests are left in the client's quota. The response also advises the client can go ahead and issue the next request without delay.

Example 3

The following requests three UUIDs. By providing a date value for the optional pregeneratedRandomization parameter, the UUIDs returned from this request will have been generated by RANDOM.ORG at some point in the past.

{
    "jsonrpc": "2.0",
    "method": "generateUUIDs",
    "params": {
        "apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
        "n": 3,
        "pregeneratedRandomization": {
            "date": "2010-12-31"
        }
    },
    "id": 12691
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                "71fba390-c5f0-4df0-8675-abdb51fe61bf",
                "932ffbef-64fb-4efd-bd96-2af5de10a733",
                "468fef5f-c14d-467a-92a8-8b54f8d5e3c4"
            ],
            "completionTime": "2021-03-25 22:27:57Z"
        },
        "bitsUsed": 0,
        "bitsLeft": 246374,
        "requestsLeft": 969,
        "advisoryDelay": 1970
    },
    "id": 12691
}

The data object contains the random UUIDs returned by the server. By asking for pregenerated random values, any request with the same specifications, i.e. the same values for n and pregeneratedRandomization will return the same data. This also applies to the equivalent method in the Signed API, see Example 4 of the generateSignedUUIDs method.

The service also advises that no bits were used to satisfy the request, as the values are not generated on-the-fly. It also includes how many bits and requests are left in the client's quota.

Example 4

Like Example 3 above, the following request three UUIDs. The only difference is that this request provides an id value instead of a date value for the optional pregeneratedRandomization parameter.

{
    "jsonrpc": "2.0",
    "method": "generateUUIDs",
    "params": {
        "apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
        "n": 3,
        "pregeneratedRandomization": {
            "id": "foobar"
        }
    },
    "id": 12691
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                "7419e7a5-f3f3-402f-8b49-0e8d8d825735",
                "704cca8d-a540-4c44-9ec7-07a343727641",
                "e9557ad7-ec40-4ebd-b866-fe4be31bd830"
            ],
            "completionTime": "2021-03-25 22:30:20Z"
        },
        "bitsUsed": 0,
        "bitsLeft": 246374,
        "requestsLeft": 968,
        "advisoryDelay": 1720
    },
    "id": 12691
}

As in Example 3, any time a request with the same parameters is made, the data returned will be identical.

generateBlobs (method)

This method generates Binary Large OBjects (BLOBs) containing true random data. Your client must set the method property of its JSON-RPC request object to generateBlobs. The request must also contain an id member, which will be returned in the response.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

apiKey
Your API key, which is used to track the true random bit usage for your client.
n
How many random blobs you need. Must be within the [1, 100] range.
size
The size of each blob, measured in bits. Must be within the [1, 1048576] range and must be divisible by 8.

The total size of all blobs requested must not exceed 1,048,576 bits (128 KiB).

Optional Parameters

The following parameters are optional and can be included in the params object of your JSON-RPC request if you want functionality that is different from the default:

format (default value base64)
Specifies the format in which the blobs will be returned. Values allowed are base64 and hex.
pregeneratedRandomization (default value null)
Allows the client to specify that the random values should be generated from a pregenerated, historical randomization instead of a one-time on-the-fly randomization. There are three possible cases:
  • If the caller specifies a null value (or does not specify a value), then RANDOM.ORG will generate true randomness specifically for the caller and will discard this randomness immediately after it has been used to generate the random values requested. This is the standard way of using a true random number generator.
  • If the caller specifies an object of the form { "date": "YYYY-MM-DD" } where YYYY-MM-DD is a date in ISO 8601 format, then RANDOM.ORG uses historical true randomness generated on the corresponding date. The date must be in the past or the current date in UTC time.
  • If the caller specifies an object of the form { "id": "PERSISTENT-IDENTIFIER" } where PERSISTENT-IDENTIFIER is a string, then RANDOM.ORG uses historical true randomness derived from the corresponding identifier in a deterministic manner. The identifier must have a length in the [1, 64] range.
The two non-null forms for the pregeneratedRandomization parameter causes RANDOM.ORG to generate the random values based on a pregenerated randomization, i.e., historical true randomness generated by RANDOM.ORG at some point in the past. This makes it possible for the client to replay a given sequence of numbers at a later stage, and also allows multiple parties in different locations to get the same numbers in a predictable fashion. These modes effectively turn RANDOM.ORG into a pseudo-random number generator.

Successful Response

If the blobs were generated successfully, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

random
This object encapsulates the random blobs and associated data. It contains the following properties.
data
An array containing the blobs requested. Each blob will be formatted as a string encoded in the format specified in the request.
completionTime
A string containing the timestamp in ISO 8601 format at which the request was completed.
bitsUsed
An integer containing the number of true random bits used to complete this request.
bitsLeft
An integer containing the (estimated) number of remaining true random bits available to the client.
requestsLeft
An integer containing the (estimated) number of remaining API requests available to the client.
advisoryDelay
An integer containing the recommended number of milliseconds that the client should delay before issuing another request.

For a successful response, the error property is absent.

Simple clients may not necessarily need all of the properties in the response. A minimal client could use only the random.data and advisoryDelay properties and ignore the rest of the response.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests a single blob containing 1,024 true random bits (128 bytes), for example to seed a pseudo-random number generator.

{
    "jsonrpc": "2.0",
    "method": "generateBlobs",
    "params": {
        "apiKey": "6b1e65b9-4186-45c2-8981-b77a9842c4f0",
        "n": 1,
        "size": 1024
    },
    "id": 42
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
    	"random": {
            "data": [
                "aNB8L3hY3kWYXgTUQxGVB5njMe2e0l3LCjkDCN1u12kPBPrsDcWMLTCDlB60kRhAlGbvPqoBHhjg6ZbOM4LfD3T9/wfhvnqJ1FTraamW2IAUnyKxz27fgcPw1So6ToIBL0fGQLpMQDF2/nEmNmFRNa9s6sQ+400IGA+ZeaOAgjE="
            ],
            "completionTime": "2011-10-10 13:19:12Z"
        },
        "bitsUsed": 1024,
        "bitsLeft": 198976,
        "requestsLeft": 9999,
        "advisoryDelay": 0
    },
    "id": 42
}

The random.data array within the result contains the random blob produced. Since no value was specified for the format parameter, the blob is encoded with the default base64-encoding. Note that the completionTime specifies UTC time zone (‘Zulu time’) by the letter ‘Z’ after the clock time. Through the other fields in the result object, RANDOM.ORG also advises how many true random bits were used to satisfy the request (1,024) and how many bits (198,976) and requests (9,999) are left in the client's quota. It also advises the client that it can go ahead and issue the next request without delay (0 milliseconds).

Example 2

The following requests four blobs, each containing 6,144 true random bits (768 bytes) encoded as hex strings.

{
    "jsonrpc": "2.0",
    "method": "generateBlobs",
    "params": {
        "apiKey": "6b1e65b9-4186-45c2-8981-b77a9842c4f0",
        "n": 4,
        "size": 6144,
        "format": "hex"
    },
    "id": 42
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
    	"random": {
            "data": [
                "3c9290ab56e2134b054ddc32fd2ccda09329ba13bc708a97e2bb773c02d45aecb9e031f17d7aadbdee377bdbdd32a42008bdee1ac715db82421da704cb2a9a64871be744404dd3ec7f6f396bd294134b7732078a4158dc79f6814f58813544b419e6dfb626977d14cfa5b4e3f335f26e266a84fc2dd84aa8dbd3dddc50626c10a56fb18831e9d886dac5eb775f560b70c265df981b7c63f99b26f86679fae0896845cfdc529ea51cd55c43adcf4d9ab238b0cbdfa879124cb2d5fc2aca9e313eaba745219d964160ce6f24464f8f0ef47446b700f79101714d009aba41c695ac4901dfdb554672b0718d87a8317931ecbd87164889784e2cb052ae792f1d607b2ed169ce0b9fa71ecbf369130bae3e0fe7ba7c7049ae105eb4efb7038645be4c2b9e8f43669aefc4b8e265ebbc350eee3c935c27f0ab46676e858309a4f49c480c62462829dbb5ea351d26b99cd7ca3c89d944a7132505ddc794e45c4828377a8eb5b877a3a1bee48991447c2dcf8d04765ed144e0fabd771f49a11204e82772bdbc0d61bf7935b2b757abb8091beefea165e458a3af108472d0650106f715c77e05cf353b28670f878c620fa5bc7707b745aacad29ac5cf28ff07bfbf0600bce4f41c26569d555c1bc606e678c34bcfa55b3ad3f503a2e95aa560abbe0939bee660cb49260c7f7811f820c0b406f476a7b13f3627bbdb898a83044da28be830d978ac5fdc69f48fcb1db21f525e020940c4e407a83f4ff736577345d9564b48e4f32e827a746cb0818e91c97e9f24d852265ecaedb367321cad60ac170f8f5cc388cd63a77881ade844e08d9e74d457842d64d2e1b47ffdfd784b3a0c2a70a325fe14a2966fa3ccabef5ce651f5b3fd99e2c6ecfb7ef6d14f2a508c515e29cc12f9c47a4a9b3503a27bddf8b1da8373102e13ff0a59ae42a9e0e258adc55886140c1492426dd22b9e2b78d46075b0c14154d6a05b4ecb7939c92409e1134fa7f943bbe64845541d9464414e3bc8f3612d3adabec7f405e7e8b7a2afb9a981b608775225e3abe3e22009ecf5dc254cbf416100ebf417f9004a991f5d966fbdb4",
                "6dcf36d75f1b627abb95146515450453cd5383df876146574e0aa31f5f65418064c00561bfe0dae7d22262145f400bb12e79b96f591c62ff99b6ff429c7f2c18851386604969775d8d4c864665d812a5a7eb6c3ded1048611672900050f0ec7df0abd583258b85c0abcc191e8f712593b17e044b8522e444dac88f59ea52acaab0f41a7237bf49aef39986f620bf8a033d3ebadb481c8c1b7de4d310933da67c2e4414118b8730ca99dbf232602a2fa38b29ebe0f560c16a8d7fe98f8a7ed86e6b5a21b9e4e804474f2d1c7c23b0d2a8edd36601757c339114a3e447860323a6de139648d4ede17d45d67fcb1194b888da90daf4faebad21bf7f1a3f5ed3dafc813a6c0795d2a12a121c55ca91358bb68ef1f2eaa1445fc9486e1e249874078b67b486c78d96c9d6853594f51de17dca2eb6615ecb9190eb6072f4b56de8209b75053894981339223e03c9fd3655b9af3113c08819057060c59456da9b374a671533d9a1fd0fad17fc9ebb90a0813d6c17728fd1d100a913fe0934c252d2e8bcecff411b2eeb2dcecd8d639c646715dae3aa0344387d5f0022d72309dd504867f8fd1b12afa077c0bf12719b336a57ea369a9dbc1505dbdcd2457ad48ff14ed871a64ae409782dd6d1a526e5bb650247c661a606cfc68438fe09939efea1992d96dd2640881c79397bc4d65cfc91e4adb9f57cd6175f9f1f3b102aa1f5a4bee0c7e75264089d0f112ac847808908c38eee391e7d0ea57cbd12282c6ec1acd660f244955888e1403a3220310e78da4bd7e1285e83c69a8b7eb79a67e9b03ac5ae95fabd88345315cd76467040f0385c8432614cc89b2a8d7852549f3ccc5b8983a38efe11041d493bd395e5d15e3d35c409e7f2a9fd63d70b0f0baf01f0ccb7e81a621ab1fd2df3e0459e5321655a2eafeacea1179f41add34ad43bbc2a95318eda137f9f02e751672a8f1c040c108d90aa7f39d20c33ae39774b75ffdde5ce27cbc07090e38af2ac3277ee5ba080f0d9bfb5adbef7cf57253105b83554fcfc266d6fe540fffa7da60ec688ff2892861edc05e427e9eee26ef72406ba5eccd299",
                "f75eb6eb3e2aff30104aac1ffd5cffbc322889770963f3dff7ad2261b8f43bf5e1a029df958627cbc060dc850926b5e060807c8d9ba00d34d61025c11c171bb71ab2f1c28fac2f019da1a2844de78d7b6f5f91b4f188bf1389097839ab559f6f1baff54d3afebd50485fd8de4b207c903dde80fe8d460dc9b0eb16d58659e571fdc8a035da15a470ebb7a56fd223ff608a91093d91e54bd0a8f4ee019d120d1008504298b304d24848188ea964e68244ee4229a5192f23e84edb19d1672f371d431ae3a332e9db184b1d459227c5ef1685b56117ac76676fb2c182da230cbb1ba29699e411a026ea689898c9d8f4b9b4cbed0bbb74b9533ea1122c865aba8c14a6a13c0cb60f60860afb3f8793fcd46eec495d3940817c40ab18d37ce0b6775c2d3d11f13742fabf90a265cf70a9ccc01858ced37297f0ffdc4827d86477352e1ce214ba861c0b65eafeb63cf2eb87768878395486b32e941d86f7e51770813d0c3a42833dd8cd4d2644776aa773d9453550b0687a8dfae2071c46ce942f687f9496286e5138f936d8c8da04dc1e7ad56e2f73634168b21abecaa60f5744026115bad5fdd159ff0cae94daa91366b75bbbf5c8b33f5cbc41529ba036f3217fb181701a7e4b34e0977f6fa28047f59d4975e3b850c21d4e0d82c0d5ce8236712009576de9811a5b84d540d65a3151336db52fef05cd9ca9f895f212149050ac42918f160f73cc535a2888ec09b14a44e1d50b79037dcfa355f7cc470aac7d1fe354c369afd798e95b54481347609f5f6c5ef2181b90712b20578fca13a1996b9c76156dc352190f123d65db9a43eff61c1d4be5b735ef1c67ad7a33fd23c820e87437bda12442d851e45c3ad296dd2fb76e2e9a90df48087aa687ee6d6077f87ac8fa71beb3d2aeb1692a71674d7a591d7e4329920030fcf629123464f6e2e27fbb0038541d6460e2487fdf04bcba19181550d9db6b1f596fccd0a61df94d505b025f725fe9ac4d073d438c9d27f8b500b3dcb1a45789cb5b3bc081895ce6f4a9252fb39fddd6f2da441eaeb47b8198e5497a21d56be7726e43811200d19cc956",
                "46f3ca09de243b3bf44113829ca9f4a719d882a31878ed130f04d3799c1b85a6ef9ed01f51a66c6fd354ede0140ac49375afcd7cb45b6fe0681a86a762388de71be787a411f479f08adb86e7a624eba426e44d2a311bc8596ee4bc91158837742bd7a7c0861cea5dc2599e1aae6f543a19795be71c3a43e4784e3cba6dc421b312ff8a31a1267a094d7b021191be71620980be6f001aaa7f5331f72eacb97a4e49bd680ad174da2d5bff64642a26fb61ca261dfc2aeb8b2ce12bd9afe113d4a48accd16d397621b2ab89119d2646e82e52a59c628bdbdc554a18d5e02a6b411960237270134424e470298f8bdabd4cc7582c3d3fd585ed7eb71d19f269968d681d076c19e563d258e47698e246a4935f180f5675eecc307e5384a26c4d4ff5bb105e087aa6496ef6cf2737c88f33486ddca695ff5a0451b25458f904664ee140ce7fdce97a9e5ab28ab32eb586478d7fba8a84c667ba1e62a0365633a878b1c9f9601c37df5afb7ff22aa98217501e7ed4fe95f9ddc03b682782379a9c5655d6dcafc384fd4201f727bf56d8b17efd86ce80d1f104b3d966b1e5d083cba04aa814629bad4d434a3673db107c79107c70ef6d10b608919f442f88a81fd47dca6181f95100727f4260df76ce9d5b3b4be834f8d2b191f8e9e00de49dd0764c003e85465d2362f001289eef63c376931e3955f14629f41e0fa738010baec1dba7b11da8521c2dcdcb2f789bef281a61514e3febae5909a0a5afc237cf00502f88bb5e1080f54df463d2ac457d55cc2f97e3d7540452abda74ac5b122c5bf3e6c2bd06d6b640ae8eac5a32bc88361d0d4e784980926bfb817ae62aaaba892a3f9f039d9b26450e3160725ee2fe375afd64a1be965523dde42c180e2d4b4477603f88d821e44f2ff5a43d57f826893fc8885919c5cf416279c3708efceb6d334b408c524d7b0bd6da38db109482ab33686de2608689a81b516b3b3bd852b2af509bbab588c7d61517988d6b11b3b3bcb5f3088ad666b98551de4ba8a1df633571f98ba856e39df803c891a6df2ddc86f1f58c4b8ee6281f627aee768a440fa7606a74"
            ],
            "completionTime": "2011-10-10 13:19:12Z"
        },
        "bitsUsed": 24576,
        "bitsLeft": 175424,
        "requestsLeft": 9999,
        "advisoryDelay": 0
    },
    "id": 42
}

The random.data array within the result contains the random blobs produced, formatted as hex strings. Note that the completionTime specifies UTC time zone (‘Zulu time’) by the letter ‘Z’ after the clock time. Through the other fields in the result object, RANDOM.ORG also advises how many true random bits were used to satisfy the request (24,576) and how many bits (175,424) and requests (9,999) are left in the client's quota. It also advises the client that it can go ahead and issue the next request without delay (0 milliseconds).

Example 3

The following requests three blobs containing 256 true random bits (32 bytes). By providing a date value for the optional pregeneratedRandomization parameter, the blob returned from this request will have been generated by RANDOM.ORG at some point in the past.

{
    "jsonrpc": "2.0",
    "method": "generateBlobs",
    "params": {
        "apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
        "n": 3,
        "size": 256,
        "format": "base64",
        "pregeneratedRandomization": {
            "date": "2010-12-31"
        }
    },
    "id": 12691
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                "cfujkMXwDfCGdavbUf5hv5Mv++9k+779fZYq9d4QpzM=",
                "Ro/vX8FN5nqSqItU+NXjxHN3/PIBXnzNWmmYsCFJ3Cw=",
                "TqWS3EXlfRPrMtU1M1cMZxmicecrmWfWGqOz+3mWMBk="
            ],
            "completionTime": "2021-03-26 09:19:33Z"
        },
        "bitsUsed": 0,
        "bitsLeft": 250000,
        "requestsLeft": 997,
        "advisoryDelay": 2000
    },
    "id": 12691
}

The random object contains the random blobs returned by the server. By asking for pregenerated random values, any request with the same specifications, i.e. the same values for n, size, format and pregeneratedRandomization, will return the same data. This also applies to the equivalent method in the Signed API, see Example 5 of the generateSignedBlobs method.

The service also advises that no bits were used to satisfy the request, as the values are not generated on-the-fly. It also includes how many bits and requests are left in the client's quota.

Example 4

As in Example 3, the following requests three base-64 blobs containing 256 true random bits (32 bytes). This time, however, the pregeneratedRandomization contains an id value instead of a date value, again asking for a blob which was generated by RANDOM.ORG some point in the past.

{
    "jsonrpc": "2.0",
    "method": "generateBlobs",
    "params": {
        "apiKey": "3fcffb4b-62ca-4a5b-b25e-05e27d909182",
        "n": 3,
        "size": 256,
        "format": "base64",
        "pregeneratedRandomization": {
            "id": "foobar"
        }
    },
    "id": 22746
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                "dBnnpfPzQC/LSQ6NjYJXNXBMyo2lQNxEXscHo0NydkE=",
                "6VV61+xATr34Zv5L4xvYMNK4i6sJRbaZ1o4ZDl3lZn8=",
                "SUAuzcxSTdaSDokWVDnGxHTthu9FSJUMORTDOBbH8Sg="
            ],
            "completionTime": "2021-03-26 11:20:34Z"
        },
        "bitsUsed": 0,
        "bitsLeft": 250000,
        "requestsLeft": 994,
        "advisoryDelay": 1790
    },
    "id": 22746
}

Like Example 3, any time a request with the same parameters is sent, the data returned will be identical.

getUsage (method)

This method returns information related to the usage of a given API key. Your client must set the method property of its JSON-RPC request object to getUsage. The request must also contain an id member, which will be returned in the response.

Required Parameters

The following parameters are mandatory and should be specified in the params array of the JSON-RPC request:

apiKey
Your API key, which is used to track the true random bit usage for your client.

Optional Parameters

This method has no optional parameters.

Successful Response

If the request succeeded, RANDOM.ORG returns a JSON-RPC response with the result property containing an object with the following named values:

status
A string indicating the API key's current status, which may be stopped or running. An API key must be running for it to be able to serve requests.
creationTime
A string containing the timestamp in ISO 8601 format at which the API key was created.
bitsLeft
An integer containing the (estimated) number of remaining true random bits available to the client.
requestsLeft
An integer containing the (estimated) number of remaining API requests available to the client.
totalBits
An integer containing the number of bits used by this API key since it was created.
totalRequests
An integer containing the number of requests used by this API key since it was created.

For a successful response, the error property is absent.

Error Response

If an error occurred, RANDOM.ORG returns a JSON-RPC response in which the result property is absent and the error property contains an error object as described in Error Codes and Messages.

Example 1

The following requests usage information for an API key that exists and is running.

{
    "jsonrpc": "2.0",
    "method": "getUsage",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000"
    },
    "id": 15998
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "status": "running",
        "creationTime": "2013-02-01 17:53:40Z",
        "bitsLeft": 998532,
        "requestsLeft": 199996,
        "totalBits": 1646421,
        "totalRequests": 65036
    },
    "id": 15998
}

RANDOM.ORG informs that the API key in question is running and advises how many bits (998,532) and requests (199,996) are left in its quota. The response also contains information about how many bits (1,646,421) and requests (65,036) have been served with this API key since it was created (on 1 February 2013 at 5.53pm UTC).

Example 2

The following requests usage information for an API key that is stopped.

{
    "jsonrpc": "2.0",
    "method": "getUsage",
    "params": {
        "apiKey": "00000000-0000-0000-0000-000000000000"
    },
    "id": 21185
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "status": "stopped",
        "creationTime": "2013-02-01 17:53:40Z",
        "bitsLeft": 871365,
        "requestsLeft": 199977,
        "totalBits": 3519123,
        "totalRequests": 69274
    },
    "id": 21185
}

RANDOM.ORG advises that the API key in question exists but is stopped, which means that it cannot be used to serve requests. The service also informs how many bits (871,365) and requests (199,977) are left in the quota for this API key. The response also contains information about how many bits (3,519,123) and requests (69,274) have been served with this API key since it was created (on 1 February 2013 at 5.53pm UTC).

Example 3

The following requests usage information for an API key that does not exist.

{
    "jsonrpc": "2.0",
    "method": "getUsage",
    "params": {
        "apiKey": "ffffffff-ffff-ffff-ffff-ffffffffffff"
    },
    "id": 3677
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "error": {
        "code": 400,
        "message": "The API key you specified does not exist",
        "data": null
    },
    "id": 3677
}

RANDOM.ORG advises that the API key in question does not exist. More information about the error object contained in the error property can be found in Error Codes and Messages.