True Random Number Service

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.

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.

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,1e4] range.

decimalPlaces

The number of decimal places to use. Must be within the [1,20] 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.

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 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 20 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": 20
    },
    "id": 4352
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                0.85890418365935235672, 0.86883621972704187649,
                0.42126293542103455824, 0.496355715084044768,
                ...
            ],
            "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).

This method generates true random numbers from a Gaussian distribution (also known as a normal distribution). The form 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,1e4] range.

mean

The distribution's mean. Must be within the [-1e6,1e6] range.

standardDeviation

The distribution's standard deviation. Must be within the [-1e6,1e6] range.

significantDigits

The number of significant digits to use. Must be within the [2,20] range.

Optional Parameters

There are no optional parameters. In particular, 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 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 decimal places. 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": "generateDecimalFractions",
    "params": {
        "apiKey": "6b1e65b9-4186-45c2-8981-b77a9842c4f0",
        "n": 2000,
        "mean": 1100,
        "standardDeviation": 100,
        "decimalPlaces": 4
    },
    "id": 3076
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                1102, 1182, 940.2, 1009,
                1185, 998.8, 1125, 1027,
                ...
	    ],
            "completionTime": "2013-01-25 19:21:15Z",
        },
	"bitsUsed": 26575,
	"bitsLeft": 173425,
        "requestsLeft": 1552,
	"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 100 random numbers from a Gaussian distribution with mean 140 and standard deviation 10, accurate to six decimal places.

{
    "jsonrpc": "2.0",
    "method": "generateDecimalFractions",
    "params": {
        "apiKey": "6b1e65b9-4186-45c2-8981-b77a9842c4f0",
        "n": 100,
        "mean": 140,
        "standardDeviation": 10,
        "significantDigits": 6
    },
    "id": 4352
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
                130.55, 128.377, 135.574, 140.546,
                162.821, 153.533, 143.96, 149.749,
                ...
            ],
            "completionTime": "2013-01-25 19:24:33Z"
        },
        "bitsUsed": 1993,
        "bitsLeft": 198007,
        "requestsLeft": 9987,
        "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 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.

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,1e4] range.

length

The length of each string. Must be within the [1,20] 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 80.

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.

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. 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., can contain duplicate values.

{
    "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 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 (470) and how many bits (199,530) 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 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": "6b1e65b9-4186-45c2-8981-b77a9842c4f0",
        "n": 16,
        "length": 4,
        "characters": "abcdefghijklmnopqrstuvwxyzæøåABCDEFGHIJKLMNOPQRSTUVWXYZÆØÅ"
    },
    "id": 4352
}

The service responds with the following:

{
    "jsonrpc": "2.0",
    "result": {
        "random": {
            "data": [
              "\u00c6hvj", "b\u00f8uA", "PkQx", "Qp\u00e6P",
              "RpnK", "vyq\u00d8", "Elhp", "YSMS",
              "riHv", "F\u00d8Ru", "h\u00d8Kc", "mIPR",
              "FtNg","Qi\u00e5W","zjhK","ACbf"
            ],
            "completionTime": "2011-10-10 13:19:12Z"
        },
        "bitsUsed": 375,
        "bitsLeft": 199625,
        "requestsLeft": 9987,
        "advisoryDelay": 0
    },
    "id": 4352
}

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.

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,1e3] range.

Optional Parameters

This method has no optional parameters.

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 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.

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.

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 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 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).

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, paused 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 paused.

{
    "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": "paused",
        "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 paused, which means that it cannot be used to serve requests right now. 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.