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.
The URL for invoking the Basic API is
https://api.random.org/json-rpc/3/invoke
No changes were made to the Basic API.
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.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeynminmax
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)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)2, 8,
10 and 16. This affects the JSON
types and formatting of the resulting data as discussed below.
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:
randomdatabase 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.
completionTimebitsUsedbitsLeftrequestsLeftadvisoryDelay
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.
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.
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).
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.
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.
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.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeynlengthlength 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.
minmin 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.
maxmax 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.
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)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)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.
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:
randomdatadata 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.
completionTimebitsUsedbitsLeftrequestsLeftadvisoryDelay
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.
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.
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.
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 a new request.
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.
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.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeyndecimalPlaces
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)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.
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:
randomdatacompletionTimebitsUsedbitsLeftrequestsLeftadvisoryDelay
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.
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.
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).
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.
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).
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.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeynmeanstandardDeviationsignificantDigitsThere are no optional parameters. In particular, Gaussians are always picked with replacement.
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:
randomdatacompletionTimebitsUsedbitsLeftrequestsLeftadvisoryDelay
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.
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.
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).
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.
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.
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.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeynlengthcharacters
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:
replacement (default value true)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.
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:
randomdatacompletionTimebitsUsedbitsLeftrequestsLeftadvisoryDelay
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.
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.
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).
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": "generateStrings",
"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.
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": "abcdefghijklmnopqrstuvwxyzæøåABCDEFGHIJKLMNOPQRSTUVWXYZÆØÅ"
},
"id": 15443
}
The service responds with the following:
{
"jsonrpc": "2.0",
"result": {
"random": {
"data": [
"ØkbQ", "Bhgx", "jNAL", "ceZV",
"xæGq", "tÆrA", "gåBA", "bRCg",
"MæpU", "jJoÅ", "zAZd", "uhdX",
"sÅiz", "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.
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.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeynThis method has no optional parameters.
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:
randomdatacompletionTimebitsUsedbitsLeftrequestsLeftadvisoryDelay
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.
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.
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).
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.
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.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeynsizeThe total size of all blobs requested must not exceed 1,048,576 bits (128 KiB).
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:
format (default value base64)base64 and hex.
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:
randomdataformat
specified in the request.
completionTimebitsUsedbitsLeftrequestsLeftadvisoryDelay
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.
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.
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).
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).
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.
The following parameters are mandatory and should be specified
in the params array of the JSON-RPC request:
apiKeyThis method has no optional parameters.
If the request succeeded, RANDOM.ORG returns
a JSON-RPC response with the result property containing
an object with the following named values:
statusstopped or running. An API key must
be running for it to be able to serve requests.
creationTimebitsLeftrequestsLefttotalBitstotalRequests
For a successful response, the error property is
absent.
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.
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).
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).
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.