Documentation

Documentation for the Random User Generator API

Follow us @randomapi

Introduction

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.

How to use

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);
  }
});
      

Results

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"
  }
}

API Errors

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

Requesting Multiple Users

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

Specifying a gender

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

Passwords

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

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

Formats

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

Using previous versions

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/

Nationalities

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

Pagination

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

Including/Excluding fields

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

Miscellaneous

Some extra parameters that you can add to a request.

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