True Random Number Service

HTTP Interface

RANDOM.ORG is a true random number service that generates randomness via atmospheric noise. This page explains how to interface to the service via the Hyper-Text Transfer Protocol (HTTP).

This page contains documentation for the Integer Generator, the Sequence Generator, the String Generator and the Quota Checker, which allows you to examine your current bit allowance.

Note: If you access RANDOM.ORG via an automated client, please make sure you observe the guidelines.

Integer Generator

The Integer Generator will generate truly random integers in configurable intervals. It is pretty easy to write a client to access the integer generator. The integer generator accepts only HTTP GET requests, so parameters are passed via encoding in the URL.

Parameters

Name	Possible Values	Description
num	[1,10e4]	The number of integers requested.
min	[-10e9,10e9]	The smallest value allowed for each integer.
max	[-10e9,10e9]	The largest value allowed for each integer.
col	[1,10e9]	The number of columns in which the integers will be arranged. The integers should be read (or processed) left to right across columns.
base	2 \| 8 \| 10 \| 16	The base that will be used to print the numbers, i.e., binary, octal, decimal or hexadecimal.
format	html \| plain	Determines the return type of the document that the server produces as its response. If html is specified, the server produces a nicely formatted XHTML document (MIME type text/html), which will display well in a browser but which is somewhat cumbersome to parse. If plain is specified, the server produces as minimalistic document of type plain text (MIME type text/plain) document, which is easy to parse. If you are writing an automated client, you probably want to specify plain here.
rnd	new \| id.identifier \| date.iso-date	Determines the randomization to use to generate the numbers. If new is specified, then a new randomization will created from the truly random bitstream at RANDOM.ORG. This is probably what you want in most cases. If id.identifier is specified, the identifier is used to determine the randomization in a deterministic fashion from a large pool of pregenerated random bits. Because the numbers are produced in a deterministic fashion, specifying an id basically uses RANDOM.ORG as a pseudo-random number generator. The third (date.iso-date) form is similar to the second; it allows the randomization to be based on one of the daily pregenerated files. This form must refer to one of the dates for which files exist, so it must be a day in the past. The date must be in ISO 8601 format (i.e., YYYY-MM-DD).

Success

If no error occurred, a HTTP status code of 200 (OK) will be returned. The MIME type will be set in accordance with the format parameter that was specified in the request. The body of the response will contain a list of numbers. If XHTML was requested (via the format parameter), the numbers will be formatted inside a <pre></pre> element. If plain text was requested, the numbers will be separated by line feeds. Multiple columns will be separated by tab characters.

Errors

If an error occurred, a HTTP status code 503 (Service Unavailable) will be returned. The MIME type will be set in accordance with the format parameter that was specified in the request. The body of the the returned page will contain the string "Error:" followed by a string with further details. If XHTML was requested, this message will appear somewhere in the document inside a <p><p> element. If plain text was requested, it will appear on the first line in the document.

The types of errors can vary. Errors will occur if you specify invalid parameters but can also occur because the server is temporarily overloaded. Reasonable behaviour for a client is to look for the "Error:" string in the page returned by the server and print out the whole line if the string was present. When I get around to it, I will provide a full list of possible errors on this page. In the meantime, feel free to experiment ;-)

You probably want to make sure your client can deal with the full range of HTTP response codes, or at least 200, 301 and 503.

Examples

Issuing a HTTP GET request for the following will generate a series of ten integers in the [1,6] interval, suitable as dice rolls, for example in a backgammon game. We are requesting a plain text document to be produced, such that our client can easily parse the numbers. Finally, we are requesting a new randomization.

http://www.random.org/integers/?num=10&min=1&max=6&col=1&base=10&format=plain&rnd=new

todo: one more example here

Sequence Generator

The Sequence Generator will randomize a given interval of integers, i.e., arrange them in random order. It is pretty easy to write a client to access the sequence generator. The sequence generator accepts only HTTP GET requests, so parameters are passed via encoding in the URL.

Parameters

Name	Possible Values	Description
min	[-10e9,10e9]	The lower bound of the interval (inclusive).
max	[-10e9,10e9]	The upper bound of the interval (inclusive).
format	html \| plain	Determines the return type of the document that the server produces as its response. If html is specified, the server produces a nicely formatted XHTML document (MIME type text/html), which will display well in a browser but which is somewhat cumbersome to parse. If plain is specified, the server produces as minimalistic document of type plain text (MIME type text/plain) document, which is easy to parse. If you are writing an automated client, you probably want to specify plain here.
rnd	new \| id.identifier \| date.iso-date	Determines the randomization to use to generate the sequence. If new is specified, then a new randomization will created from the truly random bitstream at RANDOM.ORG. This is probably what you want in most cases. If id.identifier is specified, the identifier is used to determine the randomization in a deterministic fashion from a large pool of pregenerated random bits. Because the numbers are produced in a deterministic fashion, specifying an id basically uses RANDOM.ORG as a pseudo-random number generator. The third (date.iso-date) form is similar to the second; it allows the randomization to be based on one of the daily pregenerated files. This form must refer to one of the dates for which files exist, so it must be a day in the past. The date must be in ISO 8601 format (i.e., YYYY-MM-DD).

The sequence requested must 10,000 numbers or shorter in length, i.e., max-min+1≤10e4.

Success

If no error occurred, the returned page will contain all the integers in the interval in random order. If XHTML was requested, the numbers will be formatted as a series of <li></li> elements inside an <ul></ul> element. If plain text was requested, the numbers will be separated by line feeds.

Errors

You probably want to make sure your client can deal with the full range of HTTP response codes, or at least 200, 301 and 503.

Examples

Issuing a HTTP GET request for the following will return the numbers from the interval [1,52] in random order, for example to shuffle a deck of cards. We are requesting plain text and a new randomization, as in the previous example.

http://www.random.org/sequences/?min=1&max=52&format=plain&rnd=new

todo: one more example here

String Generator

The String Generator will generate truly random strings of various length and character compositions. It is pretty easy to write a client to access the string generator. The string generator accepts only HTTP GET requests, so parameters are passed via encoding in the URL.

Parameters

Name	Possible Values	Description
num	[1,10e4]	The number of strings requested.
len	[1,20]	The length of the strings. All the strings produced will have the same length.
digits	on \| off	Determines whether digits (0-9) are allowed to occur in the strings.
upperalpha	on \| off	Determines whether uppercase alphabetic characters (A-Z) are allowed to occur in the strings.
loweralpha	on \| off	Determines lowercase alphabetic characters (a-z) are allowed to occur in the strings.
unique	on \| off	Determines whether the strings picked should be unique (as a series of raffle tickets drawn from a hat) or not (as a series of die rolls). If unique is set to on, then there is the additional constraint that the number of strings requested (num) must be less than or equal to the number of strings that exist with the selected length and characters.
format	html \| plain	Determines the return type of the document that the server produces as its response. If html is specified, the server produces a nicely formatted XHTML document (MIME type text/html), which will display well in a browser but which is somewhat cumbersome to parse. If plain is specified, the server produces as minimalistic document of type plain text (MIME type text/plain) document, which is easy to parse. If you are writing an automated client, you probably want to specify plain here.
rnd	new \| id.identifier \| date.iso-date	Determines the randomization to use to generate the strings. If new is specified, then a new randomization will created from the truly random bitstream at RANDOM.ORG. This is probably what you want in most cases. If id.identifier is specified, the identifier is used to determine the randomization in a deterministic fashion from a large pool of pregenerated random bits. Because the numbers are produced in a deterministic fashion, specifying an id basically uses RANDOM.ORG as a pseudo-random number generator. The third (date.iso-date) form is similar to the second; it allows the randomization to be based on one of the daily pregenerated files. This form must refer to one of the dates for which files exist, so it must be a day in the past. The date must be in ISO 8601 format (i.e., YYYY-MM-DD).

Success

If no error occurred, the returned page will contain a list of strings. If XHTML was requested, the strings will be formatted as a series of <li></li> elements inside an <ul></ul> element. If plain text was requested, the strings will be separated by line feeds.

Errors

If an error occurred, a HTTP status code 503 (Service Unavailable) will be returned. The MIME type will be set in accordance with the format parameter that was specified in the request. The body of the the returned page will contain the string "Error:" followed by a string with further details. The presence of the colon allows you to distinguish this from a randomly generated string. If XHTML was requested, this message will appear somewhere in the document inside a <p><p> element. If plain text was requested, it will appear on the first line in the document.

You probably want to make sure your client can deal with the full range of HTTP response codes, or at least 200, 301 and 503.

Examples

Issuing a HTTP GET request for the following will generate a series of ten strings of length eight, suitable for example as randomly generated passwords. We are specifying unique We are requesting a html text document that will look nice in a web browser. Finally, we are requesting a new randomization.

http://www.random.org/strings/?num=10&len=8&digits=on&upperalpha=on&loweralpha=on&unique=on&format=html&rnd=new

todo: one more example here

Quota Checker

The Quota Checker allows you to examine your quota at any point in time. The Quota Checker only accepts HTTP GET requests, so parameters are passed via encoding in the URL.

Parameters

Name	Possible Values	Description
ip	n.n.n.n	The IP address for which you wish to examine the quota. Each value for n should be an integer in the [0,255] interval. This parameter is optional. If you leave it out, it defaults to the IP address of the machine from which you are issuing the request.
format	html \| plain	Determines the return type of the document that the server produces as its response. If html is specified, the server produces a nicely formatted XHTML document (MIME type text/html), which will display well in a browser but which is somewhat cumbersome to parse. If plain is specified, the server produces as minimalistic document of type plain text (MIME type text/plain) document, which is easy to parse. The parameter can be left out in which case it defaults to html. If you are writing an automated client, you probably want to specify plain here.

Success

If no error occurred, a HTTP status code of 200 (OK) will be returned. The MIME type will be set in accordance with the format parameter that was specified in the request. The body of the response will contain information about the remaining allowance for the IP address in question. If XHTML was requested (via the format parameter), the information will be nested inside several XHTML elements. If plain text was requested, the current quota level will be returned as a single number.

Errors

You probably want to make sure your client can deal with the full range of HTTP response codes, or at least 200, 301 and 503.

Examples

Issuing a HTTP GET request for the following will return the quota level for the machine issuing the request. We are requesting a plain text document, such that our client can easily parse the number. If you are writing an automated client that downloads numbers or strings from RANDOM.ORG, you can use this type of request to make the client check its quota level. If the value returned is negative, your client should back off as described in the Client Guidelines.

http://www.random.org/quota/?format=plain

The following example examines the quota for the machine whose IP address is 134.226.36.87, which happens to be address of the RANDOM.ORG server. Again, we are requesting a plain text document, so the client can easily parse the value.

http://www.random.org/quota/?ip=134.226.36.87&format=plain