names

This is the repo for names.nnaemekanweke.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://names.nnaemekanweke.com/api/
---
{
  "name":"John",
  "surname":"Doe",
  "gender":"male",
  "region":"United States"
}

Optional Parameters

Number of names to return, between 1 and 500:

https://names.nnaemekanweke.com/api/?amount=25

Limit results to the male or female gender:

https://names.nnaemekanweke.com/api/?gender=female

Region-specific results:

https://names.nnaemekanweke.com/api/?region=germany

Require a minimum number of characters in a name:

https://names.nnaemekanweke.com/api/?minlen=25

Require a maximum number of characters in a name:

https://names.nnaemekanweke.com/api/?maxlen=75

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

https://names.nnaemekanweke.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 (license):

https://names.nnaemekanweke.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://names.nnaemekanweke.com/api/photos/male/1.jpg"
}

Exception handling

Error messages have the following format:

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

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 to learn more.