Random UserDocumentation for the Random User Generator API
In 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.mintbin.xyz/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": "Springfield",
"state": "Illinois",
"country": "United States",
"postcode": "62704",
"coordinates": {
"latitude": "39.7990",
"longitude": "-89.6412"
},
"timezone": {
"offset": "-6:00",
"description": "Central Time (US & Canada), Mexico City"
}
},
"email": "jennie.nichols@example.com",
"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": "(217) 561-9542",
"cell": "(217) 304-7718",
"id": {
"name": "SSN",
"value": "405-88-3636"
},
"picture": {
"large": "https://randomuser.mintbin.xyz/api/portraits/men/75.jpg",
"medium": "https://randomuser.mintbin.xyz/api/portraits/med/men/75.jpg",
"thumbnail": "https://randomuser.mintbin.xyz/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 open an issue on the repository. Thank you."
}
Random User Generator allows you to fetch up to 5,000 generated users in one request using the results parameter.
https://randomuser.mintbin.xyz/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.mintbin.xyz/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.mintbin.xyz/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.mintbin.xyz/api/?password=CHARSETS,MIN_LENGTH-MAX_LENGTH OR https://randomuser.mintbin.xyz/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.mintbin.xyz/api/?password=special,32 // Uppercase chars between 1 to 8 characters long https://randomuser.mintbin.xyz/api/?password=upper,1-8 // Special, uppercase, lowercase, and numeric chars between the default 8 to 64 characters long https://randomuser.mintbin.xyz/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.mintbin.xyz/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.mintbin.xyz/api/?format=csv
When we release a new version the API, it could possibly break your application. By accessing the API via:
https://randomuser.mintbin.xyz/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.mintbin.xyz/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.mintbin.xyz/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.mintbin.xyz/api/?nat=us,dk,fr,gb
To find out which nationalities a version offers without reading this page, ask the API. Add /nats after the version (or after /api/ for the latest version):
https://randomuser.mintbin.xyz/api/1.4/nats
The response lists every code the version generates with the country it stands for, sorted by country:
{
"nats": [
{"code": "AU", "country": "Australia"},
{"code": "BR", "country": "Brazil"},
...
],
"info": {"results": 22, "version": "1.4"}
}
An unknown nationality is not an error: the API quietly generates a random one instead, so this is the way to check a code before relying on it.
Alongside nat, you can ask for users from a particular region, city or postcode with the state, city and zip parameters (postcode works the same as zip). Use one, or combine them — a combination has to describe a single place.
https://randomuser.mintbin.xyz/api/?nat=us&state=Texas https://randomuser.mintbin.xyz/api/?nat=gb&city=Aberdeen https://randomuser.mintbin.xyz/api/?nat=us&zip=35203 https://randomuser.mintbin.xyz/api/?nat=us&city=Springfield&state=Illinois
Every user then lives there. The region, city, postcode, dialling code, timezone, street and coordinates all belong to the place you named, and a postcode you name is the one on the address.
Matching is exact but forgiving about case and accents — city=kobenhavn finds København. Postcodes are compared without spaces, hyphens or case, and a partial code matches the codes it starts: zip=AB10 finds every Aberdeen address in AB10, and zip=M5V 2T6 finds Toronto's M5V area (Canadian and Irish codes are stored down to the area, and the rest of the code is generated). A postcode shorter than three characters is ignored.
A filter that matches nothing is not an error. If the city is misspelt, the postcode is from another country, or the combination describes no real place, the request simply returns the usual random addresses for that nationality — exactly what ?nat= alone would give. Without nat the filters are ignored, since a city means nothing without its country. With several nationalities, each user's filter applies to the country they were drawn from.
Seeds work as usual: the same seed with the same filters always returns the same users.
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.mintbin.xyz/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.mintbin.xyz/api/?inc=gender,name,nat
If you want everything except for login data:
https://randomuser.mintbin.xyz/api/?exc=login
Some extra parameters that you can add to a request.
https://randomuser.mintbin.xyz/api/?results=25&nat=gb,us,es&format=csv&dl
https://randomuser.mintbin.xyz/api/?results=5&inc=name,gender,nat&noinfo
https://randomuser.mintbin.xyz/api/?results=5&callback=randomuserdata
If you find a mistake in the data — a postcode that does not serve its city, a dialling code on the wrong town — it is worth reporting. That is the class of bug this build exists to remove.