Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/thm/uinames

A simple tool to generate names for use in designs and mockups.
https://github.com/thm/uinames

Last synced: about 1 month ago
JSON representation

A simple tool to generate names for use in designs and mockups.

Awesome Lists containing this project

README 

        
uinames.com

=======



This is the repo for [uinames.com](https://uinames.com). Feel free to contribute to the project by adding names. Keep in mind that more isn't better. Quality over quantity. Quality being the most common/popular names in a region.



### The Algorithm

When the option to pick a region at random is selected, a region will be picked based on the amount of possible name-combinations for that region. A region with more names is more likely to be picked, and regions with less names are less likely to be picked. I propose having a maximum of 100 male names, 100 female names and 300 last names per region. That's 60.000 possible combinations per region.



### The Layout (JSON)

    [

      {

        "region": "Region",

        "male": ["Male", "First", "Names"],

        "female": ["Female", "First", "Names"],

        "surnames": ["Last", "Names"]

      },

      {etc}

    ]



### The API

All responses are returned as JSON(P) over HTTP(S). There is currently no request limit. However, please keep the amount of requests to a minimum, and cache responses whenever possible.



#### Basic usage

    https://uinames.com/api/

    ---

    {

      "name":"John",

      "surname":"Doe",

      "gender":"male",

      "region":"United States"

    }

#### Optional Parameters

Number of names to return, between `1` and `500`:

https://uinames.com/api/?amount=25



Limit results to the `male` or `female` gender:

https://uinames.com/api/?gender=female



Region-specific results:

https://uinames.com/api/?region=germany



Require a minimum number of characters in a name:

https://uinames.com/api/?minlen=25



Require a maximum number of characters in a name:

https://uinames.com/api/?maxlen=75



For JSONP, specify a callback function to wrap results in:

https://uinames.com/api/?callback=example



#### Extra Data

Additional random data is served to requests passing an `ext` parameter. However, response times may be slower, especially when requesting larger quantities of data.

All photos are hand-picked from [unsplash.com](https://unsplash.com) ([license](https://unsplash.com/license)):


https://uinames.com/api/?ext

---

{

  "name": "John",

  "surname": "Doe",

  "gender": "male",

  "region": "United States",

  "age": 29,

  "title": "mr",

  "phone": "(123) 456 7890",

  "birthday": {

  "dmy": "19/06/1987", // day, month, year

  "mdy": "06/19/1987", // month, day, year

  "raw": 551062610 // UNIX timestamp

  },

  "email": "[email protected]",

  "password": "Doe87(!",

  "credit_card": {

    "expiration": "12/20",

    "number": "1234-5678-1234-5678",

    "pin": 1234,

    "security": 123

  },

  "photo": "https://uinames.com/api/photos/male/1.jpg"

}



#### Exception handling

Error messages have the following format:

{"error":"Region or language not found"}



### Author

This project is initiated and maintained by [@thomweerd](https://twitter.com/thomweerd).



### Credit

This massive collection of names wouldn't have been as complete without the help of [these wonderful people](https://github.com/thm/uinames/network/members). Thanks for all the contributions and the continued support!



Special thanks to [Claudio Albertin](https://github.com/ClaudioAlbertin) for his work on the API.



### License

Parts of this repository are licensed. Except where otherwise stated, any code not covered by this license is published under exclusive copyright. See [LICENSE.md](LICENSE.md) to learn more.