Advisory: We only operate services from the RANDOM.ORG domain. Other sites that claim to be operated by us are impostors. If in doubt, contact us.
Note: This API is obsolete. Please use our new API at api.random.org instead.
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). There is also the HTTP Client Archive, which contains clients that other people have written.
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.
All the interfaces on this page return HTTP status code 503 (Service Unavailable) in the case of errors and code 200 (OK) when successful. Not all languages allow you to access the HTTP status codes in a straightforward manner. A reasonable workaround is to look for the string "Error:" (don't forget the colon) as the first line of the response. This will work for all the generators on this page, including the String Generator (which could by chance produce the string "Error" in a successful response, but which cannot produce the colon character).
Please note that the old CGI scripts (randbyte, randnum, etc.) are no longer supported and you should use the ones described below instead. In particular, the old scripts do not return the 503 status code in case of errrors (they return the 200 response code in all cases), so please use the new ones instead.
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.
| Name | Possible Values | Description |
|---|---|---|
| num | [1,1e4] | The number of integers requested. |
| min | [-1e9,1e9] | The smallest value allowed for each integer. |
| max | [-1e9,1e9] | The largest value allowed for each integer. |
| col | [1,1e9] | 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 the current day (according to UTC) or a day in the past. The date must be in ISO 8601 format (i.e., YYYY-MM-DD) or one of the two shorthand strings today or yesterday. |
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.
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 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.
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.
https://www.random.org/integers/?num=10&min=1&max=6&col=1&base=10&format=plain&rnd=new
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.
| Name | Possible Values | Description |
|---|---|---|
| min | [-1e9,1e9] | The lower bound of the interval (inclusive). |
| max | [-1e9,1e9] | The upper bound of the interval (inclusive). |
| col | [1,1e9] | The number of columns in which the integers will be arranged. The integers should be read (or processed) left to right across columns. |
| 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 the current day (according to UTC) or a day in the past. The date must be in ISO 8601 format (i.e., YYYY-MM-DD) or one of the two shorthand strings today or yesterday. |
The sequence requested must 10,000 numbers or shorter in length, i.e., max-min+1≤1e4.
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 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.
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 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.
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.
https://www.random.org/sequences/?min=1&max=52&col=1&format=plain&rnd=new
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.
| Name | Possible Values | Description |
|---|---|---|
| num | [1,1e4] | 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 the current day (according to UTC) or a day in the past. The date must be in ISO 8601 format (i.e., YYYY-MM-DD) or one of the two shorthand strings today or yesterday. |
If no error occurred, the returned page will contain a list of strings. If XHTML was requested, the strings will be formatted on separate lines inside a <pre></pre> element. If plain text was requested, the strings will be separated by line feeds.
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 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.
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.
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.
The Quota Checker allows you to examine your quota at any point in time. The quota system works on the basis of IP addresses. Each IP address has a base quota of 1,000,000 bits. When your client makes a request for random numbers (or strings, etc.), the server deducts the number of bits it took to satisfy your request from the quota associated with your client's IP address.
If your client issues a request for random numbers while its quota is negative, the RANDOM.ORG server will return a 503 error response as described below. If your client's quota is greater than or equal to zero, the server will fully complete the client's next request for random numbers, even if the request will result in the client's quota becoming negative. Hence, no partial responses will be sent as a result of your client exhausting its quota; the server will either return a full response or an error response.
Every day, shortly after midnight UTC, all quotas with less than 1,000,000 bits receive a free top-up of 200,000 bits. If the server has spare capacity, you may get an additional free top-up earlier, but you should not count on it. If you need extra bits urgently (or require many bits) you can purchase once-off top-ups from the Quota Page.
The Guidelines for Automated Clients specify that you should use the Quota Checker periodically to verify that your client is not issuing requests for random numbers to the RANDOM.ORG server when its quota is exhausted. For most clients, the easiest solution is to interleave the quota checks with the requests for random numbers. If a quota check returns a negative value, your client should back off for at least ten minutes before issuing another quota check. Only when the quota check returns a zero or positive value, should your client resume its requests for random numbers. If you want to build a really well-behaved client, you can implement an exponential backoff algorithm with a maximum delay of 24 hours.
The number of random number requests your client can issue before doing a quota check depends on how many bits each random number requests requires to satisfy. See the FAQ for details about how to estimate this. As a rule of thumb, your client should probably issue a quota check every time it thinks it has used its daily free top-up. This will mean the client can continue issue requests in case things are better than expected (perhaps it has received a free top-up) but that it will back off in case its quota is exhausted.
The Quota Checker only accepts HTTP GET requests, so parameters are passed via encoding in the URL.
| 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. |
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 followed by a single newline.
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 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.
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.
https://www.random.org/quota/?format=plain
The following example examines the quota for the machine whose IP address is 134.226.36.80, 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.
https://www.random.org/quota/?ip=134.226.36.80&format=plain