NAV Navigation
Shell Java Python JavaScript

Namsor API 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 APIs 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

Introduction

About

API Requests and Responses

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 :

Repeated Operations Tolerance

Our API features smart processing and it will not charge for analyzing 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:

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:

Error CodeMeaningDescription
401UnauthorizedMissing or incorrect API Key.
403ForbiddenAPI Limit Reached or API Key Disabled.
404Not FoundThe specified route could not be found.
500Internal Server ErrorServer error. Try again later.

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

NameTypeRequiredDescription
personalNameFullStringtrueFull name (first name and last name) or surname

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.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
nameStringThe provided full name
scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available
countryStringMost likely country of origin, in ISO 3166-1 alpha-2 format
countryAltStringSecond most likely country of origin, in ISO 3166-1 alpha-2 format
regionStringMost likely region of origin
topRegionStringMost likely region of origin (alternative classification)
subRegionStringMost likely sub region of origin
countriesTopArrayTop 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for country)
probabilityAltCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for countryAlt)

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.

NameTypeRequiredDescription
idStringUnique identifier
nameStringtrueFull name (first name and last name) or surname

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.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
nameStringSubmitted full name
scoreNumberHigher implies a more reliable result, score is not normalized
countryStringMost likely country of origin, in ISO 3166-1 alpha-2 format
countryAltStringSecond most likely country of origin, in ISO 3166-1 alpha-2 format
regionStringMost likely region of origin
topRegionStringMost likely region of origin (alternative classification)
subRegionStringMost likely subregion of origin
countriesTopArrayTop 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for country)
probabilityAltCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for countryAlt)

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

NameTypeRequiredDescription
countryIso2StringtrueMost likely country of origin, in ISO 3166-1 alpha-2 format
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)

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.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
countryIso2StringSubmitted country of origin, in ISO 3166-1 alpha-2 format
subClassificationStringMost likely subclassification, in ISO 3166-2 alpha-2 format (country-region)
subClassificationAltStringSecond most likely subclassification, in ISO 3166-2 alpha-2 format (country-region)
subclassificationTopArrayTop 10 most likely subclassification, in ISO 3166-2 alpha-2 format (country-region), sorted from most likely to least likely
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for subClassification)
probabilityAltCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for subClassificationAlt)

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.

NameTypeRequiredDescription
idStringProvided unique identifier
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)
countryIso2StringtrueMost likely country of origin, in ISO 3166-1 alpha-2 format

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.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
countryIso2StringSubmitted country of origin, in ISO 3166-1 alpha-2 format
subClassificationStringMost likely subclassification, in ISO 3166-2 alpha-2 format (country-region)
subClassificationAltStringSecond most likely subclassification, in ISO 3166-2 alpha-2 format (country-region)
subclassificationTopArrayTop 10 most likely subclassification, in ISO 3166-2 alpha-2 format (country-region), sorted from most likely to least likely
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for subClassification)
probabilityAltCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for subClassificationAlt)

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

NameTypeRequiredDescription
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)

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.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
countryOriginStringMost likely country of origin, in ISO 3166-1 alpha-2 format
countryOriginAltStringSecond most likely country of origin, in ISO 3166-1 alpha-2 format
countriesOriginTopArrayTop 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely
scoreNumberHigher implies a more reliable result, score is not normalized
regionOriginStringMost likely region of origin
topRegionOriginStringMost likely region of origin (alternative classification)
subRegionOriginStringMost likely subregion of origin
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for countryOrigin)
probabilityAltCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for countryOriginAlt)

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.

NameTypeRequiredDescription
idStringUnique identifier
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)

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.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
countryOriginStringMost likely country of origin, in ISO 3166-1 alpha-2 format
countryOriginAltStringSecond most likely country of origin, in ISO 3166-1 alpha-2 format
countriesOriginTopArrayTop 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely
scoreNumberHigher implies a more reliable result, score is not normalized
regionOriginStringMost likely region of origin
topRegionOriginStringMost likely region of origin (alternative classification)
subRegionOriginStringMost likely subregion of origin
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for countryOrigin)
probabilityAltCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for countryOriginAlt)

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

NameTypeRequiredDescription
countryIso2StringtrueCountry of residence, in ISO 3166-1 alpha-2 format
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)

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.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
scoreNumberHigher implies a more reliable result, score is not normalized
ethnicityAltStringSecond most likely ethnicity
ethnicityStringMost likely ethnicity
liftedBooleanIndicates if the result of the “ethnicity” field is based on machine learning only, or further lifted as a known fact by a country-specific rule
countryIso2StringCountry of residence, in ISO 3166-1 alpha-2 format
ethnicitiesTopArrayTop 10 most likely etchnicities, order from most likely to least likely
probabilityCalibratedNumberThe calibrated probability for ethnicity to have been guessed correctly. -1 = still calibrating.
probabilityAltCalibratedNumberThe calibrated probability for ethnicity OR ethnicityAlt to have been guessed correctly. -1 = still calibrating.

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.

NameTypeRequiredDescription
idStringUnique identifier
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)
countryIso2StringtrueCountry of residence, in ISO 3166-1 alpha-2 format

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.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
scoreNumberHigher implies a more reliable result, score is not normalized
ethnicityAltStringSecond most likely ethnicity
ethnicityStringMost likely ethnicity
liftedBooleanIndicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule
countryIso2StringCountry of residence, in ISO 3166-1 alpha-2 format
ethnicitiesTopArrayTop 10 most likely etchnicities, order from most likely to least likely
probabilityCalibratedNumberThe calibrated probability for ethnicity to have been guessed correctly. -1 = still calibrating.
probabilityAltCalibratedNumberThe calibrated probability for ethnicity OR ethnicityAlt to have been guessed correctly. -1 = still calibrating.

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

NameTypeRequiredDescription
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)

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.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
raceEthnicityAltStringSecond most likely ethnicity (U.S. race and ethnicity categorization)“W_NL”, “HL”, “A”, “B_NL”, “AI_AN” or “PI”
raceEthnicityStringMost likely ethnicity (U.S. race and ethnicity categorization)“W_NL”, “HL”, “A”, “B_NL”, “AI_AN” or “PI”
scoreNumberHigher implies a more reliable result, score is not normalized
raceEthnicitiesTopArrayMost likely ethnicity, sorted from most likely to least likely (U.S. race and ethnicity categorization)
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for raceEthnicity)
probabilityAltCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for raceEthnicityAlt)

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.

NameTypeRequiredDescription
idStringUnique identifier
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)
countryIso2StringtrueMost likely country of origin, in ISO 3166-1 alpha-2 format

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.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
raceEthnicityAltStringSecond most likely ethnicity (U.S. race and ethnicity categorization)“W_NL”, “HL”, “A”, “B_NL”, “AI_AN” or “PI”
raceEthnicityStringMost likely ethnicity (U.S. race and ethnicity categorization)“W_NL”, “HL”, “A”, “B_NL”, “AI_AN” or “PI”
scoreNumberHigher implies a more reliable result, score is not normalized
raceEthnicitiesTopArrayMost likely ethnicity, sorted from most likely to least likely (U.S. race and ethnicity categorization)
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for raceEthnicity)
probabilityAltCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for raceEthnicityAlt)

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

NameTypeRequiredDescription
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)
zip5CodeStringtrue5 digit zip code

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.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
raceEthnicityAltStringSecond most likely ethnicity (U.S. race and ethnicity categorization)“W_NL”, “HL”, “A”, “B_NL”, “AI_AN” or “PI”
raceEthnicityStringMost likely ethnicity (U.S. race and ethnicity categorization)“W_NL”, “HL”, “A”, “B_NL”, “AI_AN” or “PI”
scoreNumberHigher implies a more reliable result, score is not normalized
raceEthnicitiesTopArrayMost likely ethnicity, sorted from most likely to least likely (U.S. race and ethnicity categorization)
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for raceEthnicity)
probabilityAltCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for raceEthnicityAlt)

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.

NameTypeRequiredDescription
idStringUnique identifier
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)
countryIso2StringtrueMost likely country of origin, in ISO 3166-1 alpha-2 format
zipCodeStringtrue5 digit zip code

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.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringFirst name (or given name)
lastNameStringLast name (or family name)
raceEthnicityAltStringSecond most likely ethnicity (U.S. race and ethnicity categorization)“W_NL”, “HL”, “A”, “B_NL”, “AI_AN” or “PI”
raceEthnicityStringMost likely ethnicity (U.S. race and ethnicity categorization)“W_NL”, “HL”, “A”, “B_NL”, “AI_AN” or “PI”
scoreNumberHigher implies a more reliable result, score is not normalized
raceEthnicitiesTopArrayMost likely ethnicity, sorted from most likely to least likely (U.S. race and ethnicity categorization)
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for raceEthnicity)
probabilityAltCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for raceEthnicityAlt)

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

NameTypeRequiredDescription
countryIso2FromStringtrueCountry of origin of the sender, in ISO 3166-1 alpha-2 format
firstNameFromStringtrueFirst name (or given name) of the sender
lastNameFromStringtrueLast name (or family name) of the sender
countryIso2ToStringtrueCountry of origin of the receiver, in ISO 3166-1 alpha-2 format
firstNameToStringtrueFirst name (or given name) of the receiver
lastNameToStringtrueLast name (or family name) of the receiver

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.

NameTypeDescriptionEnumerators
idStringUnique identifier
FirstLastNameGenderedOutObject
    {…}.scriptStringCharacter set used for analysis
    {…}.idStringUnique identifier
    {…}.firstNameStringFirst name (or given name)
    {…}.lastNameStringLast name (or family name)
    {…}.likelyGenderStringMost likely gender“male”, “female” or “unknown”
    {…}.genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
    {…}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available
    {…}.probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1
FirstLastNameOriginedOutObject
    {…}.scriptStringCharacter set used for analysis
    {…}.idStringUnique identifier
    {…}.firstNameStringFirst name (or given name)
    {…}.lastNameStringLast name (or family name)
    {…}.countryOriginStringMost likely country of origin, in ISO 3166-1 alpha-2 format
    {…}.countryOriginAltStringSecond most likely country of origin, in ISO 3166-1 alpha-2 format
    {…}.countriesOriginTopArrayTop 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely
    {…}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available
    {…}.regionOriginStringMost likely region of origin
    {…}.topRegionOriginStringMost likely region of origin (alternative classification)
    {…}.subRegionOriginStringMost likely subregion of origin
    {…}.probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for countryOrigin)
    {…}.probabilityAltCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for countryOriginAlt)
FirstLastNameDiasporaedOutObject
    {…}.scriptStringCharacter set used for analysis
    {…}.idStringUnique identifier
    {…}.firstNameStringFirst name (or given name)
    {…}.lastNameStringLast name (or family name)
    {…}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available
    {…}.ethnicityAltStringSecond most likely ethnicity
    {…}.ethnicityStringMost likely ethnicity
    {…}.liftedBooleanIndicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule
    {…}.countryIso2StringMost likely country of origin, in ISO 3166-1 alpha-2 format
    {…}.ethnicitiesTopArrayTop 10 most likely etchnicities, order from most likely to least likely
    {…}.probabilityCalibratedNumberThe calibrated probability for ethnicity to have been guessed correctly. -1 = still calibrating.
    {…}.probabilityAltCalibratedNumberThe calibrated probability for ethnicity OR ethnicityAlt to have been guessed correctly. -1 = still calibrating.
scriptStringCharacter set used for analysis

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.

NameTypeRequiredDescription
idStringUnique identifier
firstLastNameGeoFromObject
    {…}.idStringUnique identifier
    {…}.firstNameStringtrueFirst name (or given name) of the sender
    {…}.lastNameStringtrueLast name (or family name) of the sender
    {…}.countryIso2StringtrueCountry of origin of the sender, in ISO 3166-1 alpha-2 format
firstLastNameGeoToObject
    {…}.idStringUnique identifier
    {…}.firstNameStringtrueFirst name (or given name) of the receiver
    {…}.lastNameStringtrueLast name (or family name) of the receiver
    {…}.countryIso2StringtrueCountry of origin of the receiver, in ISO 3166-1 alpha-2 format

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.

NameTypeDescriptionEnumerators
idStringUnique identifier
FirstLastNameGenderedOutObject
    {…}.scriptStringCharacter set used for analysis
    {…}.idStringUnique identifier
    {…}.firstNameStringFirst name (or given name)
    {…}.lastNameStringLast name (or family name)
    {…}.likelyGenderStringMost likely gender“male”, “female” or “unknown”
    {…}.genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
    {…}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available
    {…}.probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1
FirstLastNameOriginedOutObject
    {…}.scriptStringCharacter set used for analysis
    {…}.idStringUnique identifier
    {…}.firstNameStringFirst name (or given name)
    {…}.lastNameStringLast name (or family name)
    {…}.countryOriginStringMost likely country of origin, in ISO 3166-1 alpha-2 format
    {…}.countryOriginAltStringSecond most likely country of origin, in ISO 3166-1 alpha-2 format
    {…}.countriesOriginTopArrayTop 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely
    {…}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available
    {…}.regionOriginStringMost likely region of origin
    {…}.topRegionOriginStringMost likely region of origin (alternative classification)
    {…}.subRegionOriginStringMost likely subregion of origin
    {…}.probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for countryOrigin)
    {…}.probabilityAltCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1 (for countryOriginAlt)
FirstLastNameDiasporaedOutObject
    {…}.scriptStringCharacter set used for analysis
    {…}.idStringUnique identifier
    {…}.firstNameStringFirst name (or given name)
    {…}.lastNameStringLast name (or family name)
    {…}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available
    {…}.ethnicityAltStringSecond most likely ethnicity
    {…}.ethnicityStringMost likely ethnicity
    {…}.liftedBooleanIndicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule
    {…}.countryIso2StringMost likely country of origin, in ISO 3166-1 alpha-2 format
    {…}.ethnicitiesTopArrayTop 10 most likely etchnicities, order from most likely to least likely
    {…}.probabilityCalibratedNumberThe calibrated probability for ethnicity to have been guessed correctly. -1 = still calibrating.
    {…}.probabilityAltCalibratedNumberThe calibrated probability for ethnicity OR ethnicityAlt to have been guessed correctly. -1 = still calibrating.
scriptStringCharacter set used for analysis

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

NameTypeRequiredDescription
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)

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.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
likelyGenderStringMost likely gender“male”, “female” or “unknown”
genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

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.

NameTypeRequiredDescription
idStringUnique identifier
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)

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.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
likelyGenderStringMost likely gender“male”, “female” or “unknown”
genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

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

NameTypeRequiredDescription
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)
countryIso2StringtrueMost likely country of origin, in ISO 3166-1 alpha-2 format

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.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
likelyGenderStringMost likely gender“male”, “female” or “unknown”
genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

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)
fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeoBatch", {
"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\":\"Sofia\",\"lastName\":\"Kovalevskaya\",\"countryIso2\":\"RU\"}]}"
})
.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 using their geographic context.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Sofia",
"lastName": "Kovalevskaya",
"countryIso2": "RU"
}
]
}

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)
countryIso2StringtrueMost likely country of origin, in ISO 3166-1 alpha-2 format

The above command returns JSON structured like this:

{
"personalNames": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Sofia",
"lastName": "Kovalevskaya",
"likelyGender": "female",
"genderScale": 0.9938175581348969,
"score": 39.01304923594625,
"probabilityCalibrated": 0.9969087790674485
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
likelyGenderStringMost likely gender“male”, “female” or “unknown”
genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

Gender Full Name

Gender Full Name code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderFull/Alan%20Turing \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFull/Alan%20Turing")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderFull/Alan%20Turing"

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/genderFull/Alan%20Turing", {
"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 full name.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/genderFull/{fullName}

Request Parameters

NameTypeRequiredDescription
fullNameStringtrueFull name (first name and last name)

The above command returns JSON structured like this:

{
"script": "LATIN",
"id": "ad176dc1-0a45-41f6-aa3a-5bdd6246b453",
"name": "Alan Turing",
"likelyGender": "male",
"genderScale": -0.9831427708411884,
"score": 19.119365238807685,
"probabilityCalibrated": 0.9915713854205942
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
nameStringSubmitted full name
likelyGenderStringMost likely gender“male”, “female” or “unknown”
genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

Gender Full Name Batch

Gender Full Name Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullBatch \
--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":"Alan Turing"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullBatch")
.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\":\"Alan Turing\"}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Alan Turing"
}
]}
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/genderFullBatch", {
"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\":\"Alan Turing\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns the most likely gender of up to 100 full names.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

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

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
nameStringtrueFull name (first name and last name)

The above command returns JSON structured like this:

{
"personalNames": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Alan Turing",
"likelyGender": "male",
"genderScale": -0.9831427708411884,
"score": 19.119365238807685,
"probabilityCalibrated": 0.9915713854205942
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
nameStringSubmitted full name
likelyGenderStringMost likely gender“male”, “female” or “unknown”
genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

Gender Full Name Geo

Gender Full Name Geo code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeo/Maryam%20Mirzakhani/IR \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeo/Maryam%20Mirzakhani/IR")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeo/Maryam%20Mirzakhani/IR"

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/genderFullGeo/Maryam%20Mirzakhani/IR", {
"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 full name, according to its geographic context.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeo/{fullName}/{countryIso2}

Request Parameters

NameTypeRequiredDescription
fullNameStringtrueFull name (first name and last name)
countryIso2StringtrueMost likely country of origin, in ISO 3166-1 alpha-2 format

The above command returns JSON structured like this:

{
"script": "LATIN",
"id": "b8737595-afe6-4217-a80e-d1b863de2704",
"name": "Maryam Mirzakhani",
"likelyGender": "female",
"genderScale": 0.7336489993843776,
"score": 8.702861844637805,
"probabilityCalibrated": 0.8668244996921888
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
nameStringSubmitted full name
likelyGenderStringMost likely gender“male”, “female” or “unknown”
genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

Gender Full Name Geo Batch

Gender Full Name Geo Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeoBatch \
--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":"Maryam Mirzakhani","countryIso2":"IR"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeoBatch")
.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\":\"Maryam Mirzakhani\",\"countryIso2\":\"IR\"}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Maryam Mirzakhani",
"countryIso2": "IR"
}
]}
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/genderFullGeoBatch", {
"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\":\"Maryam Mirzakhani\",\"countryIso2\":\"IR\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns the most likely gender of up to 100 full names, according to their geographic context.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Maryam Mirzakhani",
"countryIso2": "IR"
}
]
}

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
nameStringtrueFull name (first name and last name)
countryIso2StringtrueMost likely country of origin, in ISO 3166-1 alpha-2 format

The above command returns JSON structured like this:

{
"personalNames": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Maryam Mirzakhani",
"likelyGender": "female",
"genderScale": 0.7336489993843776,
"score": 8.702861844637805,
"probabilityCalibrated": 0.8668244996921888
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
nameStringSubmitted full name
likelyGenderStringMost likely gender“male”, “female” or “unknown”
genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

Name Type

Namsor provides a specialized proper name type determination API, it is trained to analyse proper names and infer if they are personal names or brand names. Differentiate individuals from companies base on their name in order to automate processes, evaluate references to names or leverage deeper insight into an audience. To yield improved results you may indicate the name’s country of origin.


Try out Name Type features

Name Type

Name Type code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/nameType/Zippo \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/nameType/Zippo")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

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

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/nameType/Zippo", {
"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 type of a submitted proper noun. Ex: John Smith = personal name, Namsor = brand name.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/nameType/{properNoun}

Request Parameters

NameTypeRequiredDescription
properNounStringtrueA proper noun (person, brand, etc.)

The above command returns JSON structured like this:

{
"script": "LATIN",
"id": "a88b1bf1-56f1-40d3-84db-4daf57121b1d",
"name": "Zippo",
"commonType": "brand-name",
"commonTypeAlt": "toponym",
"score": 7.717552234146745
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
nameStringSubmitted proper noun
commonTypeStringMost likely type of the proper noun
commonTypeAltStringSecond most likely type of the proper noun
scoreNumberHigher implies a more reliable result, score is not normalized

Name Type Batch

Name Type Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"properNouns":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","name":"Zippo"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeBatch")
.header("Content-Type", "application/json")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.body("{\"properNouns\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"name\":\"Zippo\"}]}")
.asString();
import requests

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

payload = {"properNouns": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Zippo"
}
]}
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/nameTypeBatch", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"X-API-KEY": "your-api-key"
},
"body": "{\"properNouns\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"name\":\"Zippo\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns the type of up to 100 submitted proper nouns. Ex: John Smith = personal name, Namsor = brand name.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

{
"properNouns": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Zippo"
}
]
}

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
nameStringtrueA proper noun (person, brand, etc.)

The above command returns JSON structured like this:

{
"properNouns": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Zippo",
"commonType": "brand-name",
"commonTypeAlt": "toponym",
"score": 7.717552576402805
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
nameStringSubmitted proper noun
commonTypeStringMost likely type of the proper noun
commonTypeAltStringSecond most likely type of the proper noun
scoreNumberHigher implies a more reliable result, score is not normalized

Name Type Geo

Name Type Geo code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeGeo/Edi%20Gathegi/KE \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeGeo/Edi%20Gathegi/KE")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeGeo/Edi%20Gathegi/KE"

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/nameTypeGeo/Edi%20Gathegi/KE", {
"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 type of up to 100 submitted proper nouns using its geographic context. Ex: John Smith = personal name, Namsor = brand name.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeGeo/{properNoun}/{countryIso2}

Request Parameters

NameTypeRequiredDescription
properNounStringtrueA proper noun (person, brand, etc.)
countryIso2StringtrueMost likely country of origin, in ISO 3166-1 alpha-2 format

The above command returns JSON structured like this:

{
"script": "LATIN",
"id": "a941ea3f-3b3c-4ff1-af28-c01b086b7d79",
"name": "Edi Gathegi",
"commonType": "anthroponym",
"commonTypeAlt": "brand-name",
"score": 18.5790039224226
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
nameStringSubmitted proper noun
commonTypeStringMost likely type of the proper noun
commonTypeAltStringSecond most likely type of the proper noun
scoreNumberHigher implies a more reliable result, score is not normalized

Name Type Geo Batch

Name Type Geo Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeGeoBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"properNouns":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","name":"Edi Gathegi","countryIso2":"KE"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeGeoBatch")
.header("Content-Type", "application/json")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.body("{\"properNouns\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"name\":\"Edi Gathegi\",\"countryIso2\":\"KE\"}]}")
.asString();
import requests

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

payload = {"properNouns": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Edi Gathegi",
"countryIso2": "KE"
}
]}
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/nameTypeGeoBatch", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"X-API-KEY": "your-api-key"
},
"body": "{\"properNouns\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"name\":\"Edi Gathegi\",\"countryIso2\":\"KE\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns the type of up to 100 submitted proper nouns using their geographic context. Ex: John Smith = personal name, Namsor = brand name.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

{
"properNouns": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Edi Gathegi",
"countryIso2": "KE"
}
]
}

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
nameStringtrueA proper noun (person, brand, etc.)
countryIso2StringtrueMost likely country of origin, in ISO 3166-1 alpha-2 format

The above command returns JSON structured like this:

{
"properNouns": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Edi Gathegi",
"commonType": "anthroponym",
"commonTypeAlt": "brand-name",
"score": 18.579081911201673
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
nameStringSubmitted proper noun
commonTypeStringMost likely type of the proper noun
commonTypeAltStringSecond most likely type of the proper noun
scoreNumberHigher implies a more reliable result, score is not normalized

Split Name

Namsor’s software offers a name separation API. We are able to take in a full name, and split it into a first name and last name structure. Our API also supports Chinese names, in Pinyin or Mandarin Chinese, and Japanese names written in Kanji characters.


Try out Name Splitting features

Split Name

Split Name code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/parseName/John%20Smith \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/parseName/John%20Smith")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/parseName/John%20Smith"

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/parseName/John%20Smith", {
"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 first name and last name structure of a full name.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/parseName/{nameFull}

Request Parameters

NameTypeRequiredDescription
nameFullStringtrueFull name (first name and last name)

The above command returns JSON structured like this:

{
"script": "LATIN",
"id": "3fb36d3d-f9cd-4ccc-a348-38d9e5b5232d",
"name": "John Smith",
"nameParserType": "FN1LN1",
"nameParserTypeAlt": null,
"firstLastName": {
"script": null,
"id": null,
"firstName": "John",
"lastName": "Smith"
},
"score": 23.313692197779005
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
nameStringSubmitted full name
nameParserTypeStringMost likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
nameParserTypeAltStringSecond most likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
firstLastNameObject
    {…}.scriptStringCharacter set used for analysis
    {…}.idStringProvided unique identifier
    {…}.firstNameStringFirst name (or given name)
    {…}.lastNameStringLast name (or family name)
scoreNumberHigher implies a more reliable result, score is not normalized

Split Name Batch

Split Name Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/parseNameBatch \
--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":"John Smith"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/parseNameBatch")
.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\":\"John Smith\"}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "John Smith"
}
]}
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/parseNameBatch", {
"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\":\"John Smith\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns the most likely first name and last name structure of up to 100 full names.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

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

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
nameStringtrueFull name (first name and last name)

The above command returns JSON structured like this:

{
"personalNames": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "John Smith",
"nameParserType": "FN1LN1",
"nameParserTypeAlt": null,
"firstLastName": {
"script": null,
"id": null,
"firstName": "John",
"lastName": "Smith"
},
"score": 23.31368511252333
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
nameStringSubmitted full name
nameParserTypeStringMost likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
nameParserTypeAltStringSecond most likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
firstLastNameObject
    {…}.scriptStringCharacter set used for analysis
    {…}.idStringProvided unique identifier
    {…}.firstNameStringFirst name (or given name)
    {…}.lastNameStringLast name (or family name)
scoreNumberHigher implies a more reliable result, score is not normalized

Split Name Geo

Split Name Geo code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/parseName/Ricardo%20Dar%C3%ADn/AR \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/parseName/Ricardo%20Dar%C3%ADn/AR")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/parseName/Ricardo%20Dar%C3%ADn/AR"

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/parseName/Ricardo%20Dar%C3%ADn/AR", {
"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 first name and last name structure of a full name using its geographic context.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/parseName/{nameFull}/{countryIso2}

Request Parameters

NameTypeRequiredDescription
nameFullStringtrueFull name (first name and last name)
countryIso2StringtrueMost likely country of origin, in ISO 3166-1 alpha-2 format

The above command returns JSON structured like this:

{
"script": "LATIN",
"id": "dbe186ee-cfd6-48e0-a449-00c70df61ec3",
"name": "Ricardo Darín",
"nameParserType": "FN1LN1",
"nameParserTypeAlt": "FN1LN2",
"firstLastName": {
"script": null,
"id": null,
"firstName": "Ricardo",
"lastName": "Darín"
},
"score": 3.4476222927492017
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
nameStringSubmitted full name
nameParserTypeStringMost likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
nameParserTypeAltStringSecond most likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
firstLastNameObject
    {…}.scriptStringCharacter set used for analysis
    {…}.idStringProvided unique identifier
    {…}.firstNameStringFirst name (or given name)
    {…}.lastNameStringLast name (or family name)
scoreNumberHigher implies a more reliable result, score is not normalized

Split Name Geo Batch

Split Name Geo Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/parseNameGeoBatch \
--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":"Ricardo Darín","countryIso2":"AR"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/parseNameGeoBatch")
.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\":\"Ricardo Darín\",\"countryIso2\":\"AR\"}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Ricardo Darín",
"countryIso2": "AR"
}
]}
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/parseNameGeoBatch", {
"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\":\"Ricardo Darín\",\"countryIso2\":\"AR\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns the most likely first name and last name structure of up to 100 full names using their geographic context.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Ricardo Darín",
"countryIso2": "AR"
}
]
}

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
nameStringtrueFull name (first name and last name)
countryIso2StringtrueMost likely country of origin, in ISO 3166-1 alpha-2 format

The above command returns JSON structured like this:

{
"personalNames": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Ricardo Darín",
"nameParserType": "FN1LN1",
"nameParserTypeAlt": "FN1LN2",
"firstLastName": {
"script": null,
"id": null,
"firstName": "Ricardo",
"lastName": "Darín"
},
"score": 3.447624982163207
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
nameStringSubmitted full name
nameParserTypeStringMost likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
nameParserTypeAltStringSecond most likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
firstLastNameObject
    {…}.scriptStringCharacter set used for analysis
    {…}.idStringProvided unique identifier
    {…}.firstNameStringFirst name (or given name)
    {…}.lastNameStringLast name (or family name)
scoreNumberHigher implies a more reliable result, score is not normalized

Japanese

Namsor provides a specialized name processing API dedicated to analysing names in the Japanese language. We have developed a name converter, focused on Japanese names, to help you find the best transcriptions possible.

With our API, you can convert Japanese names both ways between Kanji and English. You can evaluate the quality of a transcriptions between a name in Kanji and a name in Latin characters. It is also possible to split Japansese full names, in either Kanji or Latin characters, into a first name and a last name as well as establish the gender of a name.


Try out Japanese features

To Kanji Name Gender

To Kanji Name Gender code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidates/Yamamoto/Sanae \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidates/Yamamoto/Sanae")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidates/Yamamoto/Sanae"

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/japaneseNameKanjiCandidates/Yamamoto/Sanae", {
"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 Kanji transcriptions for a japanese first name and last name in latin characters.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidates/{japaneseSurnameLatin}/{japaneseGivenNameLatin}

Request Parameters

NameTypeRequiredDescription
japaneseSurnameLatinStringtrueFamily name (or last name) in latin characters
japaneseGivenNameLatinStringtrueGiven name (or first name) in latin characters

The above command returns JSON structured like this:

{
"script": "LATIN",
"id": null,
"firstName": "Sanae",
"lastName": "Yamamoto",
"orderOption": "OrderScoreSquareFNLN",
"matchCandidates": [
{
"candidateName": "山本 早苗",
"probability": 0.5000000000000001,
"predScoreGivenName": -0.03954087197780609,
"predScoreFamilyName": -0.014371121302247047
},
{
"candidateName": "山本 沙苗",
"probability": 0.25000000000000006,
"predScoreGivenName": -5.180787086486816,
"predScoreFamilyName": -0.014371121302247047
}
]
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
orderOptionStringSorting order for matchCandidates
matchCandidatesArray of Objects
    [ {…} ].candidateNameStringInferred transcription of the full name to Kanji
    [ {…} ].probabilityNumberHigher implies a more reliable result, ranges from 0 to 1
    [ {…} ].predScoreGivenNameNumberHigher implies a more reliable result (for given name or first name)
    [ {…} ].predScoreFamilyNameNumberHigher implies a more reliable result (for family name or last name)

To Kanji Name Batch

To Kanji Name Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidatesBatch \
--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":"Sanae","lastName":"Yamamoto"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidatesBatch")
.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\":\"Sanae\",\"lastName\":\"Yamamoto\"}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Sanae",
"lastName": "Yamamoto"
}
]}
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/japaneseNameKanjiCandidatesBatch", {
"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\":\"Sanae\",\"lastName\":\"Yamamoto\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns the most likely Kanji transcriptions for up to 100 japanese first names and last names in latin characters.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

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

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
firstNameStringtrueGiven name (or first name) in latin characters
lastNameStringtrueFamily name (or last name) in latin characters

The above command returns JSON structured like this:

{
"namesAndMatchCandidates": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Sanae",
"lastName": "Yamamoto",
"orderOption": "OrderScoreSquareFNLN",
"matchCandidates": [
{
"candidateName": "山本 早苗",
"probability": 0.5000000000000001,
"predScoreGivenName": -0.03954087197780609,
"predScoreFamilyName": -0.014371121302247047
},
{
"candidateName": "山本 沙苗",
"probability": 0.25000000000000006,
"predScoreGivenName": -5.180787086486816,
"predScoreFamilyName": -0.014371121302247047
}
]
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
orderOptionStringSorting order for matchCandidates
matchCandidatesArray of Objects
    [ {…} ].candidateNameStringInferred transcription of the full name to Kanji
    [ {…} ].probabilityNumberHigher implies a more reliable result, ranges from 0 to 1
    [ {…} ].predScoreGivenNameNumberHigher implies a more reliable result (for given name or first name)
    [ {…} ].predScoreFamilyNameNumberHigher implies a more reliable result (for family name or last name)

To Kanji Name

To Kanji Name code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidates/Yamamoto/Sanae/male \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidates/Yamamoto/Sanae/male")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidates/Yamamoto/Sanae/male"

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/japaneseNameKanjiCandidates/Yamamoto/Sanae/male", {
"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 Kanji transcriptions for a japanese first name and last name in latin characters, according to their gender.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidates/{japaneseSurnameLatin}/{japaneseGivenNameLatin}/{knownGender}

Request Parameters

NameTypeRequiredDescription
japaneseSurnameLatinStringtrueFamily name (or last name) in latin characters
japaneseGivenNameLatinStringtrueGiven name (or first name) in latin characters
knownGenderStringtrueGender

The above command returns JSON structured like this:

{
"script": "LATIN",
"id": null,
"firstName": "Sanae",
"lastName": "Yamamoto",
"orderOption": "OrderScoreSquareFNLN",
"matchCandidates": [
{
"candidateName": "山本 早苗",
"probability": 0.5000000000000001,
"predScoreGivenName": -0.031474947929382324,
"predScoreFamilyName": -0.014371121302247047
},
{
"candidateName": "山本 佐苗",
"probability": 0.25000000000000006,
"predScoreGivenName": -4.911670207977295,
"predScoreFamilyName": -0.014371121302247047
}
]
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
orderOptionStringSorting order for matchCandidates
matchCandidatesArray of Objects
    [ {…} ].candidateNameStringInferred transcription of the full name to Kanji
    [ {…} ].probabilityNumberHigher implies a more reliable result, ranges from 0 to 1
    [ {…} ].predScoreGivenNameNumberHigher implies a more reliable result (for given name or first name)
    [ {…} ].predScoreFamilyNameNumberHigher implies a more reliable result (for family name or last name)

To Kanji Name Gender Batch

To Kanji Name Gender Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameGenderKanjiCandidatesBatch \
--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":"Takashi","lastName":"Murakami","gender":"male"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameGenderKanjiCandidatesBatch")
.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\":\"Takashi\",\"lastName\":\"Murakami\",\"gender\":\"male\"}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Takashi",
"lastName": "Murakami",
"gender": "male"
}
]}
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/japaneseNameGenderKanjiCandidatesBatch", {
"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\":\"Takashi\",\"lastName\":\"Murakami\",\"gender\":\"male\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns the most likely Kanji transcriptions for up to 100 japanese first names and last names in latin characters, according to their gender.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Takashi",
"lastName": "Murakami",
"gender": "male"
}
]
}

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
firstNameStringtrueGiven name (or first name) in latin characters
lastNameStringtrueFamily name (or last name) in latin characters
genderStringtrueGender

The above command returns JSON structured like this:

{
"namesAndMatchCandidates": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Takashi",
"lastName": "Murakami",
"orderOption": "OrderScoreSquareFNLN",
"matchCandidates": [
{
"candidateName": "村上 隆",
"probability": 0.5000000000000001,
"predScoreGivenName": -2.249242067337036,
"predScoreFamilyName": -0.0006758159724995494
},
{
"candidateName": "村上 崇",
"probability": 0.25000000000000006,
"predScoreGivenName": -2.572237014770508,
"predScoreFamilyName": -0.0006758159724995494
}
]
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
orderOptionStringSorting order for matchCandidates
matchCandidatesArray of Objects
    [ {…} ].candidateNameStringInferred transcription of the full name to Kanji
    [ {…} ].probabilityNumberHigher implies a more reliable result, ranges from 0 to 1
    [ {…} ].predScoreGivenNameNumberHigher implies a more reliable result (for given name or first name)
    [ {…} ].predScoreFamilyNameNumberHigher implies a more reliable result (for family name or last name)

To Latin Name

To Latin Name code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameLatinCandidates/%E5%8D%83%E6%98%A5/%E5%A1%A9%E7%94%B0 \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameLatinCandidates/%E5%8D%83%E6%98%A5/%E5%A1%A9%E7%94%B0")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameLatinCandidates/%E5%8D%83%E6%98%A5/%E5%A1%A9%E7%94%B0"

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/japaneseNameLatinCandidates/%E5%8D%83%E6%98%A5/%E5%A1%A9%E7%94%B0", {
"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 latin transcriptions for a japanese first name and last name in Kanji characters.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameLatinCandidates/{japaneseSurnameKanji}/{japaneseGivenNameKanji}

Request Parameters

NameTypeRequiredDescription
japaneseSurnameKanjiStringtrueFamily name (or last name) in Kanji
japaneseGivenNameKanjiStringtrueGiven name (or first name) in Kanji

The above command returns JSON structured like this:

{
"script": "HAN",
"id": null,
"firstName": "塩田",
"lastName": "千春",
"orderOption": "OrderScoreSquareFNLN",
"matchCandidates": [
{
"candidateName": "chiharu shiota",
"probability": 0.5000000149011616,
"predScoreGivenName": -0.3543974459171295,
"predScoreFamilyName": -0.004423846025019884
},
{
"candidateName": "chiharu shioda",
"probability": 0.2500000074505808,
"predScoreGivenName": -1.2378724813461304,
"predScoreFamilyName": -0.004423846025019884
}
]
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
orderOptionStringSorting order for matchCandidates
matchCandidatesArray of Objects
    [ {…} ].candidateNameStringInferred transcription of the full name to latin characters
    [ {…} ].probabilityNumberHigher implies a more reliable result, ranges from 0 to 1
    [ {…} ].predScoreGivenNameNumberHigher implies a more reliable result (for given name or first name)
    [ {…} ].predScoreFamilyNameNumberHigher implies a more reliable result (for family name or last name)

To Latin Name Batch

To Latin Name Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameLatinCandidatesBatch \
--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":"塩田","lastName":"千春"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameLatinCandidatesBatch")
.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\":\"塩田\",\"lastName\":\"千春\"}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "塩田",
"lastName": "千春"
}
]}
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/japaneseNameLatinCandidatesBatch", {
"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\":\"塩田\",\"lastName\":\"千春\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns the most likely latin transcriptions for up to 100 japanese first names and last names in Kanji characters.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "塩田",
"lastName": "千春"
}
]
}

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
firstNameStringtrueGiven name (or first name) in Kanji
lastNameStringtrueFamily name (or last name) in Kanji

The above command returns JSON structured like this:

{
"namesAndMatchCandidates": [
{
"script": "HAN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "塩田",
"lastName": "千春",
"orderOption": "OrderScoreSquareFNLN",
"matchCandidates": [
{
"candidateName": "chiharu shiota",
"probability": 0.5000000149011616,
"predScoreGivenName": -0.3543974459171295,
"predScoreFamilyName": -0.004423846025019884
},
{
"candidateName": "chiharu shioda",
"probability": 0.2500000074505808,
"predScoreGivenName": -1.2378724813461304,
"predScoreFamilyName": -0.004423846025019884
}
]
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
orderOptionStringSorting order for matchCandidates
matchCandidatesArray of Objects
    [ {…} ].candidateNameStringInferred transcription of the full name to latin characters
    [ {…} ].probabilityNumberHigher implies a more reliable result, ranges from 0 to 1
    [ {…} ].predScoreGivenNameNumberHigher implies a more reliable result (for given name or first name)
    [ {…} ].predScoreFamilyNameNumberHigher implies a more reliable result (for family name or last name)

Gender Name Latin

Gender Name Latin code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseName/Nakamoto/Satoshi \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseName/Nakamoto/Satoshi")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseName/Nakamoto/Satoshi"

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/genderJapaneseName/Nakamoto/Satoshi", {
"method": "GET",
"headers": {
"Accept": "application/json",
"X-API-KEY": "your-api-key"
}
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Return the most likely gender of a japanese family name and a given name in latin characters.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseName/{japaneseSurname}/{japaneseGivenName}

Request Parameters

NameTypeRequiredDescription
japaneseSurnameStringtrueFamily name (or last name) in latin characters
japaneseGivenNameStringtrueGiven name (or first name) in latin characters

The above command returns JSON structured like this:

{
"script": "LATIN",
"id": "9cfd8321-0924-4570-a4b7-29a611ce5089",
"firstName": "Satoshi",
"lastName": "Nakamoto",
"likelyGender": "male",
"genderScale": -0.9828731991489774,
"score": 24.94061932678776,
"probabilityCalibrated": 0.9914365995744887
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
likelyGenderStringMost likely gender“male”, “female” or “unknown”
genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

Gender Name Latin Batch

Gender Name Latin Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameBatch \
--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":"Satoshi","lastName":"Nakamoto"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameBatch")
.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\":\"Satoshi\",\"lastName\":\"Nakamoto\"}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Satoshi",
"lastName": "Nakamoto"
}
]}
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/genderJapaneseNameBatch", {
"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\":\"Satoshi\",\"lastName\":\"Nakamoto\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Return the most likely gender of up to 100 japanese family names and a given names in latin characters.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

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

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
firstNameStringtrueGiven name (or first name) in latin characters
lastNameStringtrueFamily name (or last name) in latin characters

The above command returns JSON structured like this:

{
"personalNames": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Satoshi",
"lastName": "Nakamoto",
"likelyGender": "male",
"genderScale": -0.9828731991489774,
"score": 24.94061932678776,
"probabilityCalibrated": 0.9914365995744887
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
likelyGenderStringMost likely gender“male”, “female” or “unknown”
genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

Gender Name Kanji

Gender Name Kanji code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFull/%E4%B8%AD%E6%9D%BE%20%E7%BE%A9%E9%83%8E \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFull/%E4%B8%AD%E6%9D%BE%20%E7%BE%A9%E9%83%8E")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFull/%E4%B8%AD%E6%9D%BE%20%E7%BE%A9%E9%83%8E"

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/genderJapaneseNameFull/%E4%B8%AD%E6%9D%BE%20%E7%BE%A9%E9%83%8E", {
"method": "GET",
"headers": {
"Accept": "application/json",
"X-API-KEY": "your-api-key"
}
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Find the most likely gender of a Japanese full name (surname and given name), written in Kanji characters.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFull/{japaneseName}

Request Parameters

NameTypeRequiredDescription
japaneseNameStringtrueFull name (family name and given name) in Kanji

The above command returns JSON structured like this:

{
"script": "HAN",
"id": "36990426-d289-43b3-99dc-50ccfe2e5ade",
"name": "中松 義郎",
"likelyGender": "male",
"genderScale": -0.22231473979961303,
"score": 3.72410721464353,
"probabilityCalibrated": 0.6111573698998065
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
nameStringSubmitted full name
likelyGenderStringMost likely gender“male”, “female” or “unknown”
genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

Gender Name Kanji Batch

Gender Name Kanji Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFullBatch \
--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":"中松 義郎"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFullBatch")
.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\":\"中松 義郎\"}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "中松 義郎"
}
]}
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/genderJapaneseNameFullBatch", {
"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\":\"中松 義郎\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Find the most likely gender of up to 100 Japanese full names (surnames and given names), written in Kanji characters.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "中松 義郎"
}
]
}

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
nameStringtrueFull name (family name and given name) in Kanji

The above command returns JSON structured like this:

{
"personalNames": [
{
"script": "HAN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "中松 義郎",
"likelyGender": "male",
"genderScale": -0.22231473979961303,
"score": 3.72410721464353,
"probabilityCalibrated": 0.6111573698998065
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
nameStringSubmitted full name
likelyGenderStringMost likely gender“male”, “female” or “unknown”
genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

Split Japanese Name

Split Japanese Name code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/parseJapaneseName/%E5%B0%8F%E5%B3%B6%20%E7%A7%80%E5%A4%AB \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/parseJapaneseName/%E5%B0%8F%E5%B3%B6%20%E7%A7%80%E5%A4%AB")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/parseJapaneseName/%E5%B0%8F%E5%B3%B6%20%E7%A7%80%E5%A4%AB"

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/parseJapaneseName/%E5%B0%8F%E5%B3%B6%20%E7%A7%80%E5%A4%AB", {
"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 first name and last name structure of a full name (family name and given name) in Kanji or latin characters.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/parseJapaneseName/{japaneseName}

Request Parameters

NameTypeRequiredDescription
japaneseNameStringtrueFull name (family name and given name) in Kanji or latin characters

The above command returns JSON structured like this:

{
"script": "HAN",
"id": "4646501e-33e3-44bc-be6f-66cab4bb5e94",
"name": "小島 秀夫",
"nameParserType": "LN1FN1",
"nameParserTypeAlt": null,
"firstLastName": {
"script": null,
"id": null,
"firstName": "秀夫",
"lastName": "小島"
},
"score": 100
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
nameStringSubmitted full name
nameParserTypeStringMost likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
nameParserTypeAltStringSecond most likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
firstLastNameObject
    {…}.scriptStringCharacter set used for analysis
    {…}.idStringProvided unique identifier
    {…}.firstNameStringFirst name (or given name)
    {…}.lastNameStringLast name (or family name)
scoreNumberHigher implies a more reliable result, score is not normalized

Split Japanese Name Batch

Split Japanese Name Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/parseJapaneseNameBatch \
--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":"小島 秀夫"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/parseJapaneseNameBatch")
.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\":\"小島 秀夫\"}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "小島 秀夫"
}
]}
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/parseJapaneseNameBatch", {
"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\":\"小島 秀夫\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns the most likely first name and last name structure of up to 100 full names (family names and given names) in Kanji or latin characters.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "小島 秀夫"
}
]
}

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
nameStringtrueFull name (family name and given name) in Kanji or latin characters

The above command returns JSON structured like this:

{
"personalNames": [
{
"script": "HAN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "小島 秀夫",
"nameParserType": "LN1FN1",
"nameParserTypeAlt": null,
"firstLastName": {
"script": null,
"id": null,
"firstName": "秀夫",
"lastName": "小島"
},
"score": 100
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
nameStringSubmitted full name
nameParserTypeStringMost likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
nameParserTypeAltStringSecond most likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
firstLastNameObject
    {…}.scriptStringCharacter set used for analysis
    {…}.idStringProvided unique identifier
    {…}.firstNameStringFirst name (or given name)
    {…}.lastNameStringLast name (or family name)
scoreNumberHigher implies a more reliable result, score is not normalized

Match Japanese Name

Match Japanese Name code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameMatch/Tomioka/Tessai/%E5%AF%8C%E5%B2%A1%20%E9%89%84%E6%96%8E \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameMatch/Tomioka/Tessai/%E5%AF%8C%E5%B2%A1%20%E9%89%84%E6%96%8E")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameMatch/Tomioka/Tessai/%E5%AF%8C%E5%B2%A1%20%E9%89%84%E6%96%8E"

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/japaneseNameMatch/Tomioka/Tessai/%E5%AF%8C%E5%B2%A1%20%E9%89%84%E6%96%8E", {
"method": "GET",
"headers": {
"Accept": "application/json",
"X-API-KEY": "your-api-key"
}
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Matches a full name in Kanji against a family name and a given name in latin characters.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameMatch/{japaneseSurnameLatin}/{japaneseGivenNameLatin}/{japaneseName}

Request Parameters

NameTypeRequiredDescription
japaneseSurnameLatinStringtrueFamily name (or last name) in latin characters
japaneseGivenNameLatinStringtrueGiven name (or first name) in latin characters
japaneseNameStringtrueFull name (family name and given name) in Kanji

The above command returns JSON structured like this:

{
"script": null,
"id": null,
"matchStatus": "Match",
"score": 1.002224089213585
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
matchStatusStringSuccess status of the match“Match” or “Mismatch”
scoreNumberHigher implies a better match, score is not normalized

Match Japanese Name Batch

Match Japanese Name Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameMatchBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c41","name1":{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Tessai","lastName":"Tomioka"},"name2":{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c43","name":"富岡 鉄斎"}}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameMatchBatch")
.header("Content-Type", "application/json")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.body("{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c41\",\"name1\":{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Tessai\",\"lastName\":\"Tomioka\"},\"name2\":{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c43\",\"name\":\"富岡 鉄斎\"}}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
"name1": {
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Tessai",
"lastName": "Tomioka"
},
"name2": {
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
"name": "富岡 鉄斎"
}
}
]}
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/japaneseNameMatchBatch", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"X-API-KEY": "your-api-key"
},
"body": "{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c41\",\"name1\":{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Tessai\",\"lastName\":\"Tomioka\"},\"name2\":{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c43\",\"name\":\"富岡 鉄斎\"}}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Matches up to 100 full names in Kanji against corresponding family names and given names in latin characters.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
"name1": {
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Tessai",
"lastName": "Tomioka"
},
"name2": {
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
"name": "富岡 鉄斎"
}
}
]
}

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
name1Object
    {…}.idStringUnique identifier
    {…}.firstNameStringtrueGiven name (or first name) in latin characters
    {…}.lastNameStringtrueFamily name (or last name) in latin characters
name2Object
    {…}.idStringUnique identifier
    {…}.nameStringtrueFull name (family name and given name) in Kanji

The above command returns JSON structured like this:

{
"matchedNames": [
{
"script": null,
"id": null,
"matchStatus": "Match",
"score": 1.002224089213585
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
matchStatusStringSuccess status of the match“Match” or “Mismatch”
scoreNumberHigher implies a better match, score is not normalized

Match Name Feedback Loop

Match Name Feedback Loop code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameMatchFeedbackLoop/Tomioka/Tessai/%E5%AF%8C%E5%B2%A1%20%E9%89%84%E6%96%8E \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameMatchFeedbackLoop/Tomioka/Tessai/%E5%AF%8C%E5%B2%A1%20%E9%89%84%E6%96%8E")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameMatchFeedbackLoop/Tomioka/Tessai/%E5%AF%8C%E5%B2%A1%20%E9%89%84%E6%96%8E"

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/japaneseNameMatchFeedbackLoop/Tomioka/Tessai/%E5%AF%8C%E5%B2%A1%20%E9%89%84%E6%96%8E", {
"method": "GET",
"headers": {
"Accept": "application/json",
"X-API-KEY": "your-api-key"
}
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Submit a Japanese family name and given name in latin caracters and its matching full name in Kanji. This help us improve our name matching tool and in return your can earn extra credits if the match is correct.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameMatchFeedbackLoop/{japaneseSurnameLatin}/{japaneseGivenNameLatin}/{japaneseName}

Request Parameters

NameTypeRequiredDescription
japaneseSurnameLatinStringtrueFamily name (or last name) in latin characters
japaneseGivenNameLatinStringtrueGiven name (or first name) in latin characters
japaneseNameStringtrueFull name (family name and given name) in Kanji

The above command returns JSON structured like this:

{
"feedbackCredits": 1
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
feedbackCreditsIntegerNumber of credits awarded

Chinese

Namsor provides dedicated name analysis API for the processing of Chinese names. Our name recognition AI can translate Chinese names to English (Pinyin). Among other features you can: infer the gender of a Chinese name or split a Chinese full name into a first name and a last name.

We are also able to rate the quality of a transcriptions between a name in Pinyin and a name in Standard Mandarin Chinese.


Try out Chinese features

To Mandarin Name

To Mandarin Name code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameCandidates/Zhao/LiYing \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameCandidates/Zhao/LiYing")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameCandidates/Zhao/LiYing"

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/chineseNameCandidates/Zhao/LiYing", {
"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 Standard Mandarin Chinese transcriptions using a surname and a given name in Pinyin.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameCandidates/{chineseSurnameLatin}/{chineseGivenNameLatin}

Request Parameters

NameTypeRequiredDescription
chineseSurnameLatinStringtrueFamily name (or last name) in Pinyin
chineseGivenNameLatinStringtrueGiven name (or first name) in Pinyin

The above command returns JSON structured like this:

{
"script": null,
"id": null,
"firstName": "LiYing",
"lastName": "Zhao",
"orderOption": null,
"matchCandidates": [
{
"candidateName": "赵丽英",
"probability": 0.26153460755147884,
"predScoreGivenName": 0,
"predScoreFamilyName": 0
},
{
"candidateName": "赵丽颖",
"probability": 0.11856235542333707,
"predScoreGivenName": 0,
"predScoreFamilyName": 0
}
]
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
orderOptionStringSorting order for matchCandidates
matchCandidatesArray of Objects
    [ {…} ].candidateNameStringInferred transcription of the full name to Standard Mandarin Chinese
    [ {…} ].probabilityNumberHigher implies a more reliable result, ranges from 0 to 1
    [ {…} ].predScoreGivenNameNumberHigher implies a more reliable result (for given name or first name)
    [ {…} ].predScoreFamilyNameNumberHigher implies a more reliable result (for family name or last name)

To Mandarin Name Batch

To Mandarin Name Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameCandidatesBatch \
--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":"LiYing","lastName":"Zhao"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameCandidatesBatch")
.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\":\"LiYing\",\"lastName\":\"Zhao\"}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "LiYing",
"lastName": "Zhao"
}
]}
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/chineseNameCandidatesBatch", {
"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\":\"LiYing\",\"lastName\":\"Zhao\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns the most likely Standard Mandarin Chinese transcriptions using up to 100 family names and given names in Pinyin.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

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

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
firstNameStringtrueGiven name (or first name) in Pinyin
lastNameStringtrueFamily name (or last name) in Pinyin

The above command returns JSON structured like this:

{
"namesAndMatchCandidates": [
{
"script": null,
"id": null,
"firstName": "LiYing",
"lastName": "Zhao",
"orderOption": null,
"matchCandidates": [
{
"candidateName": "赵丽英",
"probability": 0.26153460755147884,
"predScoreGivenName": 0,
"predScoreFamilyName": 0
},
{
"candidateName": "赵丽颖",
"probability": 0.11856235542333707,
"predScoreGivenName": 0,
"predScoreFamilyName": 0
}
]
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
orderOptionStringSorting order for matchCandidates
matchCandidatesArray of Objects
    [ {…} ].candidateNameStringInferred transcription of the full name to Standard Mandarin Chinese
    [ {…} ].probabilityNumberHigher implies a more reliable result, ranges from 0 to 1
    [ {…} ].predScoreGivenNameNumberHigher implies a more reliable result (for given name or first name)
    [ {…} ].predScoreFamilyNameNumberHigher implies a more reliable result (for family name or last name)

To Mandarin Name Gender

To Mandarin Name Gender code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameGenderCandidates/Fanzhi/Zeng/male \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameGenderCandidates/Fanzhi/Zeng/male")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameGenderCandidates/Fanzhi/Zeng/male"

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/chineseNameGenderCandidates/Fanzhi/Zeng/male", {
"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 Standard Mandarin Chinese transcriptions for a Pinyin first name and last name, according to their gender.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameGenderCandidates/{chineseSurnameLatin}/{chineseGivenNameLatin}/{knownGender}

Request Parameters

NameTypeRequiredDescription
chineseSurnameLatinStringtrueFamily name (or last name) in Pinyin
chineseGivenNameLatinStringtrueGiven name (or first name) in Pinyin
knownGenderStringtrueGender

The above command returns JSON structured like this:

{
"script": null,
"id": null,
"firstName": "Zeng",
"lastName": "Fanzhi",
"orderOption": null,
"matchCandidates": [
{
"candidateName": "甑范志",
"probability": 0.014705882352941176,
"predScoreGivenName": 0,
"predScoreFamilyName": 0
},
{
"candidateName": "甑凡智",
"probability": 0.014705882352941176,
"predScoreGivenName": 0,
"predScoreFamilyName": 0
}
]
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringFirst name (or given name)
lastNameStringLast name (or family name)
orderOptionStringSorting order for matchCandidates
matchCandidatesArray of Objects
    [ {…} ].candidateNameStringInferred transcription of the full name to Standard Mandarin Chinese
    [ {…} ].probabilityNumberHigher implies a more reliable result, ranges from 0 to 1
    [ {…} ].predScoreGivenNameNumberHigher implies a more reliable result (for given name or first name)
    [ {…} ].predScoreFamilyNameNumberHigher implies a more reliable result (for family name or last name)

To Mandarin Name Gender Batch

To Mandarin Name Gender Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameCandidatesGenderBatch \
--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":"LiYing","lastName":"Zhao","gender":"female"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameCandidatesGenderBatch")
.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\":\"LiYing\",\"lastName\":\"Zhao\",\"gender\":\"female\"}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "LiYing",
"lastName": "Zhao",
"gender": "female"
}
]}
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/chineseNameCandidatesGenderBatch", {
"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\":\"LiYing\",\"lastName\":\"Zhao\",\"gender\":\"female\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns the most likely Standard Mandarin Chinese transcriptions for up to 100 Pinyin first names and last names, according to their gender.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "LiYing",
"lastName": "Zhao",
"gender": "female"
}
]
}

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
firstNameStringtrueGiven name (or first name) in Pinyin
lastNameStringtrueFamily name (or last name) in Pinyin
genderStringtrueGender

The above command returns JSON structured like this:

{
"namesAndMatchCandidates": [
{
"script": null,
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "LiYing",
"lastName": "Zhao",
"orderOption": null,
"matchCandidates": [
{
"candidateName": "赵丽英",
"probability": 0.07949583832056487,
"predScoreGivenName": 0,
"predScoreFamilyName": 0
},
{
"candidateName": "赵丽颖",
"probability": 0.021402725701690543,
"predScoreGivenName": 0,
"predScoreFamilyName": 0
}
]
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
orderOptionStringSorting order for matchCandidates
matchCandidatesArray of Objects
    [ {…} ].candidateNameStringInferred transcription of the full name to Standard Mandarin Chinese
    [ {…} ].probabilityNumberHigher implies a more reliable result, ranges from 0 to 1
    [ {…} ].predScoreGivenNameNumberHigher implies a more reliable result (for given name or first name)
    [ {…} ].predScoreFamilyNameNumberHigher implies a more reliable result (for family name or last name)

To Pinyin Name

To Pinyin Name code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/pinyinChineseName/%E8%B5%B5%E4%B8%BD%E9%A2%96 \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/pinyinChineseName/%E8%B5%B5%E4%B8%BD%E9%A2%96")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/pinyinChineseName/%E8%B5%B5%E4%B8%BD%E9%A2%96"

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/pinyinChineseName/%E8%B5%B5%E4%B8%BD%E9%A2%96", {
"method": "GET",
"headers": {
"Accept": "application/json",
"X-API-KEY": "your-api-key"
}
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Return the most likely Pinyin transcription of a full name (family name and given name) in Standard Mandarin Chinese.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/pinyinChineseName/{chineseName}

Request Parameters

NameTypeRequiredDescription
chineseNameStringtrueFull name (family name and given name) in Standard Mandarin Chinese

The above command returns JSON structured like this:

{
"script": "HAN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "赵丽颖",
"nameParserType": "LN1FN1",
"nameParserTypeAlt": null,
"firstLastName": {
"script": null,
"id": null,
"firstName": "LiYing",
"lastName": "Zhao"
},
"score": 4.641021485371256
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
nameStringSubmitted full name
nameParserTypeStringMost likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
nameParserTypeAltStringSecond most likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
firstLastNameObject
    {…}.scriptStringCharacter set used for analysis
    {…}.idStringProvided unique identifier
    {…}.firstNameStringMost likely first name (or given name) transcription in Pinyin
    {…}.lastNameStringMost likely last name (or family name) transcription in Pinyin
scoreNumberHigher implies a more reliable result, score is not normalized

To Pinyin Name Batch

To Pinyin Name Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/pinyinChineseNameBatch \
--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":"赵丽颖"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/pinyinChineseNameBatch")
.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\":\"赵丽颖\"}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "赵丽颖"
}
]}
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/pinyinChineseNameBatch", {
"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\":\"赵丽颖\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Return the most likely Pinyin transcription of up to 100 full names (family names and given names) in Standard Mandarin Chinese.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

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

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
nameStringtrueFull name (family name and given name) in Standard Mandarin Chinese

The above command returns JSON structured like this:

{
"personalNames": [
{
"script": "HAN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "赵丽颖",
"nameParserType": "LN1FN1",
"nameParserTypeAlt": null,
"firstLastName": {
"script": null,
"id": null,
"firstName": "LiYing",
"lastName": "Zhao"
},
"score": 4.641021485371256
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
nameStringSubmitted full name
nameParserTypeStringMost likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
nameParserTypeAltStringSecond most likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
firstLastNameObject
    {…}.scriptStringCharacter set used for analysis
    {…}.idStringProvided unique identifier
    {…}.firstNameStringMost likely first name (or given name) transcription in Pinyin
    {…}.lastNameStringMost likely last name (or family name) transcription in Pinyin
scoreNumberHigher implies a more reliable result, score is not normalized

Gender Name Pinyin

Gender Name Pinyin code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNamePinyin/Q%C4%ABngy%C3%BAn/D%C3%A8ng \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNamePinyin/Q%C4%ABngy%C3%BAn/D%C3%A8ng")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNamePinyin/Q%C4%ABngy%C3%BAn/D%C3%A8ng"

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/genderChineseNamePinyin/Q%C4%ABngy%C3%BAn/D%C3%A8ng", {
"method": "GET",
"headers": {
"Accept": "application/json",
"X-API-KEY": "your-api-key"
}
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Return the most likely gender of a family name and a given name in Pinyin.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNamePinyin/{chineseSurnameLatin}/{chineseGivenNameLatin}

Request Parameters

NameTypeRequiredDescription
chineseSurnameLatinStringtrueFamily name (or last name) in Pinyin
chineseGivenNameLatinStringtrueGiven name (or first name) in Pinyin

The above command returns JSON structured like this:

{
"script": "LATIN",
"id": "9c1fda7c-54f1-48d1-b082-80cc6148aeb9",
"firstName": "Dèng",
"lastName": "Qīngyún",
"likelyGender": "male",
"genderScale": -0.014201270075495653,
"score": 1.8597729950048343,
"probabilityCalibrated": 0.5071006350377478
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
likelyGenderStringMost likely gender“male”, “female” or “unknown”
genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

Gender Name Pinyin Batch

Gender Name Pinyin Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNamePinyinBatch \
--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":"Dèng","lastName":"Qīngyún"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNamePinyinBatch")
.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\":\"Dèng\",\"lastName\":\"Qīngyún\"}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Dèng",
"lastName": "Qīngyún"
}
]}
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/genderChineseNamePinyinBatch", {
"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\":\"Dèng\",\"lastName\":\"Qīngyún\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Return the most likely gender of up to 100 family names and a given names in Pinyin.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Dèng",
"lastName": "Qīngyún"
}
]
}

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
firstNameStringtrueGiven name (or first name) in Pinyin
lastNameStringtrueFamily name (or last name) in Pinyin

The above command returns JSON structured like this:

{
"personalNames": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Dèng",
"lastName": "Qīngyún",
"likelyGender": "male",
"genderScale": -0.3132515162951226,
"score": 6.747266465582973,
"probabilityCalibrated": 0.6566257581475613
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
likelyGenderStringMost likely gender“male”, “female” or “unknown”
genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

Gender Name Mandarin

Gender Name Mandarin code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseName/%E8%B0%A2%E6%99%93%E4%BA%AE \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseName/%E8%B0%A2%E6%99%93%E4%BA%AE")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseName/%E8%B0%A2%E6%99%93%E4%BA%AE"

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/genderChineseName/%E8%B0%A2%E6%99%93%E4%BA%AE", {
"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 full name (family name and given name) in Standard Mandarin Chinese.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseName/{chineseName}

Request Parameters

NameTypeRequiredDescription
chineseNameStringtrueFull name (family name and given name) in Standard Mandarin Chinese

The above command returns JSON structured like this:

{
"script": "HAN",
"id": "46661b4d-32cf-4ca5-b598-f62a8d7e0667",
"name": "谢晓亮",
"likelyGender": "male",
"genderScale": -0.7130895869378251,
"score": 8.286118331853034,
"probabilityCalibrated": 0.8565447934689125
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
nameStringSubmitted full name
likelyGenderStringMost likely gender“male”, “female” or “unknown”
genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

Gender Name Mandarin Batch

Gender Name Mandarin Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNameBatch \
--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":"谢晓亮"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNameBatch")
.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\":\"谢晓亮\"}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "谢晓亮"
}
]}
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/genderChineseNameBatch", {
"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\":\"谢晓亮\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns the most likely gender of up to 100 full names (family names and given names) in Standard Mandarin Chinese.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

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

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
nameStringtrueFull name (family name and given name) in Standard Mandarin Chinese

The above command returns JSON structured like this:

{
"personalNames": [
{
"script": "HAN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "谢晓亮",
"likelyGender": "male",
"genderScale": -0.7130895869378251,
"score": 8.286118331853034,
"probabilityCalibrated": 0.8565447934689125
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
nameStringSubmitted full name
likelyGenderStringMost likely gender“male”, “female” or “unknown”
genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
scoreNumberHigher implies a more reliable result, score is not normalized
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

Split Chinese Name

Split Chinese Name code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/parseChineseName/%E8%B5%B5%E4%B8%BD%E9%A2%96 \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/parseChineseName/%E8%B5%B5%E4%B8%BD%E9%A2%96")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/parseChineseName/%E8%B5%B5%E4%B8%BD%E9%A2%96"

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/parseChineseName/%E8%B5%B5%E4%B8%BD%E9%A2%96", {
"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 first name and last name structure of a full name (family name and given name) in Standard Mandarin Chinese.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/parseChineseName/{chineseName}

Request Parameters

NameTypeRequiredDescription
chineseNameStringtrueFull name (family name and given name) in Standard Mandarin Chinese

The above command returns JSON structured like this:

{
"script": "HAN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "赵丽颖",
"nameParserType": "LN1FN1",
"nameParserTypeAlt": null,
"firstLastName": {
"script": null,
"id": null,
"firstName": "丽颖",
"lastName": "赵"
},
"score": 4.64102036931541
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
nameStringSubmitted full name
nameParserTypeStringMost likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
nameParserTypeAltStringSecond most likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
firstLastNameObject
    {…}.scriptStringCharacter set used for analysis
    {…}.idStringProvided unique identifier
    {…}.firstNameStringFirst name (or given name) in Standard Mandarin Chinese
    {…}.lastNameStringLast name (or family name) in Standard Mandarin Chinese
scoreNumberHigher implies a more reliable result, score is not normalized

Split Chinese Name Batch

Split Chinese Name Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/parseChineseNameBatch \
--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":"赵丽颖"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/parseChineseNameBatch")
.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\":\"赵丽颖\"}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "赵丽颖"
}
]}
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/parseChineseNameBatch", {
"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\":\"赵丽颖\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns the most likely first name and last name structure of up to 100 full names (family names and given names) in Standard Mandarin Chinese.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

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

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
nameStringtrueFull name (family name and given name) in Standard Mandarin Chinese

The above command returns JSON structured like this:

{
"personalNames": [
{
"script": "HAN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "赵丽颖",
"nameParserType": "LN1FN1",
"nameParserTypeAlt": null,
"firstLastName": {
"script": null,
"id": null,
"firstName": "丽颖",
"lastName": "赵"
},
"score": 4.64102036931541
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
nameStringSubmitted full name
nameParserTypeStringMost likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
nameParserTypeAltStringSecond most likely structure of the name“FN1LN1”, “LN1FN1”, “FN1LN2”, “LN2FN1”, “FN1LNx”, “LNxFN1”, “FN2LN1”, “LN1FN2”, “FN2LN2”, “LN2FN2”, “FN2LNx”, “LNxFN2”, “FNxLN1”, “LN1FNx”, “FNxLN2”, “LN2FNx”, “FNxLNx” or “LNxFNx”
firstLastNameObject
    {…}.scriptStringCharacter set used for analysis
    {…}.idStringProvided unique identifier
    {…}.firstNameStringFirst name (or given name) in Standard Mandarin Chinese
    {…}.lastNameStringLast name (or family name) in Standard Mandarin Chinese
scoreNumberHigher implies a more reliable result, score is not normalized

Match Chinese Name

Match Chinese Name code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameMatch/Yu/Hong/%E5%96%BB%E7%BA%A2 \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameMatch/Yu/Hong/%E5%96%BB%E7%BA%A2")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameMatch/Yu/Hong/%E5%96%BB%E7%BA%A2"

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/chineseNameMatch/Yu/Hong/%E5%96%BB%E7%BA%A2", {
"method": "GET",
"headers": {
"Accept": "application/json",
"X-API-KEY": "your-api-key"
}
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Matches a full name in Standard Mandarin Chinese against a family name and a given name in Pinyin.

Cost : The processing of each query requires 1 credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameMatch/{chineseSurnameLatin}/{chineseGivenNameLatin}/{chineseName}

Request Parameters

NameTypeRequiredDescription
chineseSurnameLatinStringtrueFamily name (or last name) in Pinyin
chineseGivenNameLatinStringtrueGiven name (or first name) in Pinyin
chineseNameStringtrueFull name (family name and given name) in Standard Mandarin Chinese

The above command returns JSON structured like this:

{
"script": null,
"id": null,
"matchStatus": "Match",
"score": 1.0017825620273417
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
matchStatusStringSuccess status of the match“Match” or “Mismatch”
scoreNumberHigher implies a better match, score is not normalized

Match Chinese Name Batch

Match Chinese Name Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameMatchBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c41","name1":{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Hong","lastName":"Yu"},"name2":{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c43","name":"喻红"}}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameMatchBatch")
.header("Content-Type", "application/json")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.body("{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c41\",\"name1\":{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Hong\",\"lastName\":\"Yu\"},\"name2\":{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c43\",\"name\":\"喻红\"}}]}")
.asString();
import requests

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

payload = {"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
"name1": {
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Hong",
"lastName": "Yu"
},
"name2": {
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
"name": "喻红"
}
}
]}
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/chineseNameMatchBatch", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"X-API-KEY": "your-api-key"
},
"body": "{\"personalNames\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c41\",\"name1\":{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Hong\",\"lastName\":\"Yu\"},\"name2\":{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c43\",\"name\":\"喻红\"}}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Matches up to 100 full names in Standard Mandarin Chinese against corresponding family names and given names in Pinyin.

Cost : The processing of each object requires 1 credits.

HTTP Request

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

Body parameter

{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
"name1": {
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Hong",
"lastName": "Yu"
},
"name2": {
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
"name": "喻红"
}
}
]
}

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
name1Object
    {…}.idStringUnique identifier
    {…}.firstNameStringtrueFamily name (or last name) in Pinyin
    {…}.lastNameStringtrueGiven name (or first name) in Pinyin
name2Object
    {…}.idStringUnique identifier
    {…}.nameStringtrueFull name (family name and given name) in Standard Mandarin Chinese

The above command returns JSON structured like this:

{
"matchedNames": [
{
"script": null,
"id": null,
"matchStatus": "Match",
"score": 1.0017825620273417
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
matchStatusStringSuccess status of the match“Match” or “Mismatch”
scoreNumberHigher implies a better match, score is not normalized

Phone

The Namsor name analysis software has been trained to evaluate formated, as well as unformatted, phone numbers. It is able to process a first name, last name and phone number in order to establish its phone prefix and country code as well as determine the structure of the phone number and check if it is valid.


Try out Phone features

Phone Code

Phone Code code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/phoneCode/Jamini/Roy/09804201420 \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/phoneCode/Jamini/Roy/09804201420")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/phoneCode/Jamini/Roy/09804201420"

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/phoneCode/Jamini/Roy/09804201420", {
"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 phone prefix, country of origin and format of a phone number using a first name and a last name.

Cost : The processing of each query requires 11 credits.

HTTP Request

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

Request Parameters

NameTypeRequiredDescription
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)
phoneNumberStringtruePhone number, formatted or unformatted

The above command returns JSON structured like this:

{
"script": "LATIN",
"id": null,
"firstName": "Jamini",
"lastName": "Roy",
"internationalPhoneNumberVerified": "+91 98042 01420",
"phoneCountryIso2Verified": "IN",
"phoneCountryCode": 91,
"phoneCountryCodeAlt": 98,
"phoneCountryIso2": "IN",
"phoneCountryIso2Alt": "IR",
"originCountryIso2": "BD",
"originCountryIso2Alt": "ID",
"phoneNumber": "09804201420",
"verified": true,
"score": 7.659341221254624
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
internationalPhoneNumberVerifiedStringPhone number, in E.164 format
phoneCountryIso2VerifiedStringCountry of origin of the phone number, in ISO 3166-1 alpha-2 format (according to Libphonenumber)
phoneCountryCodeIntegerMost likely country calling code
phoneCountryCodeAltIntegerSecond most likely country calling code
phoneCountryIso2StringMost likely country of origin of the phone number, in ISO 3166-1 alpha-2 format
phoneCountryIso2AltStringSecond most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format
originCountryIso2StringMost likely country of origin of the name, in ISO 3166-1 alpha-2 format
originCountryIso2AltStringSecond most likely country of origin of the name, in ISO 3166-1 alpha-2 format
phoneNumberStringSubmitted phone number
verifiedBooleanIndicates if the phone number could be positively verified using Libphonenumber
scoreNumberHigher implies a more reliable result, score is not normalized
countryIso2StringMost likely country of origin, in ISO 3166-1 alpha-2 format

Phone Code Batch

Phone Code Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/phoneCodeBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"personalNamesWithPhoneNumbers":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Jamini","lastName":"Roy","phoneNumber":"09804201420"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/phoneCodeBatch")
.header("Content-Type", "application/json")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.body("{\"personalNamesWithPhoneNumbers\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Jamini\",\"lastName\":\"Roy\",\"phoneNumber\":\"09804201420\"}]}")
.asString();
import requests

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

payload = {"personalNamesWithPhoneNumbers": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Jamini",
"lastName": "Roy",
"phoneNumber": "09804201420"
}
]}
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/phoneCodeBatch", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"X-API-KEY": "your-api-key"
},
"body": "{\"personalNamesWithPhoneNumbers\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Jamini\",\"lastName\":\"Roy\",\"phoneNumber\":\"09804201420\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns the most likely phone prefix, country of origin and format of up to 100 phone numbers using first names and last names.

Cost : The processing of each object requires 11 credits.

HTTP Request

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

Body parameter

{
"personalNamesWithPhoneNumbers": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Jamini",
"lastName": "Roy",
"phoneNumber": "09804201420"
}
]
}

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)
phoneNumberStringtruePhone number, formatted or unformatted

The above command returns JSON structured like this:

{
"personalNamesWithPhoneNumbers": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Jamini",
"lastName": "Roy",
"internationalPhoneNumberVerified": "+91 98042 01420",
"phoneCountryIso2Verified": "IN",
"phoneCountryCode": 91,
"phoneCountryCodeAlt": 98,
"phoneCountryIso2": "IN",
"phoneCountryIso2Alt": "IR",
"originCountryIso2": "BD",
"originCountryIso2Alt": "ID",
"phoneNumber": "09804201420",
"verified": true,
"score": 7.659341221254494
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringFirst name (or given name)
lastNameStringLast name (or family name)
internationalPhoneNumberVerifiedStringPhone number, in E.164 format
phoneCountryIso2VerifiedStringCountry of origin of the phone number, in ISO 3166-1 alpha-2 format (according to Libphonenumber)
phoneCountryCodeIntegerMost likely country calling code
phoneCountryCodeAltIntegerSecond most likely country calling code
phoneCountryIso2StringMost likely country of origin of the phone number, in ISO 3166-1 alpha-2 format
phoneCountryIso2AltStringSecond most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format
originCountryIso2StringMost likely country of origin of the name, in ISO 3166-1 alpha-2 format
originCountryIso2AltStringSecond most likely country of origin of the name, in ISO 3166-1 alpha-2 format
phoneNumberStringSubmitted phone number
verifiedBooleanIndicates if the phone number could be positively verified using Libphonenumber
scoreNumberHigher implies a more reliable result, score is not normalized
countryIso2StringMost likely country of origin, in ISO 3166-1 alpha-2 format

Phone Code Geo

Phone Code Geo code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/phoneCodeGeo/Teniola/Apata/08186472651/NG \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/phoneCodeGeo/Teniola/Apata/08186472651/NG")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/phoneCodeGeo/Teniola/Apata/08186472651/NG"

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/phoneCodeGeo/Teniola/Apata/08186472651/NG", {
"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 phone prefix and format of a phone number using a first name, last name and geographic context.

Cost : The processing of each query requires 11 credits.

HTTP Request

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

Request Parameters

NameTypeRequiredDescription
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)
phoneNumberStringtruePhone number, formatted or unformatted
countryIso2StringtrueMost likely country of origin, in ISO 3166-1 alpha-2 format

The above command returns JSON structured like this:

{
"script": "LATIN",
"id": null,
"firstName": "Teniola",
"lastName": "Apata",
"internationalPhoneNumberVerified": "+234 818 647 2651",
"phoneCountryIso2Verified": "NG",
"phoneCountryCode": 234,
"phoneCountryCodeAlt": 62,
"phoneCountryIso2": "NG",
"phoneCountryIso2Alt": "ID",
"originCountryIso2": "NG",
"originCountryIso2Alt": "CI",
"phoneNumber": "08186472651",
"verified": true,
"score": 2.362918055640346
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
firstNameStringSubmitted first name
lastNameStringSubmitted last name
internationalPhoneNumberVerifiedStringPhone number, in E.164 format
phoneCountryIso2VerifiedStringCountry of origin of the phone number, in ISO 3166-1 alpha-2 format (according to Libphonenumber)
phoneCountryCodeIntegerMost likely country calling code
phoneCountryCodeAltIntegerSecond most likely country calling code
phoneCountryIso2StringMost likely country of origin of the phone number, in ISO 3166-1 alpha-2 format
phoneCountryIso2AltStringSecond most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format
originCountryIso2StringMost likely country of origin of the name, in ISO 3166-1 alpha-2 format
originCountryIso2AltStringSecond most likely country of origin of the name, in ISO 3166-1 alpha-2 format
phoneNumberStringSubmitted phone number
verifiedBooleanIndicates if the phone number could be positively verified using Libphonenumber
scoreNumberHigher implies a more reliable result, score is not normalized
countryIso2StringMost likely country of origin, in ISO 3166-1 alpha-2 format

Phone Code Geo Batch

Phone Code Geo Batch code sample :

curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/phoneCodeGeoBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"personalNamesWithPhoneNumbers":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Teniola","lastName":"Apata","phoneNumber":"08186472651","countryIso2":"NG"}]}'
HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/phoneCodeGeoBatch")
.header("Content-Type", "application/json")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.body("{\"personalNamesWithPhoneNumbers\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Teniola\",\"lastName\":\"Apata\",\"phoneNumber\":\"08186472651\",\"countryIso2\":\"NG\"}]}")
.asString();
import requests

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

payload = {"personalNamesWithPhoneNumbers": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Teniola",
"lastName": "Apata",
"phoneNumber": "08186472651",
"countryIso2": "NG"
}
]}
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/phoneCodeGeoBatch", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Accept": "application/json",
"X-API-KEY": "your-api-key"
},
"body": "{\"personalNamesWithPhoneNumbers\":[{\"id\":\"e630dda5-13b3-42c5-8f1d-648aa8a21c42\",\"firstName\":\"Teniola\",\"lastName\":\"Apata\",\"phoneNumber\":\"08186472651\",\"countryIso2\":\"NG\"}]}"
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns the most likely phone prefix and format of up to 100 phone numbers using first names, last names and geographic context.

Cost : The processing of each object requires 11 credits.

HTTP Request

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

Body parameter

{
"personalNamesWithPhoneNumbers": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Teniola",
"lastName": "Apata",
"phoneNumber": "08186472651",
"countryIso2": "NG"
}
]
}

Request Body

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

NameTypeRequiredDescription
idStringUnique identifier
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)
phoneNumberStringtruePhone number, formatted or unformatted
countryIso2StringtrueMost likely country of origin, in ISO 3166-1 alpha-2 format
countryIso2AltStringtrueSecond most likely country of origin, in ISO 3166-1 alpha-2 format

The above command returns JSON structured like this:

{
"personalNamesWithPhoneNumbers": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Teniola",
"lastName": "Apata",
"internationalPhoneNumberVerified": "+234 818 647 2651",
"phoneCountryIso2Verified": "NG",
"phoneCountryCode": 234,
"phoneCountryCodeAlt": 62,
"phoneCountryIso2": "NG",
"phoneCountryIso2Alt": "ID",
"originCountryIso2": "NG",
"originCountryIso2Alt": "CI",
"phoneNumber": "08186472651",
"verified": true,
"score": 2.362918055640346
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringProvided unique identifier
firstNameStringFirst name (or given name)
lastNameStringLast name (or family name)
internationalPhoneNumberVerifiedStringPhone number, in E.164 format
phoneCountryIso2VerifiedStringCountry of origin of the phone number, in ISO 3166-1 alpha-2 format (according to Libphonenumber)
phoneCountryCodeIntegerMost likely country calling code
phoneCountryCodeAltIntegerSecond most likely country calling code
phoneCountryIso2StringMost likely country of origin of the phone number, in ISO 3166-1 alpha-2 format
phoneCountryIso2AltStringSecond most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format
originCountryIso2StringMost likely country of origin of the name, in ISO 3166-1 alpha-2 format
originCountryIso2AltStringSecond most likely country of origin of the name, in ISO 3166-1 alpha-2 format
phoneNumberStringSubmitted phone number
verifiedBooleanIndicates if the phone number could be positively verified using Libphonenumber
scoreNumberHigher implies a more reliable result, score is not normalized
countryIso2StringMost likely country of origin, in ISO 3166-1 alpha-2 format

Phone Code Geo Feedback Loop

Phone Code Geo Feedback Loop code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/phoneCodeGeoFeedbackLoop/Diego/Rivera/14448140442/%2B524448140442/MX \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/phoneCodeGeoFeedbackLoop/Diego/Rivera/14448140442/%2B524448140442/MX")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/phoneCodeGeoFeedbackLoop/Diego/Rivera/14448140442/%2B524448140442/MX"

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/phoneCodeGeoFeedbackLoop/Diego/Rivera/14448140442/%2B524448140442/MX", {
"method": "GET",
"headers": {
"Accept": "application/json",
"X-API-KEY": "your-api-key"
}
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Submit a phone number and its matching first name, last name, country of origin in ISO 3166-1 alpha-2 format and formated version in E.164. This help us improve our name matching tool and in return your can earn extra credits if the match is correct.

Cost : The processing of each query requires 1 credits.

HTTP Request

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

Request Parameters

NameTypeRequiredDescription
firstNameStringtrueFirst name (or given name)
lastNameStringtrueLast name (or family name)
phoneNumberStringtruePhone number, formatted or unformatted
phoneNumberE164StringtruePhone number, in E.164 format
countryIso2StringtrueCountry of origin, in ISO 3166-1 alpha-2 format

The above command returns JSON structured like this:

{
"feedbackCredits": 1
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis
idStringUnique identifier
firstNameStringFirst name (or given name)
lastNameStringLast name (or family name)
internationalPhoneNumberVerifiedStringPhone number, in E.164 format
phoneCountryIso2VerifiedStringCountry of origin of the phone number, in ISO 3166-1 alpha-2 format (according to Libphonenumber)
phoneCountryCodeIntegerMost likely country calling code
phoneCountryCodeAltIntegerSecond most likely country calling code
phoneCountryIso2StringMost likely country of origin of the phone number, in ISO 3166-1 alpha-2 format
phoneCountryIso2AltStringSecond most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format
originCountryIso2StringMost likely country of origin of the name, in ISO 3166-1 alpha-2 format
originCountryIso2AltStringSecond most likely country of origin of the name, in ISO 3166-1 alpha-2 format
phoneNumberStringSubmitted phone number
verifiedBooleanIndicates if the phone number could be positively verified using Libphonenumber
scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available
countryIso2StringMost likely country of origin, in ISO 3166-1 alpha-2 format

Admin

The Admin endpoints allow you to access a wide range of administrative tools. Access your API usage history, check the status and availability of Namsor’s endpoints or query the possible enumerators for a given classifier. Among other features you may also set your privacy options or disable your key.

Software Version

Software Version code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/softwareVersion \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/softwareVersion")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

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

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/softwareVersion", {
"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 current version of the Namsor software.

Cost : The processing of each query does not require credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/softwareVersion

The above command returns JSON structured like this:

{
"softwareNameAndVersion": "NamsorAPIv2.0.14B01",
"softwareVersion": [
2,
0,
14
]
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
softwareNameAndVersionStringName and version of the API
softwareVersionArraySoftware version, as an array (major, minor and patch)

Api Status

Api Status code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/apiStatus \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/apiStatus")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

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

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/apiStatus", {
"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 current version of the Namsor software and the status of the classifiers (API services).

Cost : The processing of each query does not require credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/apiStatus

The above command returns JSON structured like this:

{
"softwareVersion": {
"softwareNameAndVersion": "NamsorAPIv2.0.14B01",
"softwareVersion": [
2,
0,
14
]
},
"classifiers": [
{
"classifierName": "name_category",
"serving": true,
"learning": true,
"shuttingDown": false,
"probabilityCalibrated": false
},
{
"classifierName": "personalname_gender",
"serving": true,
"learning": true,
"shuttingDown": false,
"probabilityCalibrated": true
}
]
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
softwareVersionObject
    {…}.softwareNameAndVersionStringName and version of the API
    {…}.softwareVersionArraySoftware version, as an array (major, minor and patch)
classifiersArray of Objects
    [ {…} ].classifierNameStringName of the classifier / service
    [ {…} ].servingBooleanTrue if the classifier is serving requests (has reached minimal learning, is not shutting down)
    [ {…} ].learningBooleanTrue if the classifier is learning
    [ {…} ].shuttingDownBooleanTrue if the classifier is shutting down
    [ {…} ].probabilityCalibratedBooleanTrue if the classifier has finished the initial learning and has calibrated probabilities (during initial learning, calibrated probabilities will be equal to -1)

Available Services

Available Services code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/apiServices \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/apiServices")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

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

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/apiServices", {
"method": "GET",
"headers": {
"Accept": "application/json",
"X-API-KEY": "your-api-key"
}
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns a list of the API services (classifiers) and their usage costs in credits.

Cost : The processing of each query does not require credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/apiServices

The above command returns JSON structured like this:

{
"apiServices": [
{
"serviceName": "name_category",
"serviceGroup": "general",
"costInUnits": 1
},
{
"serviceName": "personalname_gender",
"serviceGroup": "gender",
"costInUnits": 1
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
serviceNameStringName of the classifier / service
serviceGroupStringGroup the classifier / service belong to
costInUnitsIntegerUsage cost of the service, in credits

Taxonomy Classes

Taxonomy Classes code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/taxonomyClasses/personalname_gender \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/taxonomyClasses/personalname_gender")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

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

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/taxonomyClasses/personalname_gender", {
"method": "GET",
"headers": {
"Accept": "application/json",
"X-API-KEY": "your-api-key"
}
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns a list of the possible enumerators for a given classifier.

Cost : The processing of each query does not require credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/taxonomyClasses/{classifierName}

Request Parameters

NameTypeRequiredDescription
classifierNameStringtrueName of the classifier

The above command returns JSON structured like this:

{
"classifierName": "personalname_gender",
"taxonomyClasses": [
"female",
"male"
]
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
classifierNameStringName of the submitted classifier
taxonomyClassesArrayPossible enumerators for this classifier

Api Usage

Api Usage code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsage \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsage")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

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

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/apiUsage", {
"method": "GET",
"headers": {
"Accept": "application/json",
"X-API-KEY": "your-api-key"
}
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Returns information on your subscription plan, billing period and current API usage.

Cost : The processing of each query does not require credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsage

The above command returns JSON structured like this:

{
"subscription": {
"apiKey": "77afd518a85798fa3723f5ec8120adb7",
"planStarted": 1602705605199,
"priorPlanStarted": 0,
"planEnded": 0,
"taxRate": 0,
"planName": "BASIC",
"planBaseFeesKey": "namsorapi_v2_BASIC_usd",
"planStatus": "OPEN",
"planQuota": 5000,
"priceUSD": 0,
"priceOverageUSD": 0.005,
"price": 0,
"priceOverage": 0.005,
"currency": "usd",
"currencyFactor": 1,
"stripeCustomerId": null,
"stripeStatus": null,
"stripeSubscription": null,
"userId": "lXVJ95AraqM9jrRns45ZfbE4qRgw"
},
"billingPeriod": {
"apiKey": "77afd518a85798fa3723f5ec8120adb7",
"subscriptionStarted": 1602705635199,
"periodStarted": 1618430435199,
"periodEnded": 0,
"stripeCurrentPeriodEnd": 0,
"stripeCurrentPeriodStart": 0,
"billingStatus": "OPEN",
"usage": 34,
"softLimit": 3000,
"hardLimit": 5000
},
"overageExclTax": 0,
"overageInclTax": 0,
"overageCurrency": null,
"overageQuantity": 0
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
subscriptionObject
    {…}.apiKeyStringYour Namsor API key
    {…}.planStartedIntegerStart date of the plan, in UNIX time format
    {…}.priorPlanStartedIntegerDatetime when the user subscribed to the prior plan
    {…}.planEndedIntegerEnd date of the plan, in UNIX time format
    {…}.taxRateNumberApplicable tax rate for the plan
    {…}.planNameStringName of the plan
    {…}.planBaseFeesKeyStringCurrent plan key (as in Stripe product)
    {…}.planStatusStringPlan status
    {…}.planQuotaIntegerTotal number of credits associated with this plan
    {…}.priceUSDNumberPrice in U.S. dollars ($)
    {…}.priceOverageUSDNumberOverage price in U.S. dollars ($)
    {…}.priceNumberPrice in the user’s preferred currency
    {…}.priceOverageNumberOveraged price in the user’s preferred currency
    {…}.currencyStringThe user’s preferred currency
    {…}.currencyFactorNumberFor USD, GBP, EUR - the factor is 1
    {…}.stripeCustomerIdStringUnique Stripe Customer identifier
    {…}.stripeStatusStringStripe status
    {…}.stripeSubscriptionStringStripe subscription identifier
    {…}.userIdStringUnique user identifier
billingPeriodObject
    {…}.apiKeyStringYour Namsor API key
    {…}.subscriptionStartedIntegerSubscription start date, in UNIX time format
    {…}.periodStartedIntegerSubscription period start date, in UNIX time format
    {…}.periodEndedIntegerSubscription end date, in UNIX time format
    {…}.stripeCurrentPeriodEndIntegerEnd of the current plan in Stripe
    {…}.stripeCurrentPeriodStartIntegerStart of the current plan in Stripe
    {…}.billingStatusStringStatus of the current period billing
    {…}.usageIntegerNumber of credits used so far
    {…}.softLimitIntegerCurrent soft limit for the period
    {…}.hardLimitIntegerCurrent hard limit for the period
overageExclTaxNumberOverage amount including any tax
overageInclTaxNumberOverage amount including tax (if applicable)
overageCurrencyStringCurrency of the overage amount
overageQuantityIntegerQuantity above monthly quota of the current subscritpion, in credits

Api Usage History

Api Usage History code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsageHistory \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsageHistory")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

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

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/apiUsageHistory", {
"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 detailed usage history, indicating what services where called and what API key parameters where applied.

Cost : The processing of each query does not require credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsageHistory

The above command returns JSON structured like this:

{
"detailedUsage": [
{
"apiKey": {
"userId": null,
"admin": false,
"vetted": false,
"learnable": true,
"anonymized": false,
"partner": false,
"striped": false,
"corporate": false,
"disabled": false,
"api_key": "b214894824e1c4762fb650866fea8f3c"
},
"apiService": "personalname_us_race_ethnicity",
"createdDateTime": 1620385794616,
"totalUsage": 1,
"lastFlushedDateTime": 1620386273418,
"lastUsedDateTime": 1620386699945,
"serviceFeaturesUsage": {}
}
]
}

Response

The HTTP response body is a nested array of objects.

NameTypeDescriptionEnumerators
apiKeyObject
    {…}.apiKeyStringThe user API Key.
    {…}.userIdStringUnique user identifier
    {…}.adminBooleanDoes the API Key have admin priviledges
    {…}.vettedBooleanIs the API Key vetted for machine learning
    {…}.learnableBooleanIs the API Key authorised to feed the machine learning
    {…}.anonymizedBooleanIs the API Key anonymized (using its SHA-256 digest for logging)
    {…}.partnerBooleanDoes the API Key have a partnership role
    {…}.stripedBooleanIs the API Key associated to a valid Stripe account
    {…}.corporateBooleanDoes the API Key have a corporate role
    {…}.disabledBooleanIs the API Key temporarily or permanently disabled
apiServiceStringName of the service requested
createdDateTimeIntegerDate of the analysis, in UNIX time format
totalUsageIntegerTotal cost of the analysis in credits
lastFlushedDateTimeIntegerLast time the counter was reset, in UNIX time format
lastUsedDateTimeIntegerLast time the API key was used, in UNIX time format
serviceFeaturesUsageObjectDetails regarding usage of special features

Api Usage History Aggregate

Api Usage History Aggregate code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsageHistoryAggregate \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsageHistoryAggregate")
.header("Accept", "application/json")
.header("X-API-KEY", "your-api-key")
.asString();
import requests

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

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/apiUsageHistoryAggregate", {
"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 aggregated API usage history detailing usage per service. For each data point in the “data” field there is a corresponding row header in the “rowHeaders” field. For each value in a data point in the “data” field there is a corresponding column header in the “colHeaders” field. Ex: To find the period of data[0], lookup rowHeaders[0]. To find the service corresponding to data[0][3], lookup colHeaders[3].

Cost : The processing of each query does not require credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsageHistoryAggregate

The above command returns JSON structured like this:

{
"timeUnit": "DAY",
"periodStart": 1600616581000,
"periodEnd": 1600702981000,
"totalUsage": 42,
"historyTruncated": false,
"data": [
[
0,
0,
0,
10,
10,
0,
0,
0,
0,
10,
10,
2
]
],
"colHeaders": [
"chineseNameCandidates",
"japaneseNameCandidates",
"japaneseNameMatching",
"name_category",
"name_parser_type",
"personalfullname_country",
"personalfullname_gender",
"personalname_country_diaspora",
"personalname_gender",
"personalname_origin_country",
"personalname_phone_prefix",
"personalname_us_race_ethnicity"
],
"rowHeaders": [
"2020-09-20"
]
}

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
timeUnitStringUnit of time used in the “rowHeaders” field. May vary depending on API usage (“DAY”, “WEEK” or “MONTH”)
periodStartIntegerStart of the reporting period, in UNIX time format
periodEndIntegerEnd of the reporting period, in UNIX time format
totalUsageIntegerTotal usage during the current period
historyTruncatedBooleanIndicates if returned data was truncaded due to size limits
dataArrayAggregated API usage, formated as an array of data points (or array of arrays)
colHeadersArrayColumn headers used to link API services to the values in each data point
rowHeadersArrayRow headers used to link a period of time to a data point

Learnable

Learnable code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/learnable/77afd518a85798fa3723f5ec8120adb7/true
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/learnable/77afd518a85798fa3723f5ec8120adb7/true")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/learnable/77afd518a85798fa3723f5ec8120adb7/true"

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

print(response.text)
fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/learnable/77afd518a85798fa3723f5ec8120adb7/true", {
"method": "GET",
"headers": {}
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Used to set the learnable status of an API key. Setting the learnable parameter of an API key to false will prevent the submitted data from feeding the machine learning.

Cost : The processing of each query does not require credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/learnable/{source}/{learnable}

Request Parameters

NameTypeRequiredDescription
sourceStringtrueThe API Key to set as learnable or non-learnable
learnableBooleantrueShould the API key be set to learnable

Response

In case of a success the API will respond with an HTTP 200 code.

Anonymize

Anonymize code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/anonymize/77afd518a85798fa3723f5ec8120adb7/true
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/anonymize/77afd518a85798fa3723f5ec8120adb7/true")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/anonymize/77afd518a85798fa3723f5ec8120adb7/true"

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

print(response.text)
fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/anonymize/77afd518a85798fa3723f5ec8120adb7/true", {
"method": "GET",
"headers": {}
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Used to set the anonymized status of an API key. Setting the anonymized parameter of an API key to true will hide the data processed with this API key in the logs by using a SHA-256 digest of the submissions instead.

Cost : The processing of each query does not require credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/anonymize/{source}/{anonymized}

Request Parameters

NameTypeRequiredDescription
sourceStringtrueThe API Key to set as anonymized or non-anonymized
anonymizedBooleantrueShould the API key be set to anonymized

Response

In case of a success the API will respond with an HTTP 200 code.

Disable API Key

Disable API Key code sample :

curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/disable/77afd518a85798fa3723f5ec8120adb7/true
HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/disable/77afd518a85798fa3723f5ec8120adb7/true")
.asString();
import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/disable/77afd518a85798fa3723f5ec8120adb7/true"

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

print(response.text)
fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/disable/77afd518a85798fa3723f5ec8120adb7/true", {
"method": "GET",
"headers": {}
})
.then(response => {
console.log(response.json());
})
.catch(err => {
console.error(err);
});

Used to enable or disable an API key. Setting the disabled parameter of an API key to true will prevent its usage.

Cost : The processing of each query does not require credits.

HTTP Request

GET https://v2.namsor.com/NamSorAPIv2/api2/json/disable/{source}/{disabled}

Request Parameters

NameTypeRequiredDescription
sourceStringtrueThe API Key to set as enabled or disabled
disabledBooleantrueShould the API key be set to disabled

Response

In case of a success the API will respond with an HTTP 200 code.