Namsor API documentation v2.0.16

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

The REST based API allow you to get access to all of Namsor’s features.

Namsor has developed a name checking technology, able to create comprehensive analysis through multiple processing. Our API can classify names by gender, country of origin, ethnicity and even by diaspora. Using a full name and it can distinguish the first name from the last name, infer if it’s a personal name or a brand name as well as identify the most likely phone prefix for that name. Our API also supports many alphabets and is able to translate Japanese names in Kanji and Chinese names in Pinyin both ways.

Need something you can’t find here? We have many more features coming soon. Let us know, we’ll do our best to add it!

Email: contact@namsor.com
Terms and Conditions: NamsorAPI_Lic_v0.0.7

• https://v2.namsor.com/NamSorAPIv2

Introduction

About

• The base endpoint URL is: https://v2.namsor.com/NamSorAPIv2
• For best results, use Batch endpoint to process multi-entity requests
• Batch processing returns the data sorted in the same order as it was sent.
• All endpoints require an API Key.
• Never share your API key to ANYONE.

API Requests and Responses

• All endpoints return JSON containing either an object or a nested array of objects.

• Currently certain NamSor API endpoints use nested object structures in their query body and / or responses, please refer yourself to the corresponding code example.

• Certain API response code examples have been truncated in order to improve readability. For example the countriesOriginTop, ethnicitiesTop and matchCandidates Array fields have been reduced to 2 elements in length.

• Be aware that data in the code examples have been URL encoded into the corresponding ASCII code characters when necessary, for example “谢晓亮” is replaced by “%E8%B0%A2%E6%99%93%E4%BA%AE”. URLs cannot contain spaces or non-ASCII characters. When making GET requests to the API use URL encoding to convert non-ASCII characters into a format that can be transmitted over the internet.

Data Privacy

By default Namsor’s machine learning algorithm may improve data evaluation based on the data inputs and does store logs of submitted request. You may change these setting either in your user account or by calling the dedicated API endpoints. All data logs are secured using AES encryption before being stored.

If you wish to disable machine learning based on your submissions, please set learnable to “false” by using the corresponding Admin route. When set to false for an API key, the data processed using that key will not feed the machine learning algorithm.

If you wish to disable service usage history, please set anonymized to “true” by using the corresponding Admin route. When set to true for an API key, the data processed using that key will be irreversibly anonymised using SHA encryption. Note that the smart processing for redundant queries will still work even if your data is anonymised.

Authentication

API Key Creation

To create an API key visit www.namsor.app and create an account. Navigate to the account information page to retrieve your API key. Your newly created account comes with 5000 free credits that you may use immediately with any of Namsor’s tools: API, demo page, csv and excel file processor or CLI tools.

API Key Installation

Your API key must be set in the header of your request using the X-API-KEY property. Please refer yourself to the provided code samples for correct key installation.

Credits

What are Credits

We use a credit system to track usage. Each plan comes with a monthly quantity of credits and a price for request that exceed your monthly allowance. The free Basic subscription plan grants you 5000 credits but other plans are available in case you have higher requirements.

As an example, with 5000 credits you can either :

• Process 5000 names to determine their gender
• Process 500 names to determine their origin or ethnicity
• Process 250 names to determine their diaspora

Repeated Operations Tolerance

Our API features smart processing and it will not charge for analysing identical data for up to 20 times. For example if you submit the same full name 5 times in order to infer it’s gender then you will only be charged 1 credit.

Soft Limit vs Hard Limit

In your user account you may set two types of credit usage limits:

• A soft limit that will trigger an email notification when reached.
• A hard limit that will trigger an email notification and block the API key when reached.

Track Usage

There are two ways to track your credit usage: check the provided graphics in your user account or query the appropriate Admin routes (API Usage, API Usage History and API Usage History Aggregate).

Enumerators

For readability purposes the enumerators for certain fields may be omitted in the request / response tables. We have detailed the most important classification types in the following section.

Gender

female, male, unknown

Country code

All country codes must be submitted and will be returned using the ISO 3166-1 alpha-2 standard.

US Races and Ethnicities

American Indian or Alaska Native (AI_AN), Asian (A), Black or African-American (B_NL), Hispanic or Latino (HL), Native Hawaiian or Pacific Islander (PI), White or European American (W_NL)

Region Classifications

subRegionOrigin :

Southern Asia, Southern Europe, Northern Africa, Middle Africa, Caribbean, South America, Western Asia, Australia and New Zealand, Western Europe, Northern Europe, Eastern Europe, Central America, Western Africa, Southern Africa, South-Eastern Asia, Eastern Africa, Northern America, Eastern Asia, Melanesia, Central Asia, Micronesia, Polynesia, Unclassified

We provide two regions classifications when inferring the region origin. These classifications have slightly different enumerators as detailed below:

regionOrigin :

Africa, Asia, Europe, Latin America and the Caribbean, Northern America, Oceania, Unclassified

topRegionOrigin :

Africa, Americas, Asia, Europe, Oceania, Unclassified

Errors

The NamSor API uses the following error codes:

Origin

Namsor helps you find thorough information about the origin of a name by establishing a name’s country of origin, the ethnicity, the diaspora and the U.S. race classification. We also provide a corridor evalutation API, to check background information about international interactions.


Try out Origin features

Country

Country code sample :

curl --request GET \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/country/Marie%20Curie \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json'

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/country/Marie%20Curie")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/country/Marie%20Curie"

headers = {
 "Accept": "application/json",
 "X-API-KEY": "your-api-key"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/country/Marie%20Curie", {
  "method": "GET",
  "headers": {
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Returns the most likely geographic context of a full name (first name and last name) or a surname.

Cost : The processing of each query requires 10 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/country/{personalNameFull}

Request Parameters

The above command returns JSON structured like this:

{
  "script": "LATIN",
  "id": "345f20b8-6b93-46d7-a938-2158ae5094fd",
  "name": "Marie Curie",
  "score": 16.010522433640798,
  "country": "FR",
  "countryAlt": "BE",
  "region": "Europe",
  "topRegion": "Europe",
  "subRegion": "Western Europe",
  "countriesTop": [
    "FR",
    "BE"
  ],
  "probabilityCalibrated": 0.6038660468170615,
  "probabilityAltCalibrated": 0.6013059282648627
}

Response

The HTTP response body is an object.

Country Batch

Country Batch code sample :

curl --request POST \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/countryBatch \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","name":"Marie Curie"}]}'

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/countryBatch")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .body("{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"name\":\"Marie Curie\"}]}")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/countryBatch"

payload = {"personalNames": [
        {
            "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
            "name": "Marie Curie"
        }
    ]}
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/countryBatch", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
  },
  "body": "{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"name\":\"Marie Curie\"}]}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Returns the most likely geographic context of up to 100 full names (first names and last names) or surnames.

Cost : The processing of each object requires 10 credits.

HTTP Request

POST https://v2.namsor.com/NamSorAPIv2/api2/json/countryBatch

Body parameter

{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "Marie Curie"
    }
  ]
}

Request Body

The HTTP request body is required to be a nested array of objects.

The above command returns JSON structured like this:

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "Marie Curie",
      "score": 16.010522304999995,
      "country": "FR",
      "countryAlt": "BE",
      "region": "Europe",
      "topRegion": "Europe",
      "subRegion": "Western Europe",
      "countriesTop": [
        "FR",
        "BE"
      ],
      "probabilityCalibrated": 0.6038660443624172,
      "probabilityAltCalibrated": 0.6013059169873552
    }
  ]
}

Response

The HTTP response body is a nested array of objects.

Country Subclassification

Country Subclassification code sample :

curl --request GET \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/subclassification/IN/Amitabh/Bachchan \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json'

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/subclassification/IN/Amitabh/Bachchan")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/subclassification/IN/Amitabh/Bachchan"

headers = {
 "Accept": "application/json",
 "X-API-KEY": "your-api-key"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/subclassification/IN/Amitabh/Bachchan", {
  "method": "GET",
  "headers": {
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Returns the most likely geographic subdivision context of a first name and a last name. Subdivision are either a country’s states or regions. At the moment this is only supported for India (ISO 3166-1 alpha-2 code “IN”).

Cost : The processing of each query requires 10 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/subclassification/{countryIso2}/{firstName}/{lastName}

Request Parameters

The above command returns JSON structured like this:

{
  "script": "LATIN",
  "id": "5dd784f2-d1d3-41b8-bba5-c064a836646b",
  "firstName": "Amitabh",
  "lastName": "Bachchan",
  "countryIso2": "IN",
  "subClassification": "IN-CH",
  "subClassificationAlt": "IN-UT",
  "subclassificationTop": [
    "IN-CH",
    "IN-UT",
    "IN-AN",
    "IN-UP",
    "IN-DL",
    "IN-HR",
    "IN-RJ",
    "IN-HP",
    "IN-BR",
    "IN-KL"
  ],
  "score": 8.02456285165782,
  "probabilityCalibrated": 0.5561082178046067,
  "probabilityAltCalibrated": 0.698831534498132
}

Response

The HTTP response body is an object.

Country Subclassification Batch

Country Subclassification Batch code sample :

curl --request POST \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/subclassificationBatch \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","countryIso2":"IN","firstName":"Jannat","lastName":"Rahmani"}]}'

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/subclassificationBatch")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .body("{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"countryIso2\":\"IN\",\"firstName\":\"Jannat\",\"lastName\":\"Rahmani\"}]}")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/subclassificationBatch"

payload = {"personalNames": [
        {
            "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
            "countryIso2": "IN",
            "firstName": "Jannat",
            "lastName": "Rahmani"
        }
    ]}
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/subclassificationBatch", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
  },
  "body": "{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"countryIso2\":\"IN\",\"firstName\":\"Jannat\",\"lastName\":\"Rahmani\"}]}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Returns the most likely geographic subdivision context of of up to 100 first names and a last names. Subdivision are either a country’s states or regions. At the moment this is only supported for India (ISO 3166-1 alpha-2 code “IN”).

Cost : The processing of each object requires 10 credits.

HTTP Request

POST https://v2.namsor.com/NamSorAPIv2/api2/json/subclassificationBatch

Body parameter

{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "countryIso2": "IN",
      "firstName": "Jannat",
      "lastName": "Rahmani"
    }
  ]
}

Request Body

The HTTP request body is required to be a nested array of objects.

The above command returns JSON structured like this:

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Jannat",
      "lastName": "Rahmani",
      "countryIso2": "IN",
      "subClassification": "IN-CH",
      "subClassificationAlt": "IN-PY",
      "subclassificationTop": [
        "IN-CH",
        "IN-PY",
        "IN-UP",
        "IN-AN",
        "IN-RJ",
        "IN-JH",
        "IN-KL",
        "IN-BR",
        "IN-DL",
        "IN-UT"
      ],
      "score": 2.5087208339960445,
      "probabilityCalibrated": 0.3684249074494664,
      "probabilityAltCalibrated": 0.4738687735374875
    }
  ]
}

Response

The HTTP response body is a nested array of objects.

Origin

Origin code sample :

curl --request GET \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/origin/Zanele/Muholi \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json'

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/origin/Zanele/Muholi")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/origin/Zanele/Muholi"

headers = {
 "Accept": "application/json",
 "X-API-KEY": "your-api-key"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/origin/Zanele/Muholi", {
  "method": "GET",
  "headers": {
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Returns the most likely country of origin of a first name and a last name. Note that the “Diaspora” endpoint may be better suited for multicultural countries like the U.S.A., Canada, Russia, etc.

Cost : The processing of each query requires 10 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/origin/{firstName}/{lastName}

Request Parameters

The above command returns JSON structured like this:

{
  "script": "LATIN",
  "id": "859e5b4b-1243-4d5a-902d-ac4d46712ce7",
  "firstName": "Zanele",
  "lastName": "Muholi",
  "countryOrigin": "ZA",
  "countryOriginAlt": "LS",
  "countriesOriginTop": [
    "ZA",
    "LS"
  ],
  "score": 14.109780317889099,
  "regionOrigin": "Africa",
  "topRegionOrigin": "Africa",
  "subRegionOrigin": "Southern Africa",
  "probabilityCalibrated": 0.7807734140287722,
  "probabilityAltCalibrated": 0.8559822284821633
}

Response

The HTTP response body is an object.

Origin Batch

Origin Batch code sample :

curl --request POST \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/originBatch \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Zanele","lastName":"Muholi"}]}'

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/originBatch")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .body("{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Zanele\",\"lastName\":\"Muholi\"}]}")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/originBatch"

payload = {"personalNames": [
        {
            "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
            "firstName": "Zanele",
            "lastName": "Muholi"
        }
    ]}
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/originBatch", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
  },
  "body": "{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Zanele\",\"lastName\":\"Muholi\"}]}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Returns the most likely country of origin of up to 100 first names and a last names. Note that the “Diaspora” endpoint may be better suited for countries like U.S.A, Canada, Australia, New-Zealand and other melting-pots.

Cost : The processing of each object requires 10 credits.

HTTP Request

POST https://v2.namsor.com/NamSorAPIv2/api2/json/originBatch

Body parameter

{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Zanele",
      "lastName": "Muholi"
    }
  ]
}

Request Body

The HTTP request body is required to be a nested array of objects.

The above command returns JSON structured like this:

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Zanele",
      "lastName": "Muholi",
      "countryOrigin": "ZA",
      "countryOriginAlt": "LS",
      "countriesOriginTop": [
        "ZA",
        "LS"
      ],
      "score": 14.109780317889099,
      "regionOrigin": "Africa",
      "topRegionOrigin": "Africa",
      "subRegionOrigin": "Southern Africa",
      "probabilityCalibrated": 0.7807734140304999,
      "probabilityAltCalibrated": 0.8559822288694453
    }
  ]
}

Response

The HTTP response body is a nested array of objects.

Diaspora

Diaspora code sample :

curl --request GET \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/diaspora/US/Subrahmanyan/Chandrasekhar \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json'

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/diaspora/US/Subrahmanyan/Chandrasekhar")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/diaspora/US/Subrahmanyan/Chandrasekhar"

headers = {
 "Accept": "application/json",
 "X-API-KEY": "your-api-key"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/diaspora/US/Subrahmanyan/Chandrasekhar", {
  "method": "GET",
  "headers": {
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Returns the most likely ethnicity or diaspora of a first name and last name, according to the country of residence.

Cost : The processing of each query requires 20 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/diaspora/{countryIso2}/{firstName}/{lastName}

Request Parameters

The above command returns JSON structured like this:

{
  "script": "LATIN",
  "id": "06cea58d-a043-4c33-909d-e78f84a68d75",
  "firstName": "Subrahmanyan",
  "lastName": "Chandrasekhar",
  "score": 36.03940751773479,
  "ethnicityAlt": "Pakistanese",
  "ethnicity": "Indian",
  "lifted": false,
  "countryIso2": "US",
  "ethnicitiesTop": [
    "Indian",
    "Pakistanese"
  ]
}

Response

The HTTP response body is an object.

Diaspora Batch

Diaspora Batch code sample :

curl --request POST \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaBatch \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Subrahmanyan","lastName":"Chandrasekhar","countryIso2":"US"}]}'

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaBatch")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .body("{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Subrahmanyan\",\"lastName\":\"Chandrasekhar\",\"countryIso2\":\"US\"}]}")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaBatch"

payload = {"personalNames": [
        {
            "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
            "firstName": "Subrahmanyan",
            "lastName": "Chandrasekhar",
            "countryIso2": "US"
        }
    ]}
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaBatch", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
  },
  "body": "{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Subrahmanyan\",\"lastName\":\"Chandrasekhar\",\"countryIso2\":\"US\"}]}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Returns the most likely ethnicity or diaspora of up to 100 first names and last names, according to their country of residence.

Cost : The processing of each object requires 20 credits.

HTTP Request

POST https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaBatch

Body parameter

{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Subrahmanyan",
      "lastName": "Chandrasekhar",
      "countryIso2": "US"
    }
  ]
}

Request Body

The HTTP request body is required to be a nested array of objects.

The above command returns JSON structured like this:

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Subrahmanyan",
      "lastName": "Chandrasekhar",
      "score": 36.039400468550376,
      "ethnicityAlt": "Pakistanese",
      "ethnicity": "Indian",
      "lifted": false,
      "countryIso2": "US",
      "ethnicitiesTop": [
        "Indian",
        "Pakistanese"
      ]
    }
  ]
}

Response

The HTTP response body is a nested array of objects.

US Race and Ethnicity

US Race and Ethnicity code sample :

curl --request GET \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicity/Keith/Haring \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json'

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicity/Keith/Haring")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicity/Keith/Haring"

headers = {
 "Accept": "application/json",
 "X-API-KEY": "your-api-key"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicity/Keith/Haring", {
  "method": "GET",
  "headers": {
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Returns the most likely U.S. race or ethnicity of a U.S. resident’s first name and last name.

Cost : The processing of each query requires 10 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicity/{firstName}/{lastName}

Request Parameters

The above command returns JSON structured like this:

{
  "script": "LATIN",
  "id": "3f1efb7d-5141-4ebf-8373-17c4068d22e4",
  "firstName": "Keith",
  "lastName": "Haring",
  "raceEthnicityAlt": "B_NL",
  "raceEthnicity": "W_NL",
  "score": 14.124697493222158,
  "raceEthnicitiesTop": [
    "W_NL",
    "B_NL",
    "A",
    "HL"
  ],
  "probabilityCalibrated": 0.8284804986473213,
  "probabilityAltCalibrated": 0.8890718404096647
}

Response

The HTTP response body is an object.

US Race and Ethnicity Batch

US Race and Ethnicity Batch code sample :

curl --request POST \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityBatch \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Keith","lastName":"Haring","countryIso2":"US"}]}'

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityBatch")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .body("{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Keith\",\"lastName\":\"Haring\",\"countryIso2\":\"US\"}]}")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityBatch"

payload = {"personalNames": [
        {
            "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
            "firstName": "Keith",
            "lastName": "Haring",
            "countryIso2": "US"
        }
    ]}
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityBatch", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
  },
  "body": "{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Keith\",\"lastName\":\"Haring\",\"countryIso2\":\"US\"}]}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Returns the most likely U.S. race or ethnicity of up to 100 U.S. resident’s first names and last names.

Cost : The processing of each object requires 10 credits.

HTTP Request

POST https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityBatch

Body parameter

{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US"
    }
  ]
}

Request Body

The HTTP request body is required to be a nested array of objects.

The above command returns JSON structured like this:

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Keith",
      "lastName": "Haring",
      "raceEthnicityAlt": "B_NL",
      "raceEthnicity": "W_NL",
      "score": 14.124697493222158,
      "raceEthnicitiesTop": [
        "W_NL",
        "B_NL",
        "A",
        "HL"
      ],
      "probabilityCalibrated": 0.8284804986473213,
      "probabilityAltCalibrated": 0.8890718404096647
    }
  ]
}

Response

The HTTP response body is a nested array of objects.

US Race and Ethnicity ZIP

US Race and Ethnicity ZIP code sample :

curl --request GET \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityZIP5/Makoto/Iwamatsu/10019 \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json'

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityZIP5/Makoto/Iwamatsu/10019")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityZIP5/Makoto/Iwamatsu/10019"

headers = {
 "Accept": "application/json",
 "X-API-KEY": "your-api-key"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityZIP5/Makoto/Iwamatsu/10019", {
  "method": "GET",
  "headers": {
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Returns the most likely U.S. race or ethnicity of a U.S. resident’s first name and last name, using their ZIP code.

Cost : The processing of each query requires 10 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityZIP5/{firstName}/{lastName}/{zip5Code}

Request Parameters

The above command returns JSON structured like this:

{
  "script": "LATIN",
  "id": "d2e92047-c3ce-4363-bf3c-a54757d372b2",
  "firstName": "Makoto",
  "lastName": "Iwamatsu",
  "raceEthnicityAlt": "HL",
  "raceEthnicity": "A",
  "score": 32.90567784847702,
  "raceEthnicitiesTop": [
    "A",
    "HL",
    "B_NL",
    "W_NL"
  ],
  "probabilityCalibrated": 0.9376434608736617,
  "probabilityAltCalibrated": 0.9817007157185398
}

Response

The HTTP response body is an object.

US Race and Ethnicity ZIP Batch

US Race and Ethnicity ZIP Batch code sample :

curl --request POST \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/usZipRaceEthnicityBatch \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Makoto","lastName":"Iwamatsu","countryIso2":"JP","zipCode":"10019"}]}'

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/usZipRaceEthnicityBatch")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .body("{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Makoto\",\"lastName\":\"Iwamatsu\",\"countryIso2\":\"JP\",\"zipCode\":\"10019\"}]}")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/usZipRaceEthnicityBatch"

payload = {"personalNames": [
        {
            "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
            "firstName": "Makoto",
            "lastName": "Iwamatsu",
            "countryIso2": "JP",
            "zipCode": "10019"
        }
    ]}
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/usZipRaceEthnicityBatch", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
  },
  "body": "{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Makoto\",\"lastName\":\"Iwamatsu\",\"countryIso2\":\"JP\",\"zipCode\":\"10019\"}]}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Returns the most likely U.S. race or ethnicity of up to 100 U.S. resident’s first names and last names, using their ZIP code.

Cost : The processing of each object requires 10 credits.

HTTP Request

POST https://v2.namsor.com/NamSorAPIv2/api2/json/usZipRaceEthnicityBatch

Body parameter

{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Makoto",
      "lastName": "Iwamatsu",
      "countryIso2": "JP",
      "zipCode": "10019"
    }
  ]
}

Request Body

The HTTP request body is required to be a nested array of objects.

The above command returns JSON structured like this:

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Makoto",
      "lastName": "Iwamatsu",
      "raceEthnicityAlt": "HL",
      "raceEthnicity": "A",
      "score": 33.10409827435145,
      "raceEthnicitiesTop": [
        "A",
        "HL",
        "B_NL",
        "W_NL"
      ],
      "probabilityCalibrated": 0.943439227727173,
      "probabilityAltCalibrated": 0.9817007157185398
    }
  ]
}

Response

The HTTP response body is a nested array of objects.

Corridor

Corridor code sample :

curl --request GET \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/corridor/GB/Ada/Lovelace/US/Nicolas/Tesla \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json'

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/corridor/GB/Ada/Lovelace/US/Nicolas/Tesla")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/corridor/GB/Ada/Lovelace/US/Nicolas/Tesla"

headers = {
 "Accept": "application/json",
 "X-API-KEY": "your-api-key"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/corridor/GB/Ada/Lovelace/US/Nicolas/Tesla", {
  "method": "GET",
  "headers": {
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Returns complete analysis of a cross border interactions between two names using their geographic context. The sender is the one who initiated the interaction (from) while the receiver is the one intended to receive the interaction (to).

Cost : The processing of each query requires 20 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/corridor/{countryIso2From}/{firstNameFrom}/{lastNameFrom}/{countryIso2To}/{firstNameTo}/{lastNameTo}

Request Parameters

The above command returns JSON structured like this:

{
  "id": null,
  "firstLastNameGeoFromGender": {
    "script": "LATIN",
    "id": "781cc5e4-aa61-4a04-bd14-4b512120817a",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "likelyGender": "female",
    "genderScale": 0.9667738179638148,
    "score": 20.98847600479561,
    "probabilityCalibrated": 0.9833869089819074
  },
  "firstLastNameGeoToGender": {
    "script": "LATIN",
    "id": "d5d87a0f-8d21-4cf6-98a2-2636a669ddd6",
    "firstName": "Nicolas",
    "lastName": "Tesla",
    "likelyGender": "male",
    "genderScale": -0.9915797101926913,
    "score": 30.224379416275056,
    "probabilityCalibrated": 0.9957898550963457
  },
  "firstLastNameGeoFromOrigin": {
    "script": "LATIN",
    "id": "781cc5e4-aa61-4a04-bd14-4b512120817a",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "countryOrigin": "IE",
    "countryOriginAlt": "GB",
    "countriesOriginTop": [
      "IE",
      "GB"
    ],
    "score": 2.568304424015469,
    "regionOrigin": "Europe",
    "topRegionOrigin": "Europe",
    "subRegionOrigin": "Northern Europe",
    "probabilityCalibrated": 0.45562779224760414,
    "probabilityAltCalibrated": 0.6327518248452595
  },
  "firstLastNameGeoToOrigin": {
    "script": "LATIN",
    "id": "d5d87a0f-8d21-4cf6-98a2-2636a669ddd6",
    "firstName": "Nicolas",
    "lastName": "Tesla",
    "countryOrigin": "FR",
    "countryOriginAlt": "GR",
    "countriesOriginTop": [
      "FR",
      "GR"
    ],
    "score": 1.454789764445522,
    "regionOrigin": "Europe",
    "topRegionOrigin": "Europe",
    "subRegionOrigin": "Western Europe",
    "probabilityCalibrated": 0.44774495967210787,
    "probabilityAltCalibrated": 0.4771001024099368
  },
  "firstLastNameGeoFromDiaspora": {
    "script": "LATIN",
    "id": "781cc5e4-aa61-4a04-bd14-4b512120817a",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "score": 32.41666571408284,
    "ethnicityAlt": "TrinidadTobago",
    "ethnicity": "British",
    "lifted": false,
    "countryIso2": "GB",
    "ethnicitiesTop": [
      "British",
      "TrinidadTobago"
    ]
  },
  "firstLastNameGeoToDiaspora": {
    "script": "LATIN",
    "id": "d5d87a0f-8d21-4cf6-98a2-2636a669ddd6",
    "firstName": "Nicolas",
    "lastName": "Tesla",
    "score": 1.1421870006029051,
    "ethnicityAlt": "Jewish",
    "ethnicity": "Italian",
    "lifted": false,
    "countryIso2": "US",
    "ethnicitiesTop": [
      "Italian",
      "Jewish"
    ]
  }
}

Response

The HTTP response body is an object.

Corridor Batch

Corridor Batch code sample :

curl --request POST \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/corridorBatch \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"corridorFromTo":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstLastNameGeoFrom":{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Ada","lastName":"Lovelace","countryIso2":"GB"},"firstLastNameGeoTo":{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Nicolas","lastName":"Tesla","countryIso2":"US"}}]}'

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/corridorBatch")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .body("{\"corridorFromTo\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstLastNameGeoFrom\":{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Ada\",\"lastName\":\"Lovelace\",\"countryIso2\":\"GB\"},\"firstLastNameGeoTo\":{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Nicolas\",\"lastName\":\"Tesla\",\"countryIso2\":\"US\"}}]}")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/corridorBatch"

payload = {"corridorFromTo": [
        {
            "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
            "firstLastNameGeoFrom": {
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
                "firstName": "Ada",
                "lastName": "Lovelace",
                "countryIso2": "GB"
            },
            "firstLastNameGeoTo": {
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
                "firstName": "Nicolas",
                "lastName": "Tesla",
                "countryIso2": "US"
            }
        }
    ]}
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/corridorBatch", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
  },
  "body": "{\"corridorFromTo\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstLastNameGeoFrom\":{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Ada\",\"lastName\":\"Lovelace\",\"countryIso2\":\"GB\"},\"firstLastNameGeoTo\":{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Nicolas\",\"lastName\":\"Tesla\",\"countryIso2\":\"US\"}}]}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Returns complete analysis of up to 100 cross border interactions between two names using their geographic context. The sender is the one who initiated the interaction (from) while the receiver is the one intended to receive the interaction (to).

Cost : The processing of each object requires 20 credits.

HTTP Request

POST https://v2.namsor.com/NamSorAPIv2/api2/json/corridorBatch

Body parameter

{
  "corridorFromTo": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstLastNameGeoFrom": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "countryIso2": "GB"
      },
      "firstLastNameGeoTo": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
        "firstName": "Nicolas",
        "lastName": "Tesla",
        "countryIso2": "US"
      }
    }
  ]
}

Request Body

The HTTP request body is required to be a nested array of objects.

The above command returns JSON structured like this:

{
  "corridorFromTo": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstLastNameGeoFromGender": {
        "script": "LATIN",
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "likelyGender": "female",
        "genderScale": 0.9667738179638148,
        "score": 20.98847600479561,
        "probabilityCalibrated": 0.9833869089819074
      },
      "firstLastNameGeoToGender": {
        "script": "LATIN",
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
        "firstName": "Nicolas",
        "lastName": "Tesla",
        "likelyGender": "male",
        "genderScale": -0.9915797101926913,
        "score": 30.224379416275056,
        "probabilityCalibrated": 0.9957898550963457
      },
      "firstLastNameGeoFromOrigin": {
        "script": "LATIN",
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "countryOrigin": "IE",
        "countryOriginAlt": "GB",
        "countriesOriginTop": [
          "IE",
          "GB"
        ],
        "score": 2.568304424015469,
        "regionOrigin": "Europe",
        "topRegionOrigin": "Europe",
        "subRegionOrigin": "Northern Europe",
        "probabilityCalibrated": 0.45562779224760414,
        "probabilityAltCalibrated": 0.6327518248452595
      },
      "firstLastNameGeoToOrigin": {
        "script": "LATIN",
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
        "firstName": "Nicolas",
        "lastName": "Tesla",
        "countryOrigin": "FR",
        "countryOriginAlt": "GR",
        "countriesOriginTop": [
          "FR",
          "GR"
        ],
        "score": 1.454789764445522,
        "regionOrigin": "Europe",
        "topRegionOrigin": "Europe",
        "subRegionOrigin": "Western Europe",
        "probabilityCalibrated": 0.44774495967210787,
        "probabilityAltCalibrated": 0.4771001024099368
      },
      "firstLastNameGeoFromDiaspora": {
        "script": "LATIN",
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "score": 32.41686703300403,
        "ethnicityAlt": "TrinidadTobago",
        "ethnicity": "British",
        "lifted": false,
        "countryIso2": "GB",
        "ethnicitiesTop": [
          "British",
          "TrinidadTobago"
        ]
      },
      "firstLastNameGeoToDiaspora": {
        "script": "LATIN",
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
        "firstName": "Nicolas",
        "lastName": "Tesla",
        "score": 1.1421954239282939,
        "ethnicityAlt": "Jewish",
        "ethnicity": "Italian",
        "lifted": false,
        "countryIso2": "US",
        "ethnicitiesTop": [
          "Italian",
          "Jewish"
        ]
      }
    }
  ]
}

Response

The HTTP response body is a nested array of objects.

Gender

Namsor’s name checking API can help you determine the probability of a person being male or female based on their name. We offer many processing options for gender determination, the name can either be provided: as a full name, as a first name and a last name. In addition to the name you may specify the country of origin to improve accuracy.

Our API also supports Chinese names, Japanese names and a large number of additional alphabets*.


Try out Gender features

Gender

Gender code sample :

curl --request GET \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/gender/Rosalind/Franklin \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json'

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/gender/Rosalind/Franklin")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/gender/Rosalind/Franklin"

headers = {
 "Accept": "application/json",
 "X-API-KEY": "your-api-key"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/gender/Rosalind/Franklin", {
  "method": "GET",
  "headers": {
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Returns the most likely gender of a first name and a last name.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/gender/{firstName}/{lastName}

Request Parameters

The above command returns JSON structured like this:

{
  "script": "LATIN",
  "id": "86767222-94ba-4ee4-8ade-6755228c77ca",
  "firstName": "Rosalind",
  "lastName": "Franklin",
  "likelyGender": "female",
  "genderScale": 0.9730217066962004,
  "score": 21.904701285428477,
  "probabilityCalibrated": 0.9865108533481002
}

Response

The HTTP response body is an object.

Gender Batch

Gender Batch code sample :

curl --request POST \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/genderBatch \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Rosalind","lastName":"Franklin"}]}'

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderBatch")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .body("{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Rosalind\",\"lastName\":\"Franklin\"}]}")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderBatch"

payload = {"personalNames": [
        {
            "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
            "firstName": "Rosalind",
            "lastName": "Franklin"
        }
    ]}
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderBatch", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
  },
  "body": "{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Rosalind\",\"lastName\":\"Franklin\"}]}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Returns the most likely gender of up to 100 first names and last names.

Cost : The processing of each object requires 1 credits.

HTTP Request

POST https://v2.namsor.com/NamSorAPIv2/api2/json/genderBatch

Body parameter

{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Rosalind",
      "lastName": "Franklin"
    }
  ]
}

Request Body

The HTTP request body is required to be a nested array of objects.

The above command returns JSON structured like this:

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Rosalind",
      "lastName": "Franklin",
      "likelyGender": "female",
      "genderScale": 0.9730217066962004,
      "score": 21.904701285428477,
      "probabilityCalibrated": 0.9865108533481002
    }
  ]
}

Response

The HTTP response body is a nested array of objects.

Gender Geo

Gender Geo code sample :

curl --request GET \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeo/Sofia/Kovalevskaya/RU \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json'

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeo/Sofia/Kovalevskaya/RU")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeo/Sofia/Kovalevskaya/RU"

headers = {
 "Accept": "application/json",
 "X-API-KEY": "your-api-key"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeo/Sofia/Kovalevskaya/RU", {
  "method": "GET",
  "headers": {
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Returns the most likely gender of a first name and a last name using its geographic context.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeo/{firstName}/{lastName}/{countryIso2}

Request Parameters

The above command returns JSON structured like this:

{
  "script": "LATIN",
  "id": "1524c414-ee6a-4a07-8056-b8dfe483850d",
  "firstName": "Sofia",
  "lastName": "Kovalevskaya",
  "likelyGender": "female",
  "genderScale": 0.9938175581348969,
  "score": 39.01304923594625,
  "probabilityCalibrated": 0.9969087790674485
}

Response

The HTTP response body is an object.

Gender Geo Batch

Gender Geo Batch code sample :

curl --request POST \
  --url https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeoBatch \
  --header 'X-API-KEY: your-api-key' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Sofia","lastName":"Kovalevskaya","countryIso2":"RU"}]}'

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeoBatch")
  .header("Content-Type", "application/json")
  .header("Accept", "application/json")
  .header("X-API-KEY", "your-api-key")
  .body("{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Sofia\",\"lastName\":\"Kovalevskaya\",\"countryIso2\":\"RU\"}]}")
  .asString();

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeoBatch"

payload = {"personalNames": [
        {
            "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
            "firstName": "Sofia",
            "lastName": "Kovalevskaya",
            "countryIso2": "RU"
        }
    ]}
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-KEY": "your-api-key"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)