api.nameror.com docs ๐ŸŽ“

๐ŸŽ“ Nameror Gender API documentation

In this documentation you are going to learn everything relevant to your integration of the Nameror Gender API.

๐Ÿคฒ Request data

Determination API

To request gender data as well as name type data at the same time, perform a GET request on the all node.

GET https://api.nameror.com/api/APIKEY/all/NAME

To request gender data only perform a GET request on the gender node.

GET https://api.nameror.com/api/APIKEY/gender/NAME

To request name type data only perform a GET request on the type node.

GET https://api.nameror.com/api/APIKEY/type/NAME



Send your names space separated, like this: Elvis Aaron Presley.

GET https://api.nameror.com/api/APIKEY/type/Elvis Aaron Presley

This results to the following response.

{
    "error":null,
    "data":[{
        "name":"Elvis",
        "genderData":{
            "gender":"male",
            "certainty":101
        },
        "typeData":{
            "type":"both",
            "certainty":101
        }
    },{
        "name":"Aaron",
        "genderData":{
            "gender":"male",
            "certainty":101
        },
        "typeData":{
            "type":"both",
            "certainty":101
        }
    },{
        "name":"Presley",
        "genderData":{
            "gender":"both",
            "certainty":101
        },
        "typeData":{
            "type":"lastname",
            "certainty":101
        }
    }]
}

In case of errors, the error message is in the error field.


Random API

To request random names perform a GET request on the random node.
Randomizer requests are charged 1: 1 on your query credit.
TYPE: givenname, lastname or both
AMOUNT: integer from 1 to 1000

GET https://api.nameror.com/api/APIKEY/random/TYPE/AMOUNT

โœ Perform corrections

To correct name data, POST the corrected name JSON object to the correction node. Corrections will be treated the same way, as corrections on nameror.com are treated.

POST https://www.nameror.com:3365/api/APIKEY/correction
{
    "name": "NAME",
    "gender": "GENDER", // male, female or both
    "type": "TYPE" // firstname, lastname or both
}

This is the response in case of success:

{
    "error": null,
    "status": "success"
}

In case of errors, the error message is in the error field.

๐Ÿ“š JavaScript Library

To make it easier we created a JavaScript Library, so you can keep your code as clean as possible. Include the library in the head of your page. Is is 1.3 kB only!

<script src="https://api.nameror.com/cdn/nameror.min.js"></script>

You can also defer or async it, but don't forget to put your code into a window.onload event.

Initialize

Create a new Nameror instance and pass it your API key as the first argument.

var nameror = new Nameror('APIKEY');

Nameror.getAll()

nameror.getAll('Napoleon Bonaparte', function(error, response) {
    if (error) return console.error(error);
    console.log(reponse); // your gender and type data
});

Nameror.getGender()

nameror.getGender('Thomas Jefferson', function(error, response) {
    if (error) return console.error(error);
    console.log(reponse); // your gender data
});

Nameror.getType()

nameror.getType('Marie Curie', function(error, response) {
    if (error) return console.error(error);
    console.log(reponse); // your type data
});

Nameror.correct()

nameror.correct({
    name: 'Marie',
    gender: 'female', // optional
    type: 'givenname' // optional
}, function(error, response) {
    if (error) return console.error(error);
    console.log(reponse); // success!
});

๐Ÿ’ก Gender prediction in forms

You could use our API to autocomplete gender data in your forms, for example in salutation fields, or even completely abandon your salutations fields on the basis of the certainty value we always send you.

Step 1: Have a form

<form action="*">
    <input name="name" class="name" type="name" />
    <select name="salutation" class="salutation">
        <option>Please chose...</option>
        <option value="female">Dear Ms.</option>
        <option value="male">Dear Mr.</option>
    </select>
</form>

Step 2: Load our library

<script src="https://api.nameror.com/cdn/nameror.min.js"></script>

Step 3: Add your JavaScript

var nameror = new Nameror('APIKEY'); var nameElement = document.querySelector('.name');
var salutationElement = document.querySelector('.salutation');
var apiUrl = 'https://api.nameror.com/api/APIKEY/all/';

var keyupLimiter;
nameElement.addEventListener('keyup', function() {
    if (keyupLimiter) {
        clearTimeout(keyupLimiter);
        keyupLimiter = null;
    }
    keyupLimiter = setTimeout(function() {
        nameror.getAll(nameElement.value, function(error, response) {
            if (error) return console.error(error);
            var firstGivennameGender;
            response.forEach(function(data) {
                if (data.typeData.type == 'givenname' && !firstGivennameGender) {
                    firstGivennameGender = data.genderData.gender;
                }
            });
            if (firstGivennameGender) {
                salutationElement.value = firstGivennameGender;
            } else {
                salutationElement.selectedIndex = 0;
            }
        });
    }, 500);
});

Step 4: Done

Easy as cake! Now your salutation dropdown is automatically prefilled, if the API sends gender data for the first given name in the name input.
You can tweak this as you like. No boundaries here.

โ— Remember to limit your requests on user input, to not burn through your request credit.

๐Ÿงน Request in any language for dataset tidying and everything else

Just request the JSON from the URL. It's easy.

curl

curl https://api.nameror.com/api/APIKEY/all/NAME

JavaScript

var xhr = new XMLHttpRequest();
xhr.addEventListener('load', function() {
    console.log(xhr.responseText);
});
xhr.open('get', 'https://api.nameror.com/api/APIKEY/all/NAME');
xhr.send();

PHP

$url = "https://api.nameror.com/api/APIKEY/all/NAME";
$curl = curl_init();
$result = curl_exec($curl);
curl_close($curl);

Python

import requests
url = 'https://api.nameror.com/api/APIKEY/all/NAME'
response = requests.get(url);


... and every other language that supports requests. ๐Ÿ˜‰