Namsor API documentation v2.0.16
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
The REST based API allow you to get access to all of Namsor’s features.
Namsor has developed a name checking technology, able to create comprehensive analysis through multiple processing. Our API can classify names by gender, country of origin, ethnicity and even by diaspora. Using a full name and it can distinguish the first name from the last name, infer if it’s a personal name or a brand name as well as identify the most likely phone prefix for that name. Our API also supports many alphabets and is able to translate Japanese names in Kanji and Chinese names in Pinyin both ways.
Need something you can’t find here? We have many more features coming soon. Let us know, we’ll do our best to add it!
Email: contact@namsor.com
Terms and Conditions: NamsorAPI_Lic_v0.0.7
Introduction
About
- The base endpoint URL is: https://v2.namsor.com/NamSorAPIv2
- For best results, use Batch endpoint to process multi-entity requests
- Batch processing returns the data sorted in the same order as it was sent.
- All endpoints require an API Key.
- Never share your API key to ANYONE.
API Requests and Responses
All endpoints return JSON containing either an object or a nested array of objects.
Currently certain NamSor API endpoints use nested object structures in their query body and / or responses, please refer yourself to the corresponding code example.
Certain API response code examples have been truncated in order to improve readability. For example the countriesOriginTop, ethnicitiesTop and matchCandidates Array fields have been reduced to 2 elements in length.
Be aware that data in the code examples have been URL encoded into the corresponding ASCII code characters when necessary, for example “谢晓亮” is replaced by “%E8%B0%A2%E6%99%93%E4%BA%AE”. URLs cannot contain spaces or non-ASCII characters. When making GET requests to the API use URL encoding to convert non-ASCII characters into a format that can be transmitted over the internet.
Data Privacy
By default Namsor’s machine learning algorithm may improve data evaluation based on the data inputs and does store logs of submitted request. You may change these setting either in your user account or by calling the dedicated API endpoints. All data logs are secured using AES encryption before being stored.
If you wish to disable machine learning based on your submissions, please set learnable to “false” by using the corresponding Admin route. When set to false for an API key, the data processed using that key will not feed the machine learning algorithm.
If you wish to disable service usage history, please set anonymized to “true” by using the corresponding Admin route. When set to true for an API key, the data processed using that key will be irreversibly anonymised using SHA encryption. Note that the smart processing for redundant queries will still work even if your data is anonymised.
Authentication
API Key Creation
To create an API key visit www.namsor.app and create an account. Navigate to the account information page to retrieve your API key. Your newly created account comes with 5000 free credits that you may use immediately with any of Namsor’s tools: API, demo page, csv and excel file processor or CLI tools.
API Key Installation
Your API key must be set in the header of your request using the X-API-KEY property. Please refer yourself to the provided code samples for correct key installation.
Credits
What are Credits
We use a credit system to track usage. Each plan comes with a monthly quantity of credits and a price for request that exceed your monthly allowance. The free Basic subscription plan grants you 5000 credits but other plans are available in case you have higher requirements.
As an example, with 5000 credits you can either :
- Process 5000 names to determine their gender
- Process 500 names to determine their origin or ethnicity
- Process 250 names to determine their diaspora
Repeated Operations Tolerance
Our API features smart processing and it will not charge for analysing identical data for up to 20 times. For example if you submit the same full name 5 times in order to infer it’s gender then you will only be charged 1 credit.
Soft Limit vs Hard Limit
In your user account you may set two types of credit usage limits:
- A soft limit that will trigger an email notification when reached.
- A hard limit that will trigger an email notification and block the API key when reached.
Track Usage
There are two ways to track your credit usage: check the provided graphics in your user account or query the appropriate Admin routes (API Usage, API Usage History and API Usage History Aggregate).
Enumerators
For readability purposes the enumerators for certain fields may be omitted in the request / response tables. We have detailed the most important classification types in the following section.
Gender
female, male, unknown
Country code
All country codes must be submitted and will be returned using the ISO 3166-1 alpha-2 standard.
US Races and Ethnicities
American Indian or Alaska Native (AI_AN), Asian (A), Black or African-American (B_NL), Hispanic or Latino (HL), Native Hawaiian or Pacific Islander (PI), White or European American (W_NL)
Region Classifications
subRegionOrigin :
Southern Asia, Southern Europe, Northern Africa, Middle Africa, Caribbean, South America, Western Asia, Australia and New Zealand, Western Europe, Northern Europe, Eastern Europe, Central America, Western Africa, Southern Africa, South-Eastern Asia, Eastern Africa, Northern America, Eastern Asia, Melanesia, Central Asia, Micronesia, Polynesia, Unclassified
We provide two regions classifications when inferring the region origin. These classifications have slightly different enumerators as detailed below:
regionOrigin :
Africa, Asia, Europe, Latin America and the Caribbean, Northern America, Oceania, Unclassified
topRegionOrigin :
Africa, Americas, Asia, Europe, Oceania, Unclassified
Errors
The NamSor API uses the following error codes:
Error Code | Meaning | Description |
---|---|---|
401 | Unauthorized | Missing or incorrect API Key. |
403 | Forbidden | API Limit Reached or API Key Disabled. |
404 | Not Found | The specified route could not be found. |
500 | Internal Server Error | Server 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
Name | Type | Required | Description |
---|---|---|---|
personalNameFull | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
name | String | The provided full name | |
score | Number | Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available | |
country | String | Most likely country of origin, in ISO 3166-1 alpha-2 format | |
countryAlt | String | Second most likely country of origin, in ISO 3166-1 alpha-2 format | |
region | String | Most likely region of origin | |
topRegion | String | Most likely region of origin (alternative classification) | |
subRegion | String | Most likely sub region of origin | |
countriesTop | Array | Top 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely | |
probabilityCalibrated | Number | Higher implies a more reliable result, ranges from 0 to 1 (for country) | |
probabilityAltCalibrated | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
name | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
name | String | Submitted full name | |
score | Number | Higher implies a more reliable result, score is not normalized | |
country | String | Most likely country of origin, in ISO 3166-1 alpha-2 format | |
countryAlt | String | Second most likely country of origin, in ISO 3166-1 alpha-2 format | |
region | String | Most likely region of origin | |
topRegion | String | Most likely region of origin (alternative classification) | |
subRegion | String | Most likely subregion of origin | |
countriesTop | Array | Top 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely | |
probabilityCalibrated | Number | Higher implies a more reliable result, ranges from 0 to 1 (for country) | |
probabilityAltCalibrated | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
countryIso2 | String | true | Most likely country of origin, in ISO 3166-1 alpha-2 format |
firstName | String | true | First name (or given name) |
lastName | String | true | Last 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
countryIso2 | String | Submitted country of origin, in ISO 3166-1 alpha-2 format | |
subClassification | String | Most likely subclassification, in ISO 3166-2 alpha-2 format (country-region) | |
subClassificationAlt | String | Second most likely subclassification, in ISO 3166-2 alpha-2 format (country-region) | |
subclassificationTop | Array | Top 10 most likely subclassification, in ISO 3166-2 alpha-2 format (country-region), sorted from most likely to least likely | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher implies a more reliable result, ranges from 0 to 1 (for subClassification) | |
probabilityAltCalibrated | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Provided unique identifier | |
firstName | String | true | First name (or given name) |
lastName | String | true | Last name (or family name) |
countryIso2 | String | true | Most 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
countryIso2 | String | Submitted country of origin, in ISO 3166-1 alpha-2 format | |
subClassification | String | Most likely subclassification, in ISO 3166-2 alpha-2 format (country-region) | |
subClassificationAlt | String | Second most likely subclassification, in ISO 3166-2 alpha-2 format (country-region) | |
subclassificationTop | Array | Top 10 most likely subclassification, in ISO 3166-2 alpha-2 format (country-region), sorted from most likely to least likely | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher implies a more reliable result, ranges from 0 to 1 (for subClassification) | |
probabilityAltCalibrated | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
firstName | String | true | First name (or given name) |
lastName | String | true | Last 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
countryOrigin | String | Most likely country of origin, in ISO 3166-1 alpha-2 format | |
countryOriginAlt | String | Second most likely country of origin, in ISO 3166-1 alpha-2 format | |
countriesOriginTop | Array | Top 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely | |
score | Number | Higher implies a more reliable result, score is not normalized | |
regionOrigin | String | Most likely region of origin | |
topRegionOrigin | String | Most likely region of origin (alternative classification) | |
subRegionOrigin | String | Most likely subregion of origin | |
probabilityCalibrated | Number | Higher implies a more reliable result, ranges from 0 to 1 (for countryOrigin) | |
probabilityAltCalibrated | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
firstName | String | true | First name (or given name) |
lastName | String | true | Last 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
countryOrigin | String | Most likely country of origin, in ISO 3166-1 alpha-2 format | |
countryOriginAlt | String | Second most likely country of origin, in ISO 3166-1 alpha-2 format | |
countriesOriginTop | Array | Top 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely | |
score | Number | Higher implies a more reliable result, score is not normalized | |
regionOrigin | String | Most likely region of origin | |
topRegionOrigin | String | Most likely region of origin (alternative classification) | |
subRegionOrigin | String | Most likely subregion of origin | |
probabilityCalibrated | Number | Higher implies a more reliable result, ranges from 0 to 1 (for countryOrigin) | |
probabilityAltCalibrated | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
countryIso2 | String | true | Country of residence, in ISO 3166-1 alpha-2 format |
firstName | String | true | First name (or given name) |
lastName | String | true | Last 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
score | Number | Higher implies a more reliable result, score is not normalized | |
ethnicityAlt | String | Second most likely ethnicity | |
ethnicity | String | Most likely ethnicity | |
lifted | Boolean | Indicates 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 | |
countryIso2 | String | Country of residence, in ISO 3166-1 alpha-2 format | |
ethnicitiesTop | Array | Top 10 most likely etchnicities, order from most likely to least likely | |
probabilityCalibrated | Number | The calibrated probability for ethnicity to have been guessed correctly. -1 = still calibrating. | |
probabilityAltCalibrated | Number | The 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
firstName | String | true | First name (or given name) |
lastName | String | true | Last name (or family name) |
countryIso2 | String | true | Country 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
score | Number | Higher implies a more reliable result, score is not normalized | |
ethnicityAlt | String | Second most likely ethnicity | |
ethnicity | String | Most likely ethnicity | |
lifted | Boolean | Indicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule | |
countryIso2 | String | Country of residence, in ISO 3166-1 alpha-2 format | |
ethnicitiesTop | Array | Top 10 most likely etchnicities, order from most likely to least likely | |
probabilityCalibrated | Number | The calibrated probability for ethnicity to have been guessed correctly. -1 = still calibrating. | |
probabilityAltCalibrated | Number | The 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
Name | Type | Required | Description |
---|---|---|---|
firstName | String | true | First name (or given name) |
lastName | String | true | Last 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
raceEthnicityAlt | String | Second most likely ethnicity (U.S. race and ethnicity categorization) | “W_NL”, “HL”, “A”, “B_NL”, “AI_AN” or “PI” |
raceEthnicity | String | Most likely ethnicity (U.S. race and ethnicity categorization) | “W_NL”, “HL”, “A”, “B_NL”, “AI_AN” or “PI” |
score | Number | Higher implies a more reliable result, score is not normalized | |
raceEthnicitiesTop | Array | Most likely ethnicity, sorted from most likely to least likely (U.S. race and ethnicity categorization) | |
probabilityCalibrated | Number | Higher implies a more reliable result, ranges from 0 to 1 (for raceEthnicity) | |
probabilityAltCalibrated | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
firstName | String | true | First name (or given name) |
lastName | String | true | Last name (or family name) |
countryIso2 | String | true | Most 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
raceEthnicityAlt | String | Second most likely ethnicity (U.S. race and ethnicity categorization) | “W_NL”, “HL”, “A”, “B_NL”, “AI_AN” or “PI” |
raceEthnicity | String | Most likely ethnicity (U.S. race and ethnicity categorization) | “W_NL”, “HL”, “A”, “B_NL”, “AI_AN” or “PI” |
score | Number | Higher implies a more reliable result, score is not normalized | |
raceEthnicitiesTop | Array | Most likely ethnicity, sorted from most likely to least likely (U.S. race and ethnicity categorization) | |
probabilityCalibrated | Number | Higher implies a more reliable result, ranges from 0 to 1 (for raceEthnicity) | |
probabilityAltCalibrated | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
firstName | String | true | First name (or given name) |
lastName | String | true | Last name (or family name) |
zip5Code | String | true | 5 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
raceEthnicityAlt | String | Second most likely ethnicity (U.S. race and ethnicity categorization) | “W_NL”, “HL”, “A”, “B_NL”, “AI_AN” or “PI” |
raceEthnicity | String | Most likely ethnicity (U.S. race and ethnicity categorization) | “W_NL”, “HL”, “A”, “B_NL”, “AI_AN” or “PI” |
score | Number | Higher implies a more reliable result, score is not normalized | |
raceEthnicitiesTop | Array | Most likely ethnicity, sorted from most likely to least likely (U.S. race and ethnicity categorization) | |
probabilityCalibrated | Number | Higher implies a more reliable result, ranges from 0 to 1 (for raceEthnicity) | |
probabilityAltCalibrated | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
firstName | String | true | First name (or given name) |
lastName | String | true | Last name (or family name) |
countryIso2 | String | true | Most likely country of origin, in ISO 3166-1 alpha-2 format |
zipCode | String | true | 5 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | First name (or given name) | |
lastName | String | Last name (or family name) | |
raceEthnicityAlt | String | Second most likely ethnicity (U.S. race and ethnicity categorization) | “W_NL”, “HL”, “A”, “B_NL”, “AI_AN” or “PI” |
raceEthnicity | String | Most likely ethnicity (U.S. race and ethnicity categorization) | “W_NL”, “HL”, “A”, “B_NL”, “AI_AN” or “PI” |
score | Number | Higher implies a more reliable result, score is not normalized | |
raceEthnicitiesTop | Array | Most likely ethnicity, sorted from most likely to least likely (U.S. race and ethnicity categorization) | |
probabilityCalibrated | Number | Higher implies a more reliable result, ranges from 0 to 1 (for raceEthnicity) | |
probabilityAltCalibrated | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
countryIso2From | String | true | Country of origin of the sender, in ISO 3166-1 alpha-2 format |
firstNameFrom | String | true | First name (or given name) of the sender |
lastNameFrom | String | true | Last name (or family name) of the sender |
countryIso2To | String | true | Country of origin of the receiver, in ISO 3166-1 alpha-2 format |
firstNameTo | String | true | First name (or given name) of the receiver |
lastNameTo | String | true | Last 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.
Name | Type | Description | Enumerators |
---|---|---|---|
id | String | Unique identifier | |
FirstLastNameGenderedOut | Object | ||
{…}.script | String | Character set used for analysis | |
{…}.id | String | Unique identifier | |
{…}.firstName | String | First name (or given name) | |
{…}.lastName | String | Last name (or family name) | |
{…}.likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
{…}.genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
{…}.score | Number | Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available | |
{…}.probabilityCalibrated | Number | Higher implies a more reliable result, ranges from 0 to 1 | |
FirstLastNameOriginedOut | Object | ||
{…}.script | String | Character set used for analysis | |
{…}.id | String | Unique identifier | |
{…}.firstName | String | First name (or given name) | |
{…}.lastName | String | Last name (or family name) | |
{…}.countryOrigin | String | Most likely country of origin, in ISO 3166-1 alpha-2 format | |
{…}.countryOriginAlt | String | Second most likely country of origin, in ISO 3166-1 alpha-2 format | |
{…}.countriesOriginTop | Array | Top 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely | |
{…}.score | Number | Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available | |
{…}.regionOrigin | String | Most likely region of origin | |
{…}.topRegionOrigin | String | Most likely region of origin (alternative classification) | |
{…}.subRegionOrigin | String | Most likely subregion of origin | |
{…}.probabilityCalibrated | Number | Higher implies a more reliable result, ranges from 0 to 1 (for countryOrigin) | |
{…}.probabilityAltCalibrated | Number | Higher implies a more reliable result, ranges from 0 to 1 (for countryOriginAlt) | |
FirstLastNameDiasporaedOut | Object | ||
{…}.script | String | Character set used for analysis | |
{…}.id | String | Unique identifier | |
{…}.firstName | String | First name (or given name) | |
{…}.lastName | String | Last name (or family name) | |
{…}.score | Number | Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available | |
{…}.ethnicityAlt | String | Second most likely ethnicity | |
{…}.ethnicity | String | Most likely ethnicity | |
{…}.lifted | Boolean | Indicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule | |
{…}.countryIso2 | String | Most likely country of origin, in ISO 3166-1 alpha-2 format | |
{…}.ethnicitiesTop | Array | Top 10 most likely etchnicities, order from most likely to least likely | |
{…}.probabilityCalibrated | Number | The calibrated probability for ethnicity to have been guessed correctly. -1 = still calibrating. | |
{…}.probabilityAltCalibrated | Number | The calibrated probability for ethnicity OR ethnicityAlt to have been guessed correctly. -1 = still calibrating. | |
script | String | Character 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
firstLastNameGeoFrom | Object | ||
{…}.id | String | Unique identifier | |
{…}.firstName | String | true | First name (or given name) of the sender |
{…}.lastName | String | true | Last name (or family name) of the sender |
{…}.countryIso2 | String | true | Country of origin of the sender, in ISO 3166-1 alpha-2 format |
firstLastNameGeoTo | Object | ||
{…}.id | String | Unique identifier | |
{…}.firstName | String | true | First name (or given name) of the receiver |
{…}.lastName | String | true | Last name (or family name) of the receiver |
{…}.countryIso2 | String | true | Country 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.
Name | Type | Description | Enumerators |
---|---|---|---|
id | String | Unique identifier | |
FirstLastNameGenderedOut | Object | ||
{…}.script | String | Character set used for analysis | |
{…}.id | String | Unique identifier | |
{…}.firstName | String | First name (or given name) | |
{…}.lastName | String | Last name (or family name) | |
{…}.likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
{…}.genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
{…}.score | Number | Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available | |
{…}.probabilityCalibrated | Number | Higher implies a more reliable result, ranges from 0 to 1 | |
FirstLastNameOriginedOut | Object | ||
{…}.script | String | Character set used for analysis | |
{…}.id | String | Unique identifier | |
{…}.firstName | String | First name (or given name) | |
{…}.lastName | String | Last name (or family name) | |
{…}.countryOrigin | String | Most likely country of origin, in ISO 3166-1 alpha-2 format | |
{…}.countryOriginAlt | String | Second most likely country of origin, in ISO 3166-1 alpha-2 format | |
{…}.countriesOriginTop | Array | Top 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely | |
{…}.score | Number | Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available | |
{…}.regionOrigin | String | Most likely region of origin | |
{…}.topRegionOrigin | String | Most likely region of origin (alternative classification) | |
{…}.subRegionOrigin | String | Most likely subregion of origin | |
{…}.probabilityCalibrated | Number | Higher implies a more reliable result, ranges from 0 to 1 (for countryOrigin) | |
{…}.probabilityAltCalibrated | Number | Higher implies a more reliable result, ranges from 0 to 1 (for countryOriginAlt) | |
FirstLastNameDiasporaedOut | Object | ||
{…}.script | String | Character set used for analysis | |
{…}.id | String | Unique identifier | |
{…}.firstName | String | First name (or given name) | |
{…}.lastName | String | Last name (or family name) | |
{…}.score | Number | Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available | |
{…}.ethnicityAlt | String | Second most likely ethnicity | |
{…}.ethnicity | String | Most likely ethnicity | |
{…}.lifted | Boolean | Indicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule | |
{…}.countryIso2 | String | Most likely country of origin, in ISO 3166-1 alpha-2 format | |
{…}.ethnicitiesTop | Array | Top 10 most likely etchnicities, order from most likely to least likely | |
{…}.probabilityCalibrated | Number | The calibrated probability for ethnicity to have been guessed correctly. -1 = still calibrating. | |
{…}.probabilityAltCalibrated | Number | The calibrated probability for ethnicity OR ethnicityAlt to have been guessed correctly. -1 = still calibrating. | |
script | String | Character 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
Name | Type | Required | Description |
---|---|---|---|
firstName | String | true | First name (or given name) |
lastName | String | true | Last 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
firstName | String | true | First name (or given name) |
lastName | String | true | Last 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
firstName | String | true | First name (or given name) |
lastName | String | true | Last name (or family name) |
countryIso2 | String | true | Most 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
firstName | String | true | First name (or given name) |
lastName | String | true | Last name (or family name) |
countryIso2 | String | true | Most 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
fullName | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
name | String | Submitted full name | |
likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
name | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
name | String | Submitted full name | |
likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
fullName | String | true | Full name (first name and last name) |
countryIso2 | String | true | Most 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
name | String | Submitted full name | |
likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
name | String | true | Full name (first name and last name) |
countryIso2 | String | true | Most 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
name | String | Submitted full name | |
likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
properNoun | String | true | A 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
name | String | Submitted proper noun | |
commonType | String | Most likely type of the proper noun | |
commonTypeAlt | String | Second most likely type of the proper noun | |
score | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
name | String | true | A 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
name | String | Submitted proper noun | |
commonType | String | Most likely type of the proper noun | |
commonTypeAlt | String | Second most likely type of the proper noun | |
score | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
properNoun | String | true | A proper noun (person, brand, etc.) |
countryIso2 | String | true | Most 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
name | String | Submitted proper noun | |
commonType | String | Most likely type of the proper noun | |
commonTypeAlt | String | Second most likely type of the proper noun | |
score | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
name | String | true | A proper noun (person, brand, etc.) |
countryIso2 | String | true | Most 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
name | String | Submitted proper noun | |
commonType | String | Most likely type of the proper noun | |
commonTypeAlt | String | Second most likely type of the proper noun | |
score | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
nameFull | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
name | String | Submitted full name | |
nameParserType | String | 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” |
nameParserTypeAlt | String | Second 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” |
firstLastName | Object | ||
{…}.script | String | Character set used for analysis | |
{…}.id | String | Provided unique identifier | |
{…}.firstName | String | First name (or given name) | |
{…}.lastName | String | Last name (or family name) | |
score | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
name | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
name | String | Submitted full name | |
nameParserType | String | 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” |
nameParserTypeAlt | String | Second 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” |
firstLastName | Object | ||
{…}.script | String | Character set used for analysis | |
{…}.id | String | Provided unique identifier | |
{…}.firstName | String | First name (or given name) | |
{…}.lastName | String | Last name (or family name) | |
score | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
nameFull | String | true | Full name (first name and last name) |
countryIso2 | String | true | Most 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
name | String | Submitted full name | |
nameParserType | String | 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” |
nameParserTypeAlt | String | Second 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” |
firstLastName | Object | ||
{…}.script | String | Character set used for analysis | |
{…}.id | String | Provided unique identifier | |
{…}.firstName | String | First name (or given name) | |
{…}.lastName | String | Last name (or family name) | |
score | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
name | String | true | Full name (first name and last name) |
countryIso2 | String | true | Most 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
name | String | Submitted full name | |
nameParserType | String | 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” |
nameParserTypeAlt | String | Second 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” |
firstLastName | Object | ||
{…}.script | String | Character set used for analysis | |
{…}.id | String | Provided unique identifier | |
{…}.firstName | String | First name (or given name) | |
{…}.lastName | String | Last name (or family name) | |
score | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
japaneseSurnameLatin | String | true | Family name (or last name) in latin characters |
japaneseGivenNameLatin | String | true | Given 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
orderOption | String | Sorting order for matchCandidates | |
matchCandidates | Array of Objects | ||
[ {…} ].candidateName | String | Inferred transcription of the full name to Kanji | |
[ {…} ].probability | Number | Higher implies a more reliable result, ranges from 0 to 1 | |
[ {…} ].predScoreGivenName | Number | Higher implies a more reliable result (for given name or first name) | |
[ {…} ].predScoreFamilyName | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
firstName | String | true | Given name (or first name) in latin characters |
lastName | String | true | Family 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
orderOption | String | Sorting order for matchCandidates | |
matchCandidates | Array of Objects | ||
[ {…} ].candidateName | String | Inferred transcription of the full name to Kanji | |
[ {…} ].probability | Number | Higher implies a more reliable result, ranges from 0 to 1 | |
[ {…} ].predScoreGivenName | Number | Higher implies a more reliable result (for given name or first name) | |
[ {…} ].predScoreFamilyName | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
japaneseSurnameLatin | String | true | Family name (or last name) in latin characters |
japaneseGivenNameLatin | String | true | Given name (or first name) in latin characters |
knownGender | String | true | Gender |
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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
orderOption | String | Sorting order for matchCandidates | |
matchCandidates | Array of Objects | ||
[ {…} ].candidateName | String | Inferred transcription of the full name to Kanji | |
[ {…} ].probability | Number | Higher implies a more reliable result, ranges from 0 to 1 | |
[ {…} ].predScoreGivenName | Number | Higher implies a more reliable result (for given name or first name) | |
[ {…} ].predScoreFamilyName | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
firstName | String | true | Given name (or first name) in latin characters |
lastName | String | true | Family name (or last name) in latin characters |
gender | String | true | Gender |
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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
orderOption | String | Sorting order for matchCandidates | |
matchCandidates | Array of Objects | ||
[ {…} ].candidateName | String | Inferred transcription of the full name to Kanji | |
[ {…} ].probability | Number | Higher implies a more reliable result, ranges from 0 to 1 | |
[ {…} ].predScoreGivenName | Number | Higher implies a more reliable result (for given name or first name) | |
[ {…} ].predScoreFamilyName | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
japaneseSurnameKanji | String | true | Family name (or last name) in Kanji |
japaneseGivenNameKanji | String | true | Given 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
orderOption | String | Sorting order for matchCandidates | |
matchCandidates | Array of Objects | ||
[ {…} ].candidateName | String | Inferred transcription of the full name to latin characters | |
[ {…} ].probability | Number | Higher implies a more reliable result, ranges from 0 to 1 | |
[ {…} ].predScoreGivenName | Number | Higher implies a more reliable result (for given name or first name) | |
[ {…} ].predScoreFamilyName | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
firstName | String | true | Given name (or first name) in Kanji |
lastName | String | true | Family 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
orderOption | String | Sorting order for matchCandidates | |
matchCandidates | Array of Objects | ||
[ {…} ].candidateName | String | Inferred transcription of the full name to latin characters | |
[ {…} ].probability | Number | Higher implies a more reliable result, ranges from 0 to 1 | |
[ {…} ].predScoreGivenName | Number | Higher implies a more reliable result (for given name or first name) | |
[ {…} ].predScoreFamilyName | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
japaneseSurname | String | true | Family name (or last name) in latin characters |
japaneseGivenName | String | true | Given 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
firstName | String | true | Given name (or first name) in latin characters |
lastName | String | true | Family 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
japaneseName | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
name | String | Submitted full name | |
likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
name | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
name | String | Submitted full name | |
likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
japaneseName | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
name | String | Submitted full name | |
nameParserType | String | 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” |
nameParserTypeAlt | String | Second 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” |
firstLastName | Object | ||
{…}.script | String | Character set used for analysis | |
{…}.id | String | Provided unique identifier | |
{…}.firstName | String | First name (or given name) | |
{…}.lastName | String | Last name (or family name) | |
score | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
name | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
name | String | Submitted full name | |
nameParserType | String | 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” |
nameParserTypeAlt | String | Second 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” |
firstLastName | Object | ||
{…}.script | String | Character set used for analysis | |
{…}.id | String | Provided unique identifier | |
{…}.firstName | String | First name (or given name) | |
{…}.lastName | String | Last name (or family name) | |
score | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
japaneseSurnameLatin | String | true | Family name (or last name) in latin characters |
japaneseGivenNameLatin | String | true | Given name (or first name) in latin characters |
japaneseName | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
matchStatus | String | Success status of the match | “Match” or “Mismatch” |
score | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
name1 | Object | ||
{…}.id | String | Unique identifier | |
{…}.firstName | String | true | Given name (or first name) in latin characters |
{…}.lastName | String | true | Family name (or last name) in latin characters |
name2 | Object | ||
{…}.id | String | Unique identifier | |
{…}.name | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
matchStatus | String | Success status of the match | “Match” or “Mismatch” |
score | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
japaneseSurnameLatin | String | true | Family name (or last name) in latin characters |
japaneseGivenNameLatin | String | true | Given name (or first name) in latin characters |
japaneseName | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
feedbackCredits | Integer | Number 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
Name | Type | Required | Description |
---|---|---|---|
chineseSurnameLatin | String | true | Family name (or last name) in Pinyin |
chineseGivenNameLatin | String | true | Given 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
orderOption | String | Sorting order for matchCandidates | |
matchCandidates | Array of Objects | ||
[ {…} ].candidateName | String | Inferred transcription of the full name to Standard Mandarin Chinese | |
[ {…} ].probability | Number | Higher implies a more reliable result, ranges from 0 to 1 | |
[ {…} ].predScoreGivenName | Number | Higher implies a more reliable result (for given name or first name) | |
[ {…} ].predScoreFamilyName | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
firstName | String | true | Given name (or first name) in Pinyin |
lastName | String | true | Family 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
orderOption | String | Sorting order for matchCandidates | |
matchCandidates | Array of Objects | ||
[ {…} ].candidateName | String | Inferred transcription of the full name to Standard Mandarin Chinese | |
[ {…} ].probability | Number | Higher implies a more reliable result, ranges from 0 to 1 | |
[ {…} ].predScoreGivenName | Number | Higher implies a more reliable result (for given name or first name) | |
[ {…} ].predScoreFamilyName | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
chineseSurnameLatin | String | true | Family name (or last name) in Pinyin |
chineseGivenNameLatin | String | true | Given name (or first name) in Pinyin |
knownGender | String | true | Gender |
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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | First name (or given name) | |
lastName | String | Last name (or family name) | |
orderOption | String | Sorting order for matchCandidates | |
matchCandidates | Array of Objects | ||
[ {…} ].candidateName | String | Inferred transcription of the full name to Standard Mandarin Chinese | |
[ {…} ].probability | Number | Higher implies a more reliable result, ranges from 0 to 1 | |
[ {…} ].predScoreGivenName | Number | Higher implies a more reliable result (for given name or first name) | |
[ {…} ].predScoreFamilyName | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
firstName | String | true | Given name (or first name) in Pinyin |
lastName | String | true | Family name (or last name) in Pinyin |
gender | String | true | Gender |
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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
orderOption | String | Sorting order for matchCandidates | |
matchCandidates | Array of Objects | ||
[ {…} ].candidateName | String | Inferred transcription of the full name to Standard Mandarin Chinese | |
[ {…} ].probability | Number | Higher implies a more reliable result, ranges from 0 to 1 | |
[ {…} ].predScoreGivenName | Number | Higher implies a more reliable result (for given name or first name) | |
[ {…} ].predScoreFamilyName | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
chineseName | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
name | String | Submitted full name | |
nameParserType | String | 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” |
nameParserTypeAlt | String | Second 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” |
firstLastName | Object | ||
{…}.script | String | Character set used for analysis | |
{…}.id | String | Provided unique identifier | |
{…}.firstName | String | Most likely first name (or given name) transcription in Pinyin | |
{…}.lastName | String | Most likely last name (or family name) transcription in Pinyin | |
score | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
name | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
name | String | Submitted full name | |
nameParserType | String | 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” |
nameParserTypeAlt | String | Second 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” |
firstLastName | Object | ||
{…}.script | String | Character set used for analysis | |
{…}.id | String | Provided unique identifier | |
{…}.firstName | String | Most likely first name (or given name) transcription in Pinyin | |
{…}.lastName | String | Most likely last name (or family name) transcription in Pinyin | |
score | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
chineseSurnameLatin | String | true | Family name (or last name) in Pinyin |
chineseGivenNameLatin | String | true | Given 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
firstName | String | true | Given name (or first name) in Pinyin |
lastName | String | true | Family 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
chineseName | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
name | String | Submitted full name | |
likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
name | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
name | String | Submitted full name | |
likelyGender | String | Most likely gender | “male”, “female” or “unknown” |
genderScale | Number | Gender scale ranging from -1 (male) to +1 (female) | |
score | Number | Higher implies a more reliable result, score is not normalized | |
probabilityCalibrated | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
chineseName | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
name | String | Submitted full name | |
nameParserType | String | 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” |
nameParserTypeAlt | String | Second 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” |
firstLastName | Object | ||
{…}.script | String | Character set used for analysis | |
{…}.id | String | Provided unique identifier | |
{…}.firstName | String | First name (or given name) in Standard Mandarin Chinese | |
{…}.lastName | String | Last name (or family name) in Standard Mandarin Chinese | |
score | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
name | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
name | String | Submitted full name | |
nameParserType | String | 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” |
nameParserTypeAlt | String | Second 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” |
firstLastName | Object | ||
{…}.script | String | Character set used for analysis | |
{…}.id | String | Provided unique identifier | |
{…}.firstName | String | First name (or given name) in Standard Mandarin Chinese | |
{…}.lastName | String | Last name (or family name) in Standard Mandarin Chinese | |
score | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
chineseSurnameLatin | String | true | Family name (or last name) in Pinyin |
chineseGivenNameLatin | String | true | Given name (or first name) in Pinyin |
chineseName | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
matchStatus | String | Success status of the match | “Match” or “Mismatch” |
score | Number | Higher 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
name1 | Object | ||
{…}.id | String | Unique identifier | |
{…}.firstName | String | true | Family name (or last name) in Pinyin |
{…}.lastName | String | true | Given name (or first name) in Pinyin |
name2 | Object | ||
{…}.id | String | Unique identifier | |
{…}.name | String | true | Full 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
matchStatus | String | Success status of the match | “Match” or “Mismatch” |
score | Number | Higher 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
Name | Type | Required | Description |
---|---|---|---|
firstName | String | true | First name (or given name) |
lastName | String | true | Last name (or family name) |
phoneNumber | String | true | Phone 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
internationalPhoneNumberVerified | String | Phone number, in E.164 format | |
phoneCountryIso2Verified | String | Country of origin of the phone number, in ISO 3166-1 alpha-2 format (according to Libphonenumber) | |
phoneCountryCode | Integer | Most likely country calling code | |
phoneCountryCodeAlt | Integer | Second most likely country calling code | |
phoneCountryIso2 | String | Most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format | |
phoneCountryIso2Alt | String | Second most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format | |
originCountryIso2 | String | Most likely country of origin of the name, in ISO 3166-1 alpha-2 format | |
originCountryIso2Alt | String | Second most likely country of origin of the name, in ISO 3166-1 alpha-2 format | |
phoneNumber | String | Submitted phone number | |
verified | Boolean | Indicates if the phone number could be positively verified using Libphonenumber | |
score | Number | Higher implies a more reliable result, score is not normalized | |
countryIso2 | String | Most 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
firstName | String | true | First name (or given name) |
lastName | String | true | Last name (or family name) |
phoneNumber | String | true | Phone 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | First name (or given name) | |
lastName | String | Last name (or family name) | |
internationalPhoneNumberVerified | String | Phone number, in E.164 format | |
phoneCountryIso2Verified | String | Country of origin of the phone number, in ISO 3166-1 alpha-2 format (according to Libphonenumber) | |
phoneCountryCode | Integer | Most likely country calling code | |
phoneCountryCodeAlt | Integer | Second most likely country calling code | |
phoneCountryIso2 | String | Most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format | |
phoneCountryIso2Alt | String | Second most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format | |
originCountryIso2 | String | Most likely country of origin of the name, in ISO 3166-1 alpha-2 format | |
originCountryIso2Alt | String | Second most likely country of origin of the name, in ISO 3166-1 alpha-2 format | |
phoneNumber | String | Submitted phone number | |
verified | Boolean | Indicates if the phone number could be positively verified using Libphonenumber | |
score | Number | Higher implies a more reliable result, score is not normalized | |
countryIso2 | String | Most 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
Name | Type | Required | Description |
---|---|---|---|
firstName | String | true | First name (or given name) |
lastName | String | true | Last name (or family name) |
phoneNumber | String | true | Phone number, formatted or unformatted |
countryIso2 | String | true | Most 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
firstName | String | Submitted first name | |
lastName | String | Submitted last name | |
internationalPhoneNumberVerified | String | Phone number, in E.164 format | |
phoneCountryIso2Verified | String | Country of origin of the phone number, in ISO 3166-1 alpha-2 format (according to Libphonenumber) | |
phoneCountryCode | Integer | Most likely country calling code | |
phoneCountryCodeAlt | Integer | Second most likely country calling code | |
phoneCountryIso2 | String | Most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format | |
phoneCountryIso2Alt | String | Second most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format | |
originCountryIso2 | String | Most likely country of origin of the name, in ISO 3166-1 alpha-2 format | |
originCountryIso2Alt | String | Second most likely country of origin of the name, in ISO 3166-1 alpha-2 format | |
phoneNumber | String | Submitted phone number | |
verified | Boolean | Indicates if the phone number could be positively verified using Libphonenumber | |
score | Number | Higher implies a more reliable result, score is not normalized | |
countryIso2 | String | Most 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.
Name | Type | Required | Description |
---|---|---|---|
id | String | Unique identifier | |
firstName | String | true | First name (or given name) |
lastName | String | true | Last name (or family name) |
phoneNumber | String | true | Phone number, formatted or unformatted |
countryIso2 | String | true | Most likely country of origin, in ISO 3166-1 alpha-2 format |
countryIso2Alt | String | true | Second 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Provided unique identifier | |
firstName | String | First name (or given name) | |
lastName | String | Last name (or family name) | |
internationalPhoneNumberVerified | String | Phone number, in E.164 format | |
phoneCountryIso2Verified | String | Country of origin of the phone number, in ISO 3166-1 alpha-2 format (according to Libphonenumber) | |
phoneCountryCode | Integer | Most likely country calling code | |
phoneCountryCodeAlt | Integer | Second most likely country calling code | |
phoneCountryIso2 | String | Most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format | |
phoneCountryIso2Alt | String | Second most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format | |
originCountryIso2 | String | Most likely country of origin of the name, in ISO 3166-1 alpha-2 format | |
originCountryIso2Alt | String | Second most likely country of origin of the name, in ISO 3166-1 alpha-2 format | |
phoneNumber | String | Submitted phone number | |
verified | Boolean | Indicates if the phone number could be positively verified using Libphonenumber | |
score | Number | Higher implies a more reliable result, score is not normalized | |
countryIso2 | String | Most 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
Name | Type | Required | Description |
---|---|---|---|
firstName | String | true | First name (or given name) |
lastName | String | true | Last name (or family name) |
phoneNumber | String | true | Phone number, formatted or unformatted |
phoneNumberE164 | String | true | Phone number, in E.164 format |
countryIso2 | String | true | Country 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.
Name | Type | Description | Enumerators |
---|---|---|---|
script | String | Character set used for analysis | |
id | String | Unique identifier | |
firstName | String | First name (or given name) | |
lastName | String | Last name (or family name) | |
internationalPhoneNumberVerified | String | Phone number, in E.164 format | |
phoneCountryIso2Verified | String | Country of origin of the phone number, in ISO 3166-1 alpha-2 format (according to Libphonenumber) | |
phoneCountryCode | Integer | Most likely country calling code | |
phoneCountryCodeAlt | Integer | Second most likely country calling code | |
phoneCountryIso2 | String | Most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format | |
phoneCountryIso2Alt | String | Second most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format | |
originCountryIso2 | String | Most likely country of origin of the name, in ISO 3166-1 alpha-2 format | |
originCountryIso2Alt | String | Second most likely country of origin of the name, in ISO 3166-1 alpha-2 format | |
phoneNumber | String | Submitted phone number | |
verified | Boolean | Indicates if the phone number could be positively verified using Libphonenumber | |
score | Number | Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available | |
countryIso2 | String | Most 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.
Name | Type | Description | Enumerators |
---|---|---|---|
softwareNameAndVersion | String | Name and version of the API | |
softwareVersion | Array | Software 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.
Name | Type | Description | Enumerators |
---|---|---|---|
softwareVersion | Object | ||
{…}.softwareNameAndVersion | String | Name and version of the API | |
{…}.softwareVersion | Array | Software version, as an array (major, minor and patch) | |
classifiers | Array of Objects | ||
[ {…} ].classifierName | String | Name of the classifier / service | |
[ {…} ].serving | Boolean | True if the classifier is serving requests (has reached minimal learning, is not shutting down) | |
[ {…} ].learning | Boolean | True if the classifier is learning | |
[ {…} ].shuttingDown | Boolean | True if the classifier is shutting down | |
[ {…} ].probabilityCalibrated | Boolean | True 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.
Name | Type | Description | Enumerators |
---|---|---|---|
serviceName | String | Name of the classifier / service | |
serviceGroup | String | Group the classifier / service belong to | |
costInUnits | Integer | Usage 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
Name | Type | Required | Description |
---|---|---|---|
classifierName | String | true | Name 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.
Name | Type | Description | Enumerators |
---|---|---|---|
classifierName | String | Name of the submitted classifier | |
taxonomyClasses | Array | Possible 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.
Name | Type | Description | Enumerators |
---|---|---|---|
subscription | Object | ||
{…}.apiKey | String | Your Namsor API key | |
{…}.planStarted | Integer | Start date of the plan, in UNIX time format | |
{…}.priorPlanStarted | Integer | Datetime when the user subscribed to the prior plan | |
{…}.planEnded | Integer | End date of the plan, in UNIX time format | |
{…}.taxRate | Number | Applicable tax rate for the plan | |
{…}.planName | String | Name of the plan | |
{…}.planBaseFeesKey | String | Current plan key (as in Stripe product) | |
{…}.planStatus | String | Plan status | |
{…}.planQuota | Integer | Total number of credits associated with this plan | |
{…}.priceUSD | Number | Price in U.S. dollars ($) | |
{…}.priceOverageUSD | Number | Overage price in U.S. dollars ($) | |
{…}.price | Number | Price in the user’s preferred currency | |
{…}.priceOverage | Number | Overaged price in the user’s preferred currency | |
{…}.currency | String | The user’s preferred currency | |
{…}.currencyFactor | Number | For USD, GBP, EUR - the factor is 1 | |
{…}.stripeCustomerId | String | Unique Stripe Customer identifier | |
{…}.stripeStatus | String | Stripe status | |
{…}.stripeSubscription | String | Stripe subscription identifier | |
{…}.userId | String | Unique user identifier | |
billingPeriod | Object | ||
{…}.apiKey | String | Your Namsor API key | |
{…}.subscriptionStarted | Integer | Subscription start date, in UNIX time format | |
{…}.periodStarted | Integer | Subscription period start date, in UNIX time format | |
{…}.periodEnded | Integer | Subscription end date, in UNIX time format | |
{…}.stripeCurrentPeriodEnd | Integer | End of the current plan in Stripe | |
{…}.stripeCurrentPeriodStart | Integer | Start of the current plan in Stripe | |
{…}.billingStatus | String | Status of the current period billing | |
{…}.usage | Integer | Number of credits used so far | |
{…}.softLimit | Integer | Current soft limit for the period | |
{…}.hardLimit | Integer | Current hard limit for the period | |
overageExclTax | Number | Overage amount including any tax | |
overageInclTax | Number | Overage amount including tax (if applicable) | |
overageCurrency | String | Currency of the overage amount | |
overageQuantity | Integer | Quantity 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.
Name | Type | Description | Enumerators |
---|---|---|---|
apiKey | Object | ||
{…}.apiKey | String | The user API Key. | |
{…}.userId | String | Unique user identifier | |
{…}.admin | Boolean | Does the API Key have admin priviledges | |
{…}.vetted | Boolean | Is the API Key vetted for machine learning | |
{…}.learnable | Boolean | Is the API Key authorised to feed the machine learning | |
{…}.anonymized | Boolean | Is the API Key anonymized (using its SHA-256 digest for logging) | |
{…}.partner | Boolean | Does the API Key have a partnership role | |
{…}.striped | Boolean | Is the API Key associated to a valid Stripe account | |
{…}.corporate | Boolean | Does the API Key have a corporate role | |
{…}.disabled | Boolean | Is the API Key temporarily or permanently disabled | |
apiService | String | Name of the service requested | |
createdDateTime | Integer | Date of the analysis, in UNIX time format | |
totalUsage | Integer | Total cost of the analysis in credits | |
lastFlushedDateTime | Integer | Last time the counter was reset, in UNIX time format | |
lastUsedDateTime | Integer | Last time the API key was used, in UNIX time format | |
serviceFeaturesUsage | Object | Details 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.
Name | Type | Description | Enumerators |
---|---|---|---|
timeUnit | String | Unit of time used in the “rowHeaders” field. May vary depending on API usage (“DAY”, “WEEK” or “MONTH”) | |
periodStart | Integer | Start of the reporting period, in UNIX time format | |
periodEnd | Integer | End of the reporting period, in UNIX time format | |
totalUsage | Integer | Total usage during the current period | |
historyTruncated | Boolean | Indicates if returned data was truncaded due to size limits | |
data | Array | Aggregated API usage, formated as an array of data points (or array of arrays) | |
colHeaders | Array | Column headers used to link API services to the values in each data point | |
rowHeaders | Array | Row 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
Name | Type | Required | Description |
---|---|---|---|
source | String | true | The API Key to set as learnable or non-learnable |
learnable | Boolean | true | Should 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
Name | Type | Required | Description |
---|---|---|---|
source | String | true | The API Key to set as anonymized or non-anonymized |
anonymized | Boolean | true | Should 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
Name | Type | Required | Description |
---|---|---|---|
source | String | true | The API Key to set as enabled or disabled |
disabled | Boolean | true | Should the API key be set to disabled |
Response
In case of a success the API will respond with an HTTP 200 code.