Documentation
Documentation for the Random User Generator API
Follow us @randomapiDocumentation for the Random User Generator API
Follow us @randomapiIn August 2013, we set out with a goal to create a free and easy to use service to generate random user data for application testing.
You can use AJAX to call the Random User Generator API and will receive a randomly generated user in return. If you are using jQuery, you can use the $.ajax() function in the code snippet below to get started.
$.ajax({
url: 'https://randomuser.me/api/',
dataType: 'json',
success: function(data) {
console.log(data);
}
});
The API will provide you with a formatted object of your choice that you can parse and apply to your application.
JSON is the default format. You can request a different format using the format parameter.
{
"results": [
{
"gender": "female",
"name": {
"title": "Miss",
"first": "Jennie",
"last": "Nichols"
},
"location": {
"street": {
"number": 8929,
"name": "Valwood Pkwy",
},
"city": "Billings",
"state": "Michigan",
"country": "United States",
"postcode": "63104",
"coordinates": {
"latitude": "-69.8246",
"longitude": "134.8719"
},
"timezone": {
"offset": "+9:30",
"description": "Adelaide, Darwin"
}
},
"email": "[email protected]",
"login": {
"uuid": "7a0eed16-9430-4d68-901f-c0d4c1c3bf00",
"username": "yellowpeacock117",
"password": "addison",
"salt": "sld1yGtd",
"md5": "ab54ac4c0be9480ae8fa5e9e2a5196a3",
"sha1": "edcf2ce613cbdea349133c52dc2f3b83168dc51b",
"sha256": "48df5229235ada28389b91e60a935e4f9b73eb4bdb855ef9258a1751f10bdc5d"
},
"dob": {
"date": "1992-03-08T15:13:16.688Z",
"age": 30
},
"registered": {
"date": "2007-07-09T05:51:59.390Z",
"age": 14
},
"phone": "(272) 790-0888",
"cell": "(489) 330-2385",
"id": {
"name": "SSN",
"value": "405-88-3636"
},
"picture": {
"large": "https://randomuser.me/api/portraits/men/75.jpg",
"medium": "https://randomuser.me/api/portraits/med/men/75.jpg",
"thumbnail": "https://randomuser.me/api/portraits/thumb/men/75.jpg"
},
"nat": "US"
}
],
"info": {
"seed": "56d27f4a53bd5441",
"results": 1,
"page": 1,
"version": "1.4"
}
}
If our API service is offline or if we are experiencing server issues, we'll return a simple JSON object with an error.
{
error: "Uh oh, something has gone wrong. Please tweet us @randomapi about the issue. Thank you."
}
Random User Generator allows you to fetch up to 5,000 generated users in one request using the results parameter.
https://randomuser.me/api/?results=5000
You can specify whether you would like to have only male or only female users generated by adding the gender parameter to your request. Valid values for the gender parameter are "male" or "female", or you may leave the parameter blank. Any other value will cause the service to return both male and female users.
https://randomuser.me/api/?gender=female
By default, passwords are chosen randomly from a list of ~10k top used passwords. Starting with version 1.1, you can have more control over how passwords are generated using the password option.
https://randomuser.me/api/?password=upper,lower,1-16
The example above would generate a password consisting of uppercase and lowercase characters ranging between 1 to 16 characters long.
You can specify options for the passwords using this format:
https://randomuser.me/api/?password=CHARSETS,MIN_LENGTH-MAX_LENGTH OR https://randomuser.me/api/?password=CHARSETS,MAX_LENGTH
You can mix and match the charsets below for the CHARSETS option above:
special !"#$%&'()*+,- ./:;<=>?@[\]^_`{|}~
upper ABCDEFGHIJKLMNOPQRSTUVWXYZ
lower abcdefghijklmnopqrstuvwxyz
number 0123456789
MIN_LENGTH and MAX_LENGTH are the min/max length of the passwords that you want to generate.
By default, passwords will be between 8 - 64 characters long.
Here are some more examples of password option combinations:
// Special chars exactly 32 characters long https://randomuser.me/api/?password=special,32 // Uppercase chars between 1 to 8 characters long https://randomuser.me/api/?password=upper,1-8 // Special, uppercase, lowercase, and numeric chars between the default 8 to 64 characters long https://randomuser.me/api/?password=special,upper,lower,number
Seeds allow you to always generate the same set of users. For example, the seed "foobar" will always return results for Becky Sims (for version 1.0). Seeds can be any string or sequence of characters.
https://randomuser.me/api/?seed=foobar
We currently offer the following data formats:
Just specify the format you would like returned by using the format parameter.
https://randomuser.me/api/?format=csv
When we release a new version the API, it could possibly break your application. By accessing the API via:
https://randomuser.me/api/
The result that is returned automatically uses the latest version of the API.
If you want to access a specific version of the API that won't be affected by updates, do this:
https://randomuser.me/api/1.4/You can request a different nationality of a randomuser.
Pictures won't be affected by this, but data such as location, cell/home phone, id, etc. will be more appropriate.
Currently, randomuser offers these nationalities:
You can specify a nationality like so:
https://randomuser.me/api/?nat=gb
Randomuser will return random nats by default. You can have some control with the nats that you'd like to have generated by specifying a comma seperated list:
https://randomuser.me/api/?nat=us,dk,fr,gb
You can request multiple pages of a seed with the page parameter.
Make sure that you use the same seed and page number (1 based index) in order to get back the same results
https://randomuser.me/api/?page=3&results=10&seed=abc
Sometimes, maybe you want some random names and not extraneous data such as location, phone, etc.
Using the inc and exc parameters, you can specify which fields to include or exclude respectively.
By specifying only the fields you want, the generator can save time by skipping CPU intensive fields like "login" for example.
These parameters accept the following values in a comma delimited list
If you only wanted the names,genders,and nats of users:
https://randomuser.me/api/?inc=gender,name,nat
If you want everything except for login data:
https://randomuser.me/api/?exc=login
Some extra parameters that you can add to a request.
https://randomuser.me/api/?results=25&nat=gb,us,es&format=csv&dl
https://randomuser.me/api/?results=5&inc=name,gender,nat&noinfo
https://randomuser.me/api/?results=5&callback=randomuserdata
If you find a mistake with an API or would like to contribute to our database, feel free to visit our Github Repo. We'd really appreciate it :)