Documentation

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

Determination API

To request random names perform a GET request on the random node. Randomizer requests are charged 1:1 on your query credit.

TYPE: string -> 'givenname', 'lastname' or 'both'
AMOUNT: integer -> 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.comare treated, with a manual verification process.

POST https://www.nameror.com:3365/api/<APIKEY>/correction

Name: string
GENDER: string -> "male", "female", "both"
TYPE: string -> "givenname", "lastname", "both"

{
    "name": "NAME",
    "gender": "GENDER",
    "type": "TYPE"
}

This is the response in case of success:

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

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!

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

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

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://www.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/';

nameElement.addEventListener('change', 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;
        }
    });
});

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.

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 in every other language that supports http requests. ๐Ÿ˜‰