API documentation
Namsor has developed a name checking technology, able to create comprehensive analysis through multiple processing. Our API can classify names by origin, by ethnicity, by residence country, by gender, and supports many alphabets*.
Introduction
About
- The base endpoint URL is: https://v2.namsor.com/NamSorAPIv2
- 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.
- 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 in the "Enhance privacy" section on the my account page. 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 in the "Enhance privacy" section on the my account page. 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
Customer accounts are common to all Namsor group websites. To create an API key visit Namsor or another site of the Namsor group and create an account. Navigate to the account information page to retrieve your API key. Your newly created account comes with 500 free credits that you may use immediately with any of Namsor's tools: API, CSV and Excel file processor or Developer 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.
You must replace your-api-key with your Namsor API key.
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 500 credits but other plans are available in case you have higher requirements. As an example, with 500 credits you can either:
- Process 50 names to determine their origins.
- Process 25 names to determine their ethnicities.
- Process 50 names to determine their US race ethncities.
- Process 50 names to determine their countries of residence.
- Process 500 names to determine their genders.
Admin routes are free.
Repeated Operations Tolerance
Our API features smart processing and it will not charge for analyzing identical data for up to 20 times. For example if you submit the same full name 5 times in order to infer it's origin 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).
Errors
- 401UnauthorizedMissing or incorrect API Key.
- 403ForbiddenAPI Limit Reached or API Key Disabled.
- 404Not FoundThe specified route could not be found.
- 500Internal Server ErrorServer error. Try again later.
Origin from names
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 US race classification. We also provide a corridor evalutation API, to check background information about international interactions.
Name Origin
Name Origin feature analyzes a first name and/or a last name to identify its country of origin with slightly improved accuracy than the Full Name Origin feature. Adding a first and last name increases the accuracy of the determined origin.
The feature returns the region of origin, the country of origin, and a list of the top 10 countries of origin, ordered from most likely to least likely. Each country of origin returned is accompanied by a calibrated probability.
Note that the name diaspora feature may be better suited for multicultural countries, such as the United States, Canada, Australia, New-Zealand and other "melting-pots".
- Description: Returns the most likely country of origin of up to 100 first names and/or last names.
- Precision:
- Cost: 10 credits per name.
- Test: Name Origin feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/originBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal names. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].firstName | String | Optional | First name, given name, nickname. |
[{...}].lastName | String | Optional | Last name, family name, surname. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted names with their countries of origin. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].firstName | String | Submitted first name, given name or nickname. | |
[{...}].lastName | String | Submitted last name, family name or surname. | |
[{...}].countryOrigin | String | Most likely country of origin, in ISO 3166-1 alpha-2 format. | Country of origin |
[{...}].countryOriginAlt | String | Second most likely country of origin, in ISO 3166-1 alpha-2 format. | Country of origin |
[{...}].countriesOriginTop | Array | Top 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely. | Country of origin |
[{...}].score | Number | Higher implies a more reliable result, score is not normalized. | |
[{...}].regionOrigin | String | Most likely region of origin. | Regions of origin or residence |
[{...}].topRegionOrigin | String | Most likely region of origin (alternative classification). | Regions of origin or residence |
[{...}].subRegionOrigin | String | Most likely sub-region of origin. | Sub regions of origin or residence |
[{...}].probabilityCalibrated | Number | The calibrated probability that countryOrigin has been guessed correctly. -1 = still calibrating. | |
[{...}].probabilityAltCalibrated | Number | The calibrated probability that countryOrigin OR countryOriginAlt have been guessed correctly. -1 = still calibrating. |
Code sample:
Name Origin code sample for shell:
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":"Keith","lastName":"Haring"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Keith",
"lastName": "Haring"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Keith",
"lastName": "Haring",
"countryOrigin": "GB",
"countryOriginAlt": "IE",
"countriesOriginTop": ["GB", "IE", "DE", "NL", "EE", "SE", "DK", "MY", "ID", "KH"],
"score": 10.255274142073363,
"regionOrigin": "Europe",
"topRegionOrigin": "Europe",
"subRegionOrigin": "Northern Europe",
"probabilityCalibrated": 0.7724670883776785,
"probabilityAltCalibrated": 0.8719112661893521
}
]
}Full Name Origin
Full Name Origin feature analyzes an unsplit full name (first name and last name) to identify its country of origin.
The feature returns the region of origin, the country of origin, and a list of the top 10 countries of origin, ordered from most likely to least likely. Each country of origin returned is accompanied by a calibrated probability.
Note that the name diaspora feature may be better suited for multicultural countries, such as the United States, Canada, Australia, New-Zealand and other "melting-pots".
If the first and last name are clearly identifiable, the Name Origin feature will be slightly more accurate.
- Description: Returns the most likely country of origin of up to 100 unsplit full names.
- Precision:
- Cost: 10 credits per name.
- Test: Full Name Origin feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/originFullBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal names. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].name | String | Required | Unsplit full name (first name and last name). |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted full names with their countries of origin. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].name | String | Submitted full name. | |
[{...}].countryOrigin | String | Most likely country of origin, in ISO 3166-1 alpha-2 format. | Country of origin |
[{...}].countryOriginAlt | String | Second most likely country of origin, in ISO 3166-1 alpha-2 format. | Country of origin |
[{...}].countriesOriginTop | Array | Top 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely. | Country of origin |
[{...}].score | Number | Higher implies a more reliable result, score is not normalized. | |
[{...}].regionOrigin | String | Most likely region of origin. | Regions of origin or residence |
[{...}].topRegionOrigin | String | Most likely region of origin (alternative classification). | Regions of origin or residence |
[{...}].subRegionOrigin | String | Most likely sub-region of origin. | Sub regions of origin or residence |
[{...}].probabilityCalibrated | Number | The calibrated probability that countryOrigin has been guessed correctly. -1 = still calibrating. | |
[{...}].probabilityAltCalibrated | Number | The calibrated probability that countryOrigin OR countryOriginAlt have been guessed correctly. -1 = still calibrating. |
Code sample:
Full Name Origin code sample for shell:
curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/originFullBatch \
--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":"Keith Haring"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Keith Haring"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Keith Haring",
"countryOrigin": "GB",
"countryOriginAlt": "IE",
"countriesOriginTop": ["GB", "IE", "DE", "NL", "DK", "SE", "CH", "EE", "MY", "HK"],
"score": 11.240061482140302,
"regionOrigin": "Europe",
"topRegionOrigin": "Europe",
"subRegionOrigin": "Northern Europe",
"probabilityCalibrated": 0.8369777938445658,
"probabilityAltCalibrated": 0.9297055536113793
}
]
}Name Diaspora
Name Diaspora feature analyzes a name to identify the most likely ethnicity or diaspora with slightly improved accuracy than the Full Name Diaspora feature. Adding a first and last name and a country of residence increases the accuracy of the determined diaspora.
The feature returns the most likely ethnicity or a diaspora and the top 10 most likely ethnicities, ordered from most likely to least likely. Each ethnicity returned is accompanied by a calibrated probability.
- Description: Returns the most likely ethnicity or diaspora of up to 100 first names (optional) and last names, according to their country of residence.
- Precision:
- Cost: 20 credits per name.
- Test: Name Diaspora feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal names with their country of residence. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].firstName | String | Optional | First name, given name, nickname. |
[{...}].lastName | String | Required | Last name, family name, surname. |
[{...}].countryIso2 | String | Optional | Country of residence, in ISO 3166-1 alpha-2 format. "US" by default (if no value indicated). |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted names with their ethnicities. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].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. | Ethnicities or diasporas |
[{...}].ethnicity | String | Most likely ethnicity. | Ethnicities or diasporas |
[{...}].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 | Submitted country of residence, in ISO 3166-1 alpha-2 format. | Country of residence |
[{...}].ethnicitiesTop | Array | Top 10 most likely ethnicities, ordered from most likely to least likely. | Ethnicities or diasporas |
[{...}].probabilityCalibrated | Number | The calibrated probability that ethnicity has been guessed correctly. -1 = still calibrating . | |
[{...}].probabilityAltCalibrated | Number | The calibrated probability that ethnicity OR ethnicityAlt have been guessed correctly. -1 = still calibrating . |
Code sample:
Name Diaspora code sample for shell:
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":"0d7d6417-0bbb-4205-951d-b3473f605b56","firstName":"Keith","lastName":"Haring","countryIso2":"US"}]}'Body parameter:
{
"personalNames": [
{
"id": "0d7d6417-0bbb-4205-951d-b3473f605b56",
"firstName": "Keith",
"lastName": "Haring",
"countryIso2": "US"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "0d7d6417-0bbb-4205-951d-b3473f605b56",
"firstName": "Keith",
"lastName": "Haring",
"score": 8.653234788906794,
"ethnicityAlt": "British",
"ethnicity": "German",
"lifted": false,
"countryIso2": "US",
"ethnicitiesTop": ["German", "British", "Dutch", "Danish", "Irish", "Norwegian", "Swedish", "Jewish", "NativeHawaiian", "Austrian"],
"probabilityCalibrated": 0.5197497794419499,
"probabilityAltCalibrated": 0.5197497794419499
}
]
}Full Name Diaspora
Full Name Diaspora feature analyzes an unsplit full name (first name and last name) to identify the most likely ethnicity or diaspora.
The feature returns the most likely ethnicity or a diaspora and the top 10 most likely ethnicities, ordered from most likely to least likely. Each ethnicity returned is accompanied by a calibrated probability.
If the first and last name are clearly identifiable, the Name Diaspora feature will be slightly more accurate.
- Description: Returns the most likely ethnicity or diaspora of up to 100 unsplit full names, according to their country of residence.
- Precision:
- Cost: 20 credits per name.
- Test: Full Name Diaspora feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaFullBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal full names with their country of residence. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].name | String | Required | Unsplit full name (first name and last name). |
[{...}].countryIso2 | String | Required | Country of residence, in ISO 3166-1 alpha-2 format. "US" by default (if no value indicated). |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted full names with their ethnicities. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].name | String | Submitted full name. | |
[{...}].score | Number | Higher implies a more reliable result, score is not normalized. | |
[{...}].ethnicityAlt | String | Second most likely ethnicity. | Ethnicities or diasporas |
[{...}].ethnicity | String | Most likely ethnicity. | Ethnicities or diasporas |
[{...}].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 | Submitted country of residence, in ISO 3166-1 alpha-2 format. | Country of residence |
[{...}].ethnicitiesTop | Array | Top 10 most likely ethnicities, ordered from most likely to least likely. | Ethnicities or diasporas |
[{...}].probabilityCalibrated | Number | The calibrated probability that ethnicity has been guessed correctly. -1 = still calibrating . | |
[{...}].probabilityAltCalibrated | Number | The calibrated probability that ethnicity OR ethnicityAlt have been guessed correctly. -1 = still calibrating . |
Code sample:
Full Name Diaspora code sample for shell:
curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaFullBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"0d7d6417-0bbb-4205-951d-b3473f605b56","name":"Keith Haring","countryIso2":"US"}]}'Body parameter:
{
"personalNames": [
{
"id": "0d7d6417-0bbb-4205-951d-b3473f605b56",
"name": "Keith Haring",
"countryIso2": "US"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "0d7d6417-0bbb-4205-951d-b3473f605b56",
"name": "Keith Haring",
"score": 1.9177978014400305,
"ethnicityAlt": "British",
"ethnicity": "German",
"lifted": false,
"countryIso2": "US",
"ethnicitiesTop": ["German", "British", "Dutch", "Irish", "Norwegian", "Danish", "Swedish", "Swiss", "Austrian", "NativeHawaiian"],
"probabilityCalibrated": 0.29971840123154375,
"probabilityAltCalibrated": 0.35544175296700403
}
]
}Name US Race
Name US Race feature analyzes a first name and/or a last name to identify the most likely US race with slightly improved accuracy than the Full Name US Race feature. Adding a first and last name and a country of residence increases the accuracy of the determined US race.
The feature returns the most likely US race ethnicity and a list of the most likely US race ethnicities, sorted from most likely to least likely. Each race returned is accompanied by a calibrated probability.
US race is a categorization from United States Census Taxonomy
- Description: Returns the most likely US race of up to 100 first names and/or last names.
- Precision:
- Cost: 10 credits per name.
- Test: Name US Race feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityBatchRequest header
| Property | Values | Required | Description |
|---|---|---|---|
X-API-KEY | Required | Your Namsor's services API key | |
X-OPTION-USRACEETHNICITY-TAXONOMY | USRACEETHNICITY-6CLASSES | Optional | Enumerators for the returned 'race' ethnicity. Do not specify the property of the http request to obtain 4 classes (W_NL, HL, A, B_NL), USRACEETHNICITY-6CLASSES will return 6 classes (W_NL, HL, A, B_NL, AI_AN, PI). For international names (non US resident) please choose 4 classes. |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal names with their country of residence. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].firstName | String | Optional | First name, given name, nickname. |
[{...}].lastName | String | Optional | Last name, family name, surname. |
[{...}].countryIso2 | String | Optional | Country of residence, in ISO 3166-1 alpha-2 format. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted names with their race. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].firstName | String | Submitted first name. | |
[{...}].lastName | String | Submitted last name. | |
[{...}].raceEthnicityAlt | String | Second most likely race (US race categorization from US Census Taxonomy). | U.S. race ethnicities |
[{...}].raceEthnicity | String | Most likely race (US race categorization from US Census Taxonomy). | U.S. race ethnicities |
[{...}].score | Number | Higher implies a more reliable result, score is not normalized. | |
[{...}].raceEthnicitiesTop | Array | Most likely race, sorted from most likely to least likely (US race categorization from US Census Taxonomy). | U.S. race ethnicities |
[{...}].probabilityCalibrated | Number | The calibrated probability that raceEthnicity has been guessed correctly. -1 = still calibrating. | |
[{...}].probabilityAltCalibrated | Number | The calibrated probability that raceEthnicity OR raceEthnicityAlt have been guessed correctly. -1 = still calibrating. |
Code sample:
Name US Race code sample for shell:
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":"85dd5f48-b9e1-4019-88ce-ccc7e56b763f","firstName":"Keith","lastName":"Haring","countryIso2":"US"}]}'Body parameter:
{
"personalNames": [
{
"id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
"firstName": "Keith",
"lastName": "Haring",
"countryIso2": "US"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
"firstName": "Keith",
"lastName": "Haring",
"raceEthnicityAlt": "B_NL",
"raceEthnicity": "W_NL",
"score": 3.9546190943560813,
"raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
"probabilityCalibrated": 0.619185913005526,
"probabilityAltCalibrated": 0.7534347105665851
}
]
}Name US Race ZIP
Name US Race ZIP feature analyzes a first name and/or a last name to identify the most likely US race with improved accuracy than the basic feature Name US Race. Adding a first and last name and a country of residence increases the accuracy of the determined US race.
The feature returns the most likely US race ethnicity and a list of the most likely US race ethnicities, sorted from most likely to least likely. Each race returned is accompanied by a calibrated probability.
US race is a categorization from United States Census Taxonomy
- Description: Returns the most likely US race of up to 100 first names and/or last names using their ZIP code.
- Precision:
- Cost: 10 credits per name.
- Test: Name US Race ZIP feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/usZipRaceEthnicityBatchRequest header
| Property | Values | Required | Description |
|---|---|---|---|
X-API-KEY | Required | Your Namsor's services API key | |
X-OPTION-USRACEETHNICITY-TAXONOMY | USRACEETHNICITY-6CLASSES | Optional | Enumerators for the returned 'race' ethnicity. Do not specify the property of the http request to obtain 4 classes (W_NL, HL, A, B_NL), USRACEETHNICITY-6CLASSES will return 6 classes (W_NL, HL, A, B_NL, AI_AN, PI). For international names (non US resident) please choose 4 classes. |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal names with their country of residence and postal code. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].firstName | String | Optional | First name, given name, nickname. |
[{...}].lastName | String | Optional | Last name, family name, surname. |
[{...}].countryIso2 | String | Optional | Country of residence, in ISO 3166-1 alpha-2 format. |
[{...}].zipCode | String | Required | Postal code (5-digit) of residence used by the United States Postal Service (USPS). |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted names with their race. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].firstName | String | Submitted first name. | |
[{...}].lastName | String | Submitted last name. | |
[{...}].raceEthnicityAlt | String | Second most likely race (US race categorization from US Census Taxonomy). | U.S. race ethnicities |
[{...}].raceEthnicity | String | Most likely race (US race categorization from US Census Taxonomy). | U.S. race ethnicities |
[{...}].score | Number | Higher implies a more reliable result, score is not normalized. | |
[{...}].raceEthnicitiesTop | Array | Most likely race, sorted from most likely to least likely (US race categorization from US Census Taxonomy). | U.S. race ethnicities |
[{...}].probabilityCalibrated | Number | The calibrated probability that raceEthnicity has been guessed correctly. -1 = still calibrating. | |
[{...}].probabilityAltCalibrated | Number | The calibrated probability that raceEthnicity OR raceEthnicityAlt have been guessed correctly. -1 = still calibrating. |
Code sample:
Name US Race ZIP code sample for shell:
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":"728767f9-c5b2-4ed3-a071-828077f16552","firstName":"Keith","lastName":"Haring","countryIso2":"US","zipCode":"10019"}]}'Body parameter:
{
"personalNames": [
{
"id": "728767f9-c5b2-4ed3-a071-828077f16552",
"firstName": "Keith",
"lastName": "Haring",
"countryIso2": "US",
"zipCode": "10019"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "728767f9-c5b2-4ed3-a071-828077f16552",
"firstName": "Keith",
"lastName": "Haring",
"raceEthnicityAlt": "B_NL",
"raceEthnicity": "W_NL",
"score": 3.9546190943560813,
"raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
"probabilityCalibrated": 0.619185913005526,
"probabilityAltCalibrated": 0.7534347105665851
}
]
}Full Name US Race
Full Name US Race feature analyzes an unsplit full name (first name and last name) to identify the most likely US race.
The feature returns the most likely US race ethnicity and a list of the most likely US race ethnicities, sorted from most likely to least likely. Each race returned is accompanied by a calibrated probability.
US race is a categorization from United States Census Taxonomy
If the first and last name are clearly identifiable, the Name US Race feature will be slightly more accurate.
- Description: Returns the most likely US race of up to 100 unsplit full names.
- Precision:
- Cost: 10 credits per name.
- Test: Full Name US Race feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityFullBatchRequest header
| Property | Values | Required | Description |
|---|---|---|---|
X-API-KEY | Required | Your Namsor's services API key | |
X-OPTION-USRACEETHNICITY-TAXONOMY | USRACEETHNICITY-6CLASSES | Optional | Enumerators for the returned 'race' ethnicity. Do not specify the property of the http request to obtain 4 classes (W_NL, HL, A, B_NL), USRACEETHNICITY-6CLASSES will return 6 classes (W_NL, HL, A, B_NL, AI_AN, PI). For international names (non US resident) please choose 4 classes. |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal full names with their country of residence. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].name | String | Required | Unsplit full name (first name and last name). |
[{...}].countryIso2 | String | Optional | Country of residence, in ISO 3166-1 alpha-2 format. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted full names with their race. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].name | String | Submitted full name. | |
[{...}].raceEthnicityAlt | String | Second most likely race (US race categorization from US Census Taxonomy). | U.S. race ethnicities |
[{...}].raceEthnicity | String | Most likely race (US race categorization from US Census Taxonomy). | U.S. race ethnicities |
[{...}].score | Number | Higher implies a more reliable result, score is not normalized. | |
[{...}].raceEthnicitiesTop | Array | Most likely race, sorted from most likely to least likely (US race categorization from US Census Taxonomy). | U.S. race ethnicities |
[{...}].probabilityCalibrated | Number | The calibrated probability that raceEthnicity has been guessed correctly. -1 = still calibrating. | |
[{...}].probabilityAltCalibrated | Number | The calibrated probability that raceEthnicity OR raceEthnicityAlt have been guessed correctly. -1 = still calibrating. |
Code sample:
Full Name US Race code sample for shell:
curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityFullBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"85dd5f48-b9e1-4019-88ce-ccc7e56b763f","name":"Keith Haring","countryIso2":"US"}]}'Body parameter:
{
"personalNames": [
{
"id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
"name": "Keith Haring",
"countryIso2": "US"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
"name": "Keith Haring",
"raceEthnicityAlt": "B_NL",
"raceEthnicity": "W_NL",
"score": 6.493299531249249,
"raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
"probabilityCalibrated": 0.7239234645232184,
"probabilityAltCalibrated": 0.8814496032861949
}
]
}Name Country
Name Country feature analyzes a first name and/or a last name to identify its country of residence with slightly improved accuracy than the Full Name Country feature.
The feature returns the region of residence, the country of residence, and a list of the top 10 countries of residence, ordered from most likely to least likely. Each country of residence returned is accompanied by a calibrated probability.
- Description: Returns the most likely country of residence of up to 100 first names and/or last names.
- Precision:
- Cost: 10 credits per name.
- Test: Name Country feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/countryFnLnBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal names. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].firstName | String | Optional | First name, given name, nickname. |
[{...}].lastName | String | Optional | Last name, family name, surname. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted names with their countries of residence. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].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. | |
[{...}].country | String | Most likely country of residence, in ISO 3166-1 alpha-2 format. | Country of residence |
[{...}].countryAlt | String | Second most likely country of residence, in ISO 3166-1 alpha-2 format. | Country of residence |
[{...}].region | String | Most likely region of residence. | Regions of origin or residence |
[{...}].topRegion | String | Most likely region of residence (alternative classification). | Regions of origin or residence |
[{...}].subRegion | String | Most likely sub-region of residence. | Sub regions of origin or residence |
[{...}].countriesTop | Array | Top 10 most likely countries of residence, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely. | |
[{...}].probabilityCalibrated | Number | The calibrated probability that country has been guessed correctly. -1 = still calibrating. | |
[{...}].probabilityAltCalibrated | Number | The calibrated probability that country OR countryAlt have been guessed correctly. -1 = still calibrating. |
Code sample:
Name Country code sample for shell:
curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/countryFnLnBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4","firstName":"Keith","lastName":"Haring"}]}'Body parameter:
{
"personalNames": [
{
"id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
"firstName": "Keith",
"lastName": "Haring"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
"firstName": "Keith",
"lastName": "Haring",
"score": 1.0276301745383112,
"country": "AU",
"countryAlt": "GB",
"region": "Oceania",
"topRegion": "Oceania",
"subRegion": "Australia and New Zealand",
"countriesTop": ["AU", "GB", "US", "CA", "NZ", "TT", "SG", "JM", "IE", "DE"],
"probabilityCalibrated": 0.2748899815464943,
"probabilityAltCalibrated": 0.3641355716648853
}
]
}Full Name Country
Full Name Country feature analyzes an unsplit full name (first name and last name) to identify its country of residence.
The feature returns the region of residence, the country of residence, and a list of the top 10 countries of residence, ordered from most likely to least likely. Each country of residence returned is accompanied by a calibrated probability.
If the first and last name are clearly identifiable, the Name Country feature will be slightly more accurate.
- Description: Returns the most likely country of residence of up to 100 unsplit full names.
- Precision:
- Cost: 10 credits per name.
- Test: Full Name Country feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/countryBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal names. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].name | String | Required | Unsplit full name (first name and last name). |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted full names with their countries of residence. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].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 residence, in ISO 3166-1 alpha-2 format. | Country of residence |
[{...}].countryAlt | String | Second most likely country of residence, in ISO 3166-1 alpha-2 format. | Country of residence |
[{...}].region | String | Most likely region of residence. | Regions of origin or residence |
[{...}].topRegion | String | Most likely region of residence (alternative classification). | Regions of origin or residence |
[{...}].subRegion | String | Most likely sub-region of residence. | Sub regions of origin or residence |
[{...}].countriesTop | Array | Top 10 most likely countries of residence, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely. | |
[{...}].probabilityCalibrated | Number | The calibrated probability that country has been guessed correctly. -1 = still calibrating. | |
[{...}].probabilityAltCalibrated | Number | The calibrated probability that country OR countryAlt have been guessed correctly. -1 = still calibrating. |
Code sample:
Full Name Country code sample for shell:
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":"9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4","name":"Keith Haring"}]}'Body parameter:
{
"personalNames": [
{
"id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
"name": "Keith Haring"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
"name": "Keith Haring",
"score": 2.051795198803658,
"country": "GB",
"countryAlt": "NZ",
"region": "Europe",
"topRegion": "Europe",
"subRegion": "Northern Europe",
"countriesTop": ["GB", "NZ", "US", "AU", "IE", "CA", "JM", "TT", "SG", "DE"],
"probabilityCalibrated": 0.22823337808846267,
"probabilityAltCalibrated": 0.24281407862260063
}
]
}Names Corridor
Name Corridor feature analyzes two person's first name, last name, and country of residence to return a comprehensive report of the interaction.
- Description: 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: 20 credits per name.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/corridorBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
corridorFromTo | Array of objects | Required | A list of name pairs, with country code (nameFrom -> nameTo).. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].firstLastNameGeoFrom | Object | Required | . |
{...}.id | String | Optional | Unique identifier. |
{...}.firstName | String | Required | First name (or given name) of the sender. |
{...}.lastName | String | Required | Last name (or family name) of the sender. |
{...}.countryIso2 | String | Required | Country of origin of the sender, in ISO 3166-1 alpha-2 format. |
[{...}].firstLastNameGeoTo | Object | Required | . |
{...}.id | String | Optional | Unique identifier. |
{...}.firstName | String | Required | First name (or given name) of the receiver. |
{...}.lastName | String | Required | Last name (or family name) of the receiver. |
{...}.countryIso2 | String | Required | Country of origin of the receiver, in ISO 3166-1 alpha-2 format. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
corridorFromTo | Array of objects | A list of classified name pairs.. | |
[{...}].id | String | Unique identifier. | |
[{...}].firstLastNameGeoFromGender | Object | Gender data for the sender name. | |
{...}.script | String | Name of the script used for the name, in ISO 15924 format. | Script |
{...}.id | String | Unique identifier. | |
{...}.firstName | String | Submitted first name (or given name) of the sender. | |
{...}.lastName | String | Submitted last name (or family name) of the sender. | |
{...}.likelyGender | String | Most likely gender. | Genders |
{...}.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. | |
[{...}].firstLastNameGeoToGender | Object | Gender data for the receiver name. | |
{...}.script | String | Name of the script used for the name, in ISO 15924 format. | Script |
{...}.id | String | Unique identifier. | |
{...}.firstName | String | Submitted first name (or given name) of the receiver. | |
{...}.lastName | String | Submitted last name (or family name) of the receiver. | |
{...}.likelyGender | String | Most likely gender. | Genders |
{...}.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. | |
[{...}].firstLastNameGeoFromOrigin | Object | Origin data for the sender name. | |
{...}.script | String | Name of the script used for the name, in ISO 15924 format. | Script |
{...}.id | String | Unique identifier. | |
{...}.firstName | String | Submitted first name (or given name) of the sender. | |
{...}.lastName | String | Submitted last name (or family name) of the sender. | |
{...}.countryOrigin | String | Most likely country of origin of the sender, in ISO 3166-1 alpha-2 format. | Country of origin |
{...}.countryOriginAlt | String | Second most likely country of origin of the sender, in ISO 3166-1 alpha-2 format. | Country of origin |
{...}.countriesOriginTop | Array | Top 10 most likely countries of origin of the sender, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely. | Country of origin |
{...}.score | Number | Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available. | |
{...}.regionOrigin | String | Most likely region of origin of the sender. | Regions of origin or residence |
{...}.topRegionOrigin | String | Most likely region of origin of the sender (alternative classification). | Regions of origin or residence |
{...}.subRegionOrigin | String | Most likely sub-region of origin of the sender. | Sub regions of origin or residence |
{...}.probabilityCalibrated | Number | The calibrated probability for countryOrigin to have been guessed correctly. -1 = still calibrating. | |
{...}.probabilityAltCalibrated | Number | The calibrated probability for countryOrigin OR countryOriginAlt to have been guessed correctly. -1 = still calibrating. | |
[{...}].firstLastNameGeoToOrigin | Object | Origin data for the receiver name. | |
{...}.script | String | Name of the script used for the name, in ISO 15924 format. | Script |
{...}.id | String | Unique identifier. | |
{...}.firstName | String | Submitted first name (or given name) of the receiver. | |
{...}.lastName | String | Submitted last name (or family name) of the receiver. | |
{...}.countryOrigin | String | Most likely country of origin of the receiver, in ISO 3166-1 alpha-2 format. | Country of origin |
{...}.countryOriginAlt | String | Second most likely country of origin of the receiver, in ISO 3166-1 alpha-2 format. | Country of origin |
{...}.countriesOriginTop | Array | Top 10 most likely countries of origin of the receiver, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely. | Country of origin |
{...}.score | Number | Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available. | |
{...}.regionOrigin | String | Most likely region of origin. | Regions of origin or residence |
{...}.topRegionOrigin | String | Most likely region of origin of the receiver (alternative classification). | Regions of origin or residence |
{...}.subRegionOrigin | String | Most likely sub-region of origin of the receiver. | Sub regions of origin or residence |
{...}.probabilityCalibrated | Number | The calibrated probability for countryOrigin to have been guessed correctly. -1 = still calibrating. | |
{...}.probabilityAltCalibrated | Number | The calibrated probability for countryOrigin OR countryOriginAlt to have been guessed correctly. -1 = still calibrating. | |
[{...}].firstLastNameGeoFromDiaspora | Object | Diaspora data for the sender name. | |
{...}.script | String | Name of the script used for the name, in ISO 15924 format. | Script |
{...}.id | String | Unique identifier. | |
{...}.firstName | String | Submitted first name (or given name) of the sender. | |
{...}.lastName | String | Submitted last name (or family name) of the sender. | |
{...}.score | Number | Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available. | |
{...}.ethnicityAlt | String | Second most likely ethnicity of the sender. | Ethnicities or diasporas |
{...}.ethnicity | String | Most likely ethnicity of the sender. | Ethnicities or diasporas |
{...}.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 | Submitted country of origin of the sender, in ISO 3166-1 alpha-2 format. | Country of residence |
{...}.ethnicitiesTop | Array | Top 10 most likely ethnicities of the sender, ordered from most likely to least likely. | Ethnicities or diasporas |
[{...}].firstLastNameGeoToDiaspora | Object | Diaspora data for the receiver name. | |
{...}.script | String | Name of the script used for the name, in ISO 15924 format. | Script |
{...}.id | String | Unique identifier. | |
{...}.firstName | String | Submitted first name (or given name) of the receiver. | |
{...}.lastName | String | Submitted last name (or family name) of the receiver. | |
{...}.score | Number | Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available. | |
{...}.ethnicityAlt | String | Second most likely ethnicity of the receiver. | Ethnicities or diasporas |
{...}.ethnicity | String | Most likely ethnicity of the receiver. | Ethnicities or diasporas |
{...}.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 | Submitted country of origin of the receiver, in ISO 3166-1 alpha-2 format. | Country of residence |
{...}.ethnicitiesTop | Array | Top 10 most likely ethnicities of the receiver, ordered from most likely to least likely. | Ethnicities or diasporas |
Code sample:
Names Corridor code sample for shell:
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"}}]}'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"
}
}
]
}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"]
}
}
]
}Gender from names
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*.
Genderize Name
Genderize Name feature analyzes a first name and a last name (optional) to identify its most likely gender with slightly improved accuracy than the Genderize Full Name feature. Adding a first and last name increases the accuracy of the determined gender.
The feature returns the most likely gender accompanied by a calibrated probability. If the probability of the returned gender is between 45% and 55%, the name can be interpreted as a unisex name.
- Description: Returns the most likely gender of up to 100 first names and last names (optional).
- Precision:
- Cost: 1 credit per name.
- Test: Genderize Name feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/genderBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal names. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].firstName | String | Required | First name, given name, nickname. |
[{...}].lastName | String | Optional | Last name, family name, surname. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted names genderized. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].firstName | String | Submitted first name. | |
[{...}].lastName | String | Submitted last name. | |
[{...}].likelyGender | String | Most likely gender. | Genders |
[{...}].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. |
Code sample:
Genderize Name code sample for shell:
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":"b590b04c-da23-4f2f-a334-aee384ee420a","firstName":"Keith","lastName":"Haring"}]}'Body parameter:
{
"personalNames": [
{
"id": "b590b04c-da23-4f2f-a334-aee384ee420a",
"firstName": "Keith",
"lastName": "Haring"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "b590b04c-da23-4f2f-a334-aee384ee420a",
"firstName": "Keith",
"lastName": "Haring",
"likelyGender": "male",
"genderScale": -0.8126510374561324,
"score": 12.516892456249645,
"probabilityCalibrated": 0.9063255187280662
}
]
}Genderize Name Geo
Genderize Name Geo feature analyzes a first name and a last name (optional) based on a country of residence to identify its most likely gender with improved accuracy than the basic feature Genderize Name. Adding a first and last name increases the accuracy of the determined gender.
The feature returns the most likely gender accompanied by a calibrated probability. If the probability of the returned gender is between 45% and 55%, the name can be interpreted as a unisex name.
- Description: Returns the most likely gender of up to 100 first names and last names (optional) using their geographic context.
- Precision:
- Cost: 1 credit per name.
- Test: Genderize Name Geo feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeoBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal names with their country of residence. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].firstName | String | Required | First name, given name, nickname. |
[{...}].lastName | String | Optional | Last name, family name, surname. |
[{...}].countryIso2 | String | Required | Most likely country of residence, in ISO 3166-1 alpha-2 format. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted names genderized. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].firstName | String | Submitted first name. | |
[{...}].lastName | String | Submitted last name. | |
[{...}].likelyGender | String | Most likely gender. | Genders |
[{...}].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. |
Code sample:
Genderize Name Geo code sample for shell:
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":"27fb45db-eddf-40d0-95c1-de9978a166b0","firstName":"Keith","lastName":"Haring","countryIso2":"US"}]}'Body parameter:
{
"personalNames": [
{
"id": "27fb45db-eddf-40d0-95c1-de9978a166b0",
"firstName": "Keith",
"lastName": "Haring",
"countryIso2": "US"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "27fb45db-eddf-40d0-95c1-de9978a166b0",
"firstName": "Keith",
"lastName": "Haring",
"likelyGender": "male",
"genderScale": -0.8889514731555574,
"score": 16.03594419932244,
"probabilityCalibrated": 0.9444757365777787
}
]
}Genderize Full Name
Genderize Full Name feature analyzes an unsplit full name (first name and last name) to identify its most likely gender.
The feature returns the most likely gender accompanied by a calibrated probability. If the probability of the returned gender is between 45% and 55%, the name can be interpreted as a unisex name.
If the first and last name are clearly identifiable, the Genderize Name feature will be slightly more accurate.
- Description: Returns the most likely gender of up to 100 unsplit full names.
- Precision:
- Cost: 1 credit per name.
- Test: Genderize Full Name feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal full names. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].name | String | Required | Unsplit full name (first name and last name). |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted full names genderized. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].name | String | Submitted full name. | |
[{...}].likelyGender | String | Most likely gender. | Genders |
[{...}].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. |
Code sample:
Genderize Full Name code sample for shell:
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":"0f472330-11a9-49ad-a0f5-bcac90a3f6bf","name":"Keith Haring"}]}'Body parameter:
{
"personalNames": [
{
"id": "0f472330-11a9-49ad-a0f5-bcac90a3f6bf",
"name": "Keith Haring"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "0f472330-11a9-49ad-a0f5-bcac90a3f6bf",
"name": "Keith Haring",
"likelyGender": "male",
"genderScale": -0.8744219712791637,
"score": 11.2727995452283,
"probabilityCalibrated": 0.9372109856395818
}
]
}Genderize Full Name Geo
Genderize Full Name Geo feature analyzes an unsplit full name (first name and last name) based on a country of residence, to identify its most likely gender with improved accuracy than the basic feature Genderize Full Name. The feature returns most likely gender accompanied by a calibrated probability. If the probability of the returned gender is between 45% and 55%, the name can be interpreted as a unisex name.
If the first and last name are clearly identifiable, the Genderize Name Geo feature will be slightly more accurate.
- Description: Returns the most likely gender of up to 100 unsplit full names, according to their geographic context.
- Precision:
- Cost: 1 credit per name.
- Test: Genderize Full Name Geo feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeoBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal full names with their country of residence. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].name | String | Required | Unsplit full name (first name and last name). |
[{...}].countryIso2 | String | Required | Country of residence, in ISO 3166-1 alpha-2 format. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted full names genderized. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].name | String | Submitted full name. | |
[{...}].likelyGender | String | Most likely gender. | Genders |
[{...}].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. |
Code sample:
Genderize Full Name Geo code sample for shell:
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":"3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f","name":"Keith Haring","countryIso2":"US"}]}'Body parameter:
{
"personalNames": [
{
"id": "3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f",
"name": "Keith Haring",
"countryIso2": "US"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f",
"name": "Keith Haring",
"likelyGender": "male",
"genderScale": -0.8716298606148474,
"score": 11.225679376737641,
"probabilityCalibrated": 0.9358149303074237
}
]
}Name Type Recognition
Namsor provides a specialized proper name type determination API, it is trained to analyse proper names and infer if they are personal names (anthroponym), a geographic name (toponym) 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.
Name Type
Name Type feature analyzes a proper noun to determine if it's the name of a person (anthroponym), a geographic name (toponym), an alias of a person (pseudonym) or the name of a brand. We recommend that you submit the entire name (full name) if applicable.
- Description: Returns the type of up to 100 submitted proper nouns. Ex: John Smith = personal name, Namsor = brand name, Cherbourg en Cotentin = toponym, Batman = pseudonym.
- Precision:
- Cost: 1 credit per name.
- Test: Name Type feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
properNouns | Array of objects | Required | A list of proper names. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].name | String | Required | A proper noun (person, brand, etc.). |
| Name | Type | Description | Enumerators |
|---|---|---|---|
properNouns | Array of objects | A list of commonTypeized names.. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].name | String | Submitted proper noun. | |
[{...}].commonType | String | Most likely type of the proper noun. | Name types |
[{...}].commonTypeAlt | String | Second most likely type of the proper noun. | Name types |
[{...}].score | Number | Higher implies a more reliable result, score is not normalized. |
Code sample:
Name Type code sample for shell:
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"}]}'Body parameter:
{
"properNouns": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Zippo"
}
]
}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
}
]
}Name Type Geo
Name Type Geo feature analyzes a proper noun based on a local context to determine if it's the name of a person (anthroponym), a geographic name (toponym), an alias of a person (pseudonym) or the name of a brand, with improved accuracy than the basic feature Name Type.
- Description: Returns the type of up to 100 submitted proper nouns using their geographic context. Ex: John Smith = personal name, Namsor = brand name, Cherbourg en Cotentin = toponym, Batman = pseudonym.
- Precision:
- Cost: 1 credit per name.
- Test: Name Type Geo feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeGeoBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
properNouns | Array of objects | Required | A list of proper names. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].name | String | Required | A proper noun (person, brand, etc.). |
[{...}].countryIso2 | String | Required | Most likely country of origin, in ISO 3166-1 alpha-2 format. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
properNouns | Array of objects | A list of commonTypeized names.. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].name | String | Submitted proper noun. | |
[{...}].commonType | String | Most likely type of the proper noun. | Name types |
[{...}].commonTypeAlt | String | Second most likely type of the proper noun. | Name types |
[{...}].score | Number | Higher implies a more reliable result, score is not normalized. |
Code sample:
Name Type Geo code sample for shell:
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"}]}'Body parameter:
{
"properNouns": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Edi Gathegi",
"countryIso2": "KE"
}
]
}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
}
]
}Split names
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.
Split Name
Split Name feature identifies the first name and the last name from an unsplit full name. The Split Name Geo feature helps improve accuracy when splitting the full name by adding a country of residence.
- Description: Returns the most likely first name and last name structure of up to 100 full names.
- Cost: 1 credit per name.
- Test: Split Name feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/parseNameBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of unsplit full names. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].name | String | Required | Full name (first name and last name). |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted names separated into first name and last name structure. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].name | String | Submitted full name. | |
[{...}].nameParserType | String | Most likely structure of the name. | Name structures |
[{...}].nameParserTypeAlt | String | Second most likely structure of the name. | Name structures |
[{...}].firstLastName | Object | Split name. | |
{...}.script | String | Name of the script used for the name, in ISO 15924 format. | Script |
{...}.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. |
Code sample:
Split Name code sample for shell:
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"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "John Smith"
}
]
}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
}
]
}Split Name Geo
Split Name Geo feature processes an unsplit full name with a country of residence to identify the first name and the last name, with improved accuracy than the basic feature Split Name.
- Description: Returns the most likely first name and last name structure of up to 100 full names using their geographic context.
- Cost: 1 credit per name.
- Test: Split Name Geo feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/parseNameGeoBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of unsplit full names with their country of residence. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].name | String | Required | Full name (first name and last name). |
[{...}].countryIso2 | String | Required | Most likely country of origin, in ISO 3166-1 alpha-2 format. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted names separated into first name and last name structure. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].name | String | Submitted full name. | |
[{...}].nameParserType | String | Most likely structure of the name. | Name structures |
[{...}].nameParserTypeAlt | String | Second most likely structure of the name. | Name structures |
[{...}].firstLastName | Object | Split name. | |
{...}.script | String | Name of the script used for the name, in ISO 15924 format. | Script |
{...}.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. |
Code sample:
Split Name Geo code sample for shell:
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"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Ricardo Darín",
"countryIso2": "AR"
}
]
}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
}
]
}Japanese names
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.
Translate Japanese Name To Latin
Translate Japanese Name To Latin feature converts a Japanese given name or a Japanese surname (or both for more precision) written in Kanji characters, into Latin alphabet. The conversion of a Japanese name written in Kanji into Latin alphabet is called romanization. Several conversions for the same name are possible. This is why the feature returns a list of converted names, accompanied by a calibrated probability and sorted from most likely to least likely.
- Description: Returns the most likely latin transcriptions for up to 100 Japanese given names and/or surnames in Kanji characters.
- Cost: 1 credit per name.
- Test: Translate Japanese Name To Latin feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameLatinCandidatesBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal Japanese names in Kanji characters. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].firstName | String | Optional | Japanese given name (or first name) in Kanji. |
[{...}].lastName | String | Optional | Japanese surname (or family name) in Kanji. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
namesAndMatchCandidates | Array of objects | List of submitted names converted to Latin alphabet. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].firstName | String | Submitted given name. | |
[{...}].lastName | String | Submitted surname. | |
[{...}].orderOption | String | Sorting order for matchCandidates. | |
[{...}].matchCandidates | Array of objects | List of possible transcriptions for the submitted name. | |
[{...}].candidateName | String | Inferred transcription of the submitted name to Latin alphabet. | |
[{...}].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). |
Code sample:
Translate Japanese Name To Latin code sample for shell:
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":"千春"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "塩田",
"lastName": "千春"
}
]
}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
}
]
}
]
}Translate Japanese Name To Kanji
Translate Japanese Name To Kanji feature transcribes a Japanese given name or a Japanese surname (or both for more precision) written in Latin alphabet, into Kanji characters. The conversion of a Japanese name written in Kanji into Latin alphabet is called romanization. Several transcriptions for the same name are possible. This is why the feature returns a list of transcribed names, accompanied by a calibrated probability and sorted from most likely to least likely.
The name transcription will work with greater accuracy for names identified as Japanese.
- Description: Returns the most likely Kanji transcriptions for up to 100 Japanese given names and/or surnames in Latin alphabet (romanized).
- Precision:
- Cost: 1 credit per name.
- Test: Translate Japanese Name To Kanji feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidatesBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal Japanese names in Latin alphabet. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].firstName | String | Optional | Japanese given name (or first name) in Latin. |
[{...}].lastName | String | Optional | Japanese surname (or family name) in Latin. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
namesAndMatchCandidates | Array of objects | List of submitted names converted to Kanji characters. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].firstName | String | Submitted given name. | |
[{...}].lastName | String | Submitted surname. | |
[{...}].orderOption | String | Sorting order for matchCandidates. | |
[{...}].matchCandidates | Array of objects | List of possible transcriptions for the submitted name. | |
[{...}].candidateName | String | Inferred transcription of the submitted 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). |
Code sample:
Translate Japanese Name To Kanji code sample for shell:
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"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Sanae",
"lastName": "Yamamoto"
}
]
}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
}
]
}
]
}Translate Japanese Name To Kanji Gender
Translate Japanese Name To Kanji Gender feature transcribes a Japanese given name or a Japanese surname (or both) written in Latin alphabet, into Kanji characters. This feature is based on gender to improved accuracy of the transcription than the basic feature Translate Japanese Name To Kanji. The feature returns a list of the most likely transcribed names accompanied by a calibrated probability and sorted from most likely to least likely.
The name transcription will work with greater accuracy for names identified as Japanese.
- Description: Returns the most likely Kanji transcriptions for up to 100 Japanese given names and/or surnames in Latin alphabet, according to their gender.
- Precision:
- Cost: 1 credit per name.
- Test: Translate Japanese Name To Kanji Gender feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameGenderKanjiCandidatesBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal Japanese names in Latin alphabet and their known gender. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].firstName | String | Optional | Japanese given name (or first name) in Latin. |
[{...}].lastName | String | Optional | Japanese surname (or family name) in Latin. |
[{...}].gender | String | Required | Most likely gender (female, or male). |
| Name | Type | Description | Enumerators |
|---|---|---|---|
namesAndMatchCandidates | Array of objects | List of submitted names converted to Kanji characters. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].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 | List of possible transcriptions for the submitted name. | |
[{...}].candidateName | String | Inferred transcription of the submitted 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). |
Code sample:
Translate Japanese Name To Kanji Gender code sample for shell:
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"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Takashi",
"lastName": "Murakami",
"gender": "male"
}
]
}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
}
]
}
]
}Match Japanese Name
Match Japanese Name feature assesses and grades the quality of a transcription between a Japanese name in Latin characters and a Japanese name in Kanji. The feature returns the status of the match, and scores the names transcription.
- Description: Matches up to 100 full names in Kanji against corresponding family names and given names in Latin alphabet.
- Cost: 1 credit per name.
- Test: Match Japanese Name feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameMatchBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal Japanese names in Kanji characters and in Latin aplhabet. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].name1 | Object | Required | . |
{...}.id | String | Optional | Unique identifier. |
{...}.firstName | String | Required | Japanese given name (or first name) in Latin alphabet. |
{...}.lastName | String | Required | Japanese surname (or family name) in Latin alphabet. |
[{...}].name2 | Object | Required | . |
{...}.id | String | Optional | Unique identifier. |
{...}.name | String | Required | Japanese full name (family name and given name) in Kanji. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
matchedNames | Array of objects | List of submitted Japanese names with the status of their transcription. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].matchStatus | String | Success status of the match. | Match status |
[{...}].score | Number | Higher implies a better match, score is not normalized. |
Code sample:
Match Japanese Name code sample for shell:
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":"富岡 鉄斎"}}]}'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": "富岡 鉄斎"
}
}
]
}The above command returns JSON structured like this:
{
"matchedNames": [
{
"script": null,
"id": null,
"matchStatus": "Match",
"score": 1.002224089213585
}
]
}Genderize Japanese Name
Genderize Japanese Name feature accurately identifies the gender of a Japanese given name and a Japanese surname (optional), written in Kanji or in Latin alphabet, with slightly improved accuracy than the Genderize Japanese Full Name feature. The feature returns the most likely gender accompanied by a calibrated probability. If the probability of the returned gender is between 45% and 55%, the name can be interpreted as a gender neutral name.
- Description: Returns the most likely gender of up to 100 Japanese given names and surnames (optional) in Latin alphabet or in Kanji characters.
- Precision:
- Cost: 1 credit per name.
- Test: Genderize Japanese Name feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of Japanese names. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].firstName | String | Required | Japanese given name (first name) in Latin or Kanji characters. |
[{...}].lastName | String | Optional | Japanese surname (family name) in Latin or Kanji characters. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted Japanese names genderized. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].firstName | String | Submitted given name. | |
[{...}].lastName | String | Submitted surname. | |
[{...}].likelyGender | String | Most likely gender. | Genders |
[{...}].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. |
Code sample:
Genderize Japanese Name code sample for shell:
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"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Satoshi",
"lastName": "Nakamoto"
}
]
}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
}
]
}Genderize Japanese Full Name
Genderize Japanese Full Name feature accurately identifies the gender of an unsplit Japanese full name (surname andgiven name) written in Kanji characters. The feature returns most likely gender accompanied by a calibrated probability. If the probability of the returned gender is between 45% and 55%, the name can be interpreted as a unisex name.
If the given and surname are clearly identifiable, the Genderize Japanese Name feature will be slightly more accurate.
- Description: Returns the most likely gender of up to 100 unsplit Japanese full names (surnames and given names), written in Kanji characters or in Latin alphabet.
- Precision:
- Cost: 1 credit per name.
- Test: Genderize Japanese Full Name feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFullBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of Japanese full names. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].name | String | Required | Unsplit Japanese full name (given name and surname) in Kanji or Latin alphabet. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted Japanese full names genderized. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].name | String | Submitted full name. | |
[{...}].likelyGender | String | Most likely gender. | Genders |
[{...}].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. |
Code sample:
Genderize Japanese Full Name code sample for shell:
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":"中松 義郎"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "中松 義郎"
}
]
}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
}
]
}Split Japanese Name
Split Japanese Name feature accurately identifies the given name and the surname from an unsplit Japanese full name written in Latin alphabet or in Kanji characters.
- Description: Returns the most likely given name and surname structure of up to 100 full names (family names and given names) in Kanji or Latin alphabet.
- Precision:
- Cost: 1 credit per name.
- Test: Split Japanese Name feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/parseJapaneseNameBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of Japanese unsplit full names. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].name | String | Required | Japanese full name (given name and surname) in Kanji or Latin alphabet. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted Japanese names separated into given name and surname structure. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].name | String | Submitted full name. | |
[{...}].nameParserType | String | Most likely structure of the name. | Name structures |
[{...}].nameParserTypeAlt | String | Second most likely structure of the name. | Name structures |
[{...}].firstLastName | Object | Split name. | |
{...}.script | String | Name of the script used for the name, in ISO 15924 format. | Script |
{...}.id | String | Provided unique identifier. | |
{...}.firstName | String | Given name (or first name). | |
{...}.lastName | String | Surname (or family name). | |
[{...}].score | Number | Higher implies a more reliable result, score is not normalized. |
Code sample:
Split Japanese Name code sample for shell:
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":"小島 秀夫"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "小島 秀夫"
}
]
}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
}
]
}Chinese names
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.
Translate Chinese Name To Pinyin
Translate Chinese Name To Pinyin feature transcribes a Chinese full name written in standard Mandarin Chinese, into Pinyin (Latin alphabet). Pinyin is used to depict Mandarin logograms with the Latin alphabet, used by languages such as English.
The name transcription in Pinyin will only work with a Chinese full name (given name and surname).
- Description: Returns the most likely Pinyin transcription of up to 100 Chinese full names (given name and surname) in Standard Mandarin Chinese.
- Cost: 1 credit per name.
- Test: Translate Chinese Name To Pinyin feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/pinyinChineseNameBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal Chinese full names (given name and surname) in standard Mandarin Chinese. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].name | String | Required | Chinese full name (given name and surname) in Standard Mandarin Chinese. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted names converted to Pinyin (Latin alphabet). | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].name | String | Submitted full name. | |
[{...}].nameParserType | String | Most likely structure of the name. | Name structures |
[{...}].nameParserTypeAlt | String | Second most likely structure of the name. | Name structures |
[{...}].firstLastName | Object | Transcribed name. | |
{...}.script | String | Name of the script used for the name, in ISO 15924 format. | Script |
{...}.id | String | Provided unique identifier. | |
{...}.firstName | String | Most likely given name (or first name) transcription in Pinyin. | |
{...}.lastName | String | Most likely surname (or family name or last name) transcription in Pinyin. | |
[{...}].score | Number | Higher implies a more reliable result, score is not normalized. |
Code sample:
Translate Chinese Name To Pinyin code sample for shell:
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":"赵丽颖"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "赵丽颖"
}
]
}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
}
]
}Translate Chinese Name To Mandarin
Translate Chinese Name To Mandarin feature transcribes a Chinese given name or a Chinese surname or both (for more precision) written in Pinyin (Latin alphabet), into standard Mandarin Chinese. Pinyin is used to depict Mandarin logograms with the Latin alphabet, used by languages such as English. Several transcriptions for the same name are possible. This is why the feature returns a list of transcribed names, accompanied by a calibrated probability and sorted from most likely to least likely.
Mandarin name transcription will only work with given names and surnames identified as Chinese.
- Description: Returns the most likely Standard Mandarin Chinese transcriptions using up to 100 given names and/or surnames in Pinyin.
- Precision:
- Cost: 1 credit per name.
- Test: Translate Chinese Name To Mandarin feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameCandidatesBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal Chinese names in Pinyin (Latin alphabet). |
[{...}].id | String | Optional | Unique identifier. |
[{...}].firstName | String | Optional | Chinese given name (or first name) in Pinyin. |
[{...}].lastName | String | Optional | Chinese surname (or family name or last name) in Pinyin. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
namesAndMatchCandidates | Array of objects | List of submitted names converted to standard mandarin Chinese. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].firstName | String | Submitted given name. | |
[{...}].lastName | String | Submitted surname. | |
[{...}].orderOption | String | Sorting order for matchCandidates. | |
[{...}].matchCandidates | Array of objects | List of possible transcriptions for the submitted name. | |
[{...}].candidateName | String | Inferred transcription of the submitted 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 surname or last name). |
Code sample:
Translate Chinese Name To Mandarin code sample for shell:
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"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "LiYing",
"lastName": "Zhao"
}
]
}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
}
]
}
]
}Translate Chinese Name To Mandarin Gender
Translate Chinese Name To Mandarin Gender feature transcribes a Chinese given name or a Chinese surname or both written in Pinyin (Latin alphabet), into standard Mandarin Chinese. This feature is based on gender to improve accuracy of the transcription than the basic feature Translate Chinese Name To Mandarin. The feature returns a list of the most likely transcribed names accompanied by a calibrated probability and sorted from most likely to least likely.
Mandarin name transcription will only work with given names and surnames identified as Chinese.
- Description: Returns the most likely Standard Mandarin Chinese transcriptions for up to 100 Pinyin given names and/or surnames, according to their gender.
- Precision:
- Cost: 1 credit per name.
- Test: Translate Chinese Name To Mandarin Gender feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameCandidatesGenderBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal Chinese names in Pinyin (Latin alphabet) and their known gender. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].firstName | String | Optional | Chinese given name (or first name) in Pinyin. |
[{...}].lastName | String | Optional | Chinese surname (or family name or last name) in Pinyin. |
[{...}].gender | String | Required | Gender (female or male). |
| Name | Type | Description | Enumerators |
|---|---|---|---|
namesAndMatchCandidates | Array of objects | List of submitted names converted to standard mandarin Chinese. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].firstName | String | Submitted given name. | |
[{...}].lastName | String | Submitted surname. | |
[{...}].orderOption | String | Sorting order for matchCandidates. | |
[{...}].matchCandidates | Array of objects | List of possible transcriptions for the submitted name. | |
[{...}].candidateName | String | Inferred transcription of the submitted 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 surname or last name). |
Code sample:
Translate Chinese Name To Mandarin Gender code sample for shell:
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"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "LiYing",
"lastName": "Zhao",
"gender": "female"
}
]
}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
}
]
}
]
}Match Chinese Name
Match Chinese Name feature assesses and grades the quality of a transcription between a Chinese name in Latin characters (Pinyin) and a Chinese name in standard Mandarin Chinese. The feature returns the status of the match, and scores the names transcription.
- Description: Matches up to 100 full names in Standard Mandarin Chinese against corresponding given names and surnames in Pinyin.
- Cost: 1 credit per name.
- Test: Match Chinese Name feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/chineseNameMatchBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal Chinese names in Pinyin and in Mandarin Chinese. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].name1 | Object | Required | . |
{...}.id | String | Optional | Unique identifier. |
{...}.firstName | String | Required | Chinese surname (or family name or last name) in Pinyin. |
{...}.lastName | String | Required | Chinese given name (or first name) in Pinyin. |
[{...}].name2 | Object | Required | . |
{...}.id | String | Optional | Unique identifier. |
{...}.name | String | Required | Chinese full name (given name and surname) in Standard Mandarin Chinese. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
matchedNames | Array of objects | List of submitted Chinese names with the status of their transcription. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].matchStatus | String | Success status of the match. | Match status |
[{...}].score | Number | Higher implies a better match, score is not normalized. |
Code sample:
Match Chinese Name code sample for shell:
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":"喻红"}}]}'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": "喻红"
}
}
]
}The above command returns JSON structured like this:
{
"matchedNames": [
{
"script": null,
"id": null,
"matchStatus": "Match",
"score": 1.0017825620273417
}
]
}Genderize Chinese Name
Genderize Chinese Name feature accurately identifies the gender of a Chinese given name and a Chinese surname (optional), written in Latin alphabet (Pinyin) or Standard Mandarin Chinese, with slightly improved accuracy than the Genderize Chinese Full Name feature. The feature returns the most likely gender accompanied by a calibrated probability. If the probability of the returned gender is between 45% and 55%, the name can be interpreted as a gender neutral name.
- Description: Returns the most likely gender of up to 100 given names and surnames (optional) in Pinyin or standard Mandarin Chinese.
- Precision:
- Cost: 1 credit per name.
- Test: Genderize Chinese Name feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNamePinyinBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of Chinese names. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].firstName | String | Required | Chinese given name (first name) in Pinyin or standard Mandarin Chinese. |
[{...}].lastName | String | Optional | Chinese surname (last name) in Pinyin or standard Mandarin Chinese. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted Chinese names genderized. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].firstName | String | Submitted given name. | |
[{...}].lastName | String | Submitted surname. | |
[{...}].likelyGender | String | Most likely gender. | Genders |
[{...}].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. |
Code sample:
Genderize Chinese Name code sample for shell:
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"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Dèng",
"lastName": "Qīngyún"
}
]
}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
}
]
}Genderize Chinese Full Name
Genderize Chinese Full Name feature accurately identifies the gender of an unsplit Chinese full name written in standard Mandarin Chinese. The feature returns most likely gender accompanied by a calibrated probability. If the probability of the returned gender is between 45% and 55%, the name can be interpreted as a unisex name.
The Genderize Chinese Full Name feature will only work with Chinese full names written in standard Mandarin Chinese.
- Description: Returns the most likely gender of up to 100 unsplit Chinese full names (family names and given names) in in Standard Mandarin Chinese.
- Precision:
- Cost: 1 credit per name.
- Test: Genderize Chinese Full Name feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNameBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of Chinese full names. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].name | String | Required | Unsplit Chinese full name (given name and surname) in Standard Mandarin Chinese. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted Chinese full names genderized. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].name | String | Submitted full name. | |
[{...}].likelyGender | String | Most likely gender. | Genders |
[{...}].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. |
Code sample:
Genderize Chinese Full Name code sample for shell:
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":"谢晓亮"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "谢晓 亮"
}
]
}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
}
]
}Split Chinese Name
Split Chinese Name feature accurately identifies the given name and the surname from an unsplit Chinese full name written in Latin alphabet (Pinyin) or in standard Mandarin Chinese.
- Description: Returns the most likely given name and surname structure of up to 100 full names in Standard Mandarin Chinese or in Pinyin.
- Precision:
- Cost: 1 credit per name.
- Test: Split Chinese Name feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/parseChineseNameBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of Chinese unsplit full names. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].name | String | Required | Chinese full name (given name and surname) in Standard Mandarin Chinese or Pinyin. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted Chinese names separated into given name and surname structure. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].name | String | Submitted full name. | |
[{...}].nameParserType | String | Most likely structure of the name. | Name structures |
[{...}].nameParserTypeAlt | String | Second most likely structure of the name. | Name structures |
[{...}].firstLastName | Object | Split name. | |
{...}.script | String | Name of the script used for the name, in ISO 15924 format. | Script |
{...}.id | String | Provided unique identifier. | |
{...}.firstName | String | Given name (or first name) in Standard Mandarin Chinese. | |
{...}.lastName | String | Surname (or family name or last name) in Standard Mandarin Chinese. | |
[{...}].score | Number | Higher implies a more reliable result, score is not normalized. |
Code sample:
Split Chinese Name code sample for shell:
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":"赵丽颖"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "赵丽颖"
}
]
}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
}
]
}Indian names
Namsor has developed extended functionality for Indian names. You will be able to determine a personn's caste group or religion from their first and/or last name. It is also possible to estimate the state or Union territory of residence directly from the name.
Caste Indian Name
Caste Indian Name feature analyzes a first name, a last name and an Indian state or Union territory of residence to determine the person's most likely caste group.Adding the first and last name increases the accuracy of the estimated religion. If the first and last name are not clearly identifiable, please use the Caste Indian Full Name feature.
- Description: Returns the caste from first names, last names and territories of residence.
- Cost: 10 credits per name.
- Test: Caste Indian Name feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/castegroupIndianBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal full names with their State or Union territory of origin or residence. |
[{...}].id | String | Optional | Provided unique identifier. |
[{...}].firstName | String | Optional | Indian first name, given name, nickname. |
[{...}].lastName | String | Optional | Indian last name, family name, surname. |
[{...}].subdivisionIso | String | Required | Indian state or Union territory (origin or residence), in ISO 3166-2 format. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted full names with their caste group. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].firstName | String | Provided first name. | |
[{...}].lastName | String | Provided last name. | |
[{...}].castegroup | String | Most likely caste group. | Indian caste groups |
[{...}].castegroupAlt | String | Second most likely caste group. | Indian caste groups |
[{...}].castegroupTop | Array | Top of the most likely caste group, sorted from most likely to least likely. | Indian caste groups |
[{...}].score | Number | Higher implies a more reliable result, score is not normalized. | |
[{...}].probabilityCalibrated | Number | The calibrated probability that castegroup has been guessed correctly. -1 = still calibrating. | |
[{...}].probabilityAltCalibrated | Number | The calibrated probability that castegroup OR castegroupAlt have been guessed correctly. -1 = still calibrating. |
Code sample:
Caste Indian Name code sample for shell:
curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/castegroupIndianBatch \
--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":"Akash","lastName":"Sharma","subdivisionIso":"IN-UP"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Akash",
"lastName": "Sharma",
"subdivisionIso": "IN-UP"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "string",
"firstName": "Akash",
"lastName": "Sharma",
"castegroup": "General/High Caste",
"castegroupAlt": "General",
"castegroupTop": ["General/High Caste", "General", "OBC", "SC", "ST"],
"score": 11.127678155723578,
"probabilityCalibrated": 0.7031015750163506,
"probabilityAltCalibrated": 0.9535225800378421
}
]
}Caste Indian Full Name
Caste Indian Full Name feature analyzes an unsplit Indian full name and a Indian state or Union territory of residence to determine the person's most likely caste group.
- Description: Returns the caste from unsplit Indian full names and territories of residence.
- Cost: 10 credits per name.
- Test: Caste Indian Full Name feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/castegroupIndianFullBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal full names with their State or Union territory of origin or residence. |
[{...}].id | String | Optional | Provided unique identifier. |
[{...}].name | String | Required | Unsplit Indian full name (first name and last name). |
[{...}].subdivisionIso | String | Required | Indian state or Union territory (origin or residence), in ISO 3166-2 format. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted full names with their caste group. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].name | String | Provided full name. | |
[{...}].score | Number | Higher implies a more reliable result, score is not normalized. | |
[{...}].castegroup | String | Most likely caste group. | Indian caste groups |
[{...}].castegroupAlt | String | Second most likely caste group. | Indian caste groups |
[{...}].castegroupTop | Array | Top of the most likely caste group, sorted from most likely to least likely. | Indian caste groups |
[{...}].probabilityCalibrated | Number | The calibrated probability that castegroup has been guessed correctly. -1 = still calibrating. | |
[{...}].probabilityAltCalibrated | Number | The calibrated probability that castegroup OR castegroupAlt have been guessed correctly. -1 = still calibrating. |
Code sample:
Caste Indian Full Name code sample for shell:
curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/castegroupIndianFullBatch \
--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":"Akash Sharma","subdivisionIso":"IN-UP"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Akash Sharma",
"subdivisionIso": "IN-UP"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "string",
"name": "Akash Sharma",
"score": 7.8984899727105295,
"castegroup": "General/High Caste",
"castegroupAlt": "General",
"castegroupTop": ["General/High Caste", "General", "OBC", "ST", "SC"],
"probabilityCalibrated": 0.6400351364066995,
"probabilityAltCalibrated": 0.9559249062835251
}
]
}Religion Indian Name
Religion Indian Name feature analyzes a first name, a last name and a Indian state or Union territory of residence to determine the person's most likely religion. Adding the first and last name increases the accuracy of the estimated religion. If the first and last name are not clearly identifiable, please use the Religion Indian Full Name feature.
- Description: Returns religion from Indian first and last names and territories of origin.
- Cost: 10 credits per name.
- Test: Religion Indian Name feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/religionIndianBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal names with their State or Union territory of origin or residence. |
[{...}].id | String | Optional | Provided unique identifier. |
[{...}].firstName | String | Optional | Indian first name, given name, nickname. |
[{...}].lastName | String | Optional | Indian last name, family name, surname. |
[{...}].subdivisionIso | String | Required | Indian state or Union territory (origin or residence), in ISO 3166-2 format. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted names with their religion. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].firstName | String | Provided first name. | |
[{...}].lastName | String | Provided last name. | |
[{...}].religion | String | Most likely religion. | Religions of India |
[{...}].religionAlt | String | Second most likely religion. | Religions of India |
[{...}].religionsTop | Array | Top of the most likely religions, sorted from most likely to least likely. | Religions of India |
[{...}].score | Number | Higher implies a more reliable result, score is not normalized. | |
[{...}].probabilityCalibrated | Number | The calibrated probability that religion has been guessed correctly. -1 = still calibrating. | |
[{...}].probabilityAltCalibrated | Number | The calibrated probability that religion OR religionAlt have been guessed correctly. -1 = still calibrating. |
Code sample:
Religion Indian Name code sample for shell:
curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/religionIndianBatch \
--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":"Akash","lastName":"Sharma","subdivisionIso":"IN-PB"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Akash",
"lastName": "Sharma",
"subdivisionIso": "IN-PB"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Akash",
"lastName": "Sharma",
"religion": "Hinduism",
"religionAlt": "Jain",
"religionsTop": ["Hinduism", "Jain", "Buddhist", "Christian", "Sikh", "Parsi", "Muslim"],
"score": 15.842441054636446,
"probabilityCalibrated": 0.8366121598622244,
"probabilityAltCalibrated": 0.9418751496555294
}
]
}Religion Indian Full Name
Religion Indian Name feature analyzes an unsplit Indian full name and a Indian state or Union territory of residence to determine the person's most likely religion.
- Description: Returns religion from unsplit Indian full names and territories of origin.
- Cost: 10 credits per name.
- Test: Religion Indian Full Name feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/religionIndianFullBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal names with their State or Union territory of origin or residence. |
[{...}].id | String | Optional | Provided unique identifier. |
[{...}].name | String | Required | Unsplit Indian full name (first name and last name). |
[{...}].subdivisionIso | String | Required | Indian state or Union territory (origin or residence), in ISO 3166-2 format. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted names with their religion. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].name | String | Provided full name. | |
[{...}].score | Number | Higher implies a more reliable result, score is not normalized. | |
[{...}].religion | String | Most likely religion. | Religions of India |
[{...}].religionAlt | String | Second most likely religion. | Religions of India |
[{...}].religionsTop | Array | Top of the most likely religions, sorted from most likely to least likely. | Religions of India |
[{...}].probabilityCalibrated | Number | The calibrated probability that religion has been guessed correctly. -1 = still calibrating. | |
[{...}].probabilityAltCalibrated | Number | The calibrated probability that religion OR religionAlt have been guessed correctly. -1 = still calibrating. |
Code sample:
Religion Indian Full Name code sample for shell:
curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/religionIndianFullBatch \
--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":"Akash Sharma","subdivisionIso":"IN-PB"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Akash Sharma",
"subdivisionIso": "IN-PB"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Akash Sharma",
"score": 11.205099735191228,
"religion": "Hinduism",
"religionAlt": "Jain",
"religionsTop": ["Hinduism", "Jain", "Buddhist", "Christian", "Sikh", "Muslim", "Parsi"],
"probabilityCalibrated": 0.9535569047307475,
"probabilityAltCalibrated": 0.9896944325654494
}
]
}Subclassification Indian Name
Subclassification Indian Name feature analyzes a first name or a last name (or both for more precision) to estimate the person's most likely State or Union territory of residence (in ISO 3166-2 alpha-2 format), with slightly improved accuracy than the Subclassification Indian Full Name feature.
- Description: Returns the most likely Indian State or Union territory of residence of up to 100 Indian first names and/or last names.
- Cost: 10 credits per name.
- Test: Subclassification Indian Name feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/subclassificationIndianBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal names. |
[{...}].id | String | Optional | Provided unique identifier. |
[{...}].firstName | String | Optional | First name, given name, nickname. |
[{...}].lastName | String | Optional | Last name, family name, surname. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted names with their most likely geographic subdivision context. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].firstName | String | Submitted first name. | |
[{...}].lastName | String | Submitted last name. | |
[{...}].countryIso2 | String | Most likely country of residence, in ISO 3166-1 alpha-2 format. | Country of residence |
[{...}].subClassification | String | Most likely Indian State or Union territory of residence, in ISO 3166-2 alpha-2 format. | Indian subdivision |
[{...}].subClassificationAlt | String | Second most likely Indian State or Union territory of residence, in ISO 3166-2 alpha-2 format. | Indian subdivision |
[{...}].subclassificationTop | Array | Top 10 most likely Indian State or Union territory of residence, sorted from most likely to least likely. | Indian subdivision |
[{...}].score | Number | Higher implies a more reliable result, score is not normalized. | |
[{...}].probabilityCalibrated | Number | The calibrated probability for subClassification to have been guessed correctly. -1 = still calibrating. | |
[{...}].probabilityAltCalibrated | Number | The calibrated probability for subClassification OR subClassificationAlt to have been guessed correctly. -1 = still calibrating. |
Code sample:
Subclassification Indian Name code sample for shell:
curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/subclassificationIndianBatch \
--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":"Jannat","lastName":"Rahmani"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Jannat",
"lastName": "Rahmani"
}
]
}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
}
]
}Subclassification Indian Full Name
Subclassification Indian Full Name feature analyzes an unsplit full name (first name and last name) to identify the person's most likely State or Union territory of residence, in ISO 3166-2 alpha-2 format.
If the first and last name are clearly identifiable, the Subclassification Indian Name feature will be slightly more accurate.
- Description: Returns the most likely Indian State or Union territory of residence of up to 100 unsplit full names.
- Cost: 10 credits per name.
- Test: Subclassification Indian Full Name feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/subclassificationIndianFullBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNames | Array of objects | Required | A list of personal names. |
[{...}].id | String | Optional | Provided unique identifier. |
[{...}].name | String | Required | Unsplit full name (first name and last name). |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNames | Array of objects | List of submitted names with their most likely geographic subdivision context. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].name | String | Submitted full name. | |
[{...}].countryIso2 | String | Most likely country of residence, in ISO 3166-1 alpha-2 format. | Country of residence |
[{...}].subClassification | String | Most likely Indian State or Union territory of residence, in ISO 3166-2 alpha-2 format. | Indian subdivision |
[{...}].subClassificationAlt | String | Second most likely Indian State or Union territory of residence, in ISO 3166-2 alpha-2 format. | Indian subdivision |
[{...}].subclassificationTop | Array | Top 10 most likely Indian State or Union territory of residence, sorted from most likely to least likely. | Indian subdivision |
[{...}].score | Number | Higher implies a more reliable result, score is not normalized. | |
[{...}].probabilityCalibrated | Number | The calibrated probability for subClassification to have been guessed correctly. -1 = still calibrating. | |
[{...}].probabilityAltCalibrated | Number | The calibrated probability for subClassification OR subClassificationAlt to have been guessed correctly. -1 = still calibrating. |
Code sample:
Subclassification Indian Full Name code sample for shell:
curl --request POST \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/subclassificationIndianFullBatch \
--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":"Jannat Rahmani"}]}'Body parameter:
{
"personalNames": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Jannat Rahmani"
}
]
}The above command returns JSON structured like this:
{
"personalNames": [
{
"script": "LATIN",
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"name": "Jannat 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
}
]
}Phone number
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.
Format Phone Number
Format Phone Number feature analyzes a first name, a last name and a phone number to determine the most likely phone prefix, country of origin and formated phone number.
- Description: Returns the most likely phone prefix, country of residence and format of up to 100 phone numbers using first names and last names.
- Precision:
- Cost: 11 credits per name.
- Test: Format Phone Number feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/phoneCodeBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNamesWithPhoneNumbers | Array of objects | Required | A list of personal names with phone numbers. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].firstName | String | Optional | First name (or given name). |
[{...}].lastName | String | Optional | Last name (or family name). |
[{...}].phoneNumber | String | Required | Phone number, formatted or unformatted. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNamesWithPhoneNumbers | Array of objects | List of formatted phone numbers. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].firstName | String | Submitted first name (or given name). | |
[{...}].lastName | String | Submitted last name (or family name). | |
[{...}].internationalPhoneNumberVerified | String | Positively verified phone number, in E.164 format (according to LibPhoneNumber). | |
[{...}].phoneCountryIso2Verified | String | Positively verified country of origin of the phone number, in ISO 3166-1 alpha-2 format (according to LibPhoneNumber). | Country of residence |
[{...}].phoneCountryCode | Number | Most likely country calling code. | Phone prefix |
[{...}].phoneCountryCodeAlt | Number | Second most likely country calling code. | Phone prefix |
[{...}].phoneCountryIso2 | String | Most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format. | Country of residence |
[{...}].phoneCountryIso2Alt | String | Second most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format. | Country of residence |
[{...}].originCountryIso2 | String | Most likely country of residence of the name, in ISO 3166-1 alpha-2 format. | Country of origin |
[{...}].originCountryIso2Alt | String | Second most likely country of residence of the name, in ISO 3166-1 alpha-2 format. | Country of origin |
[{...}].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. |
Code sample:
Format Phone Number code sample for shell:
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"}]}'Body parameter:
{
"personalNamesWithPhoneNumbers": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Jamini",
"lastName": "Roy",
"phoneNumber": "09804201420"
}
]
}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
}
]
}Format Phone Number Geo
Format Phone Number Geo feature analyzes a first name, a last name, a phone number and a local context to determine the most likely phone prefix, country of origin and formated phone number, with improved accuracy than the basic feature Format Phone Number.
- Description: Returns the most likely phone prefix and format of up to 100 phone numbers using first names, last names and geographic context.
- Precision:
- Cost: 11 credits per name.
- Test: Format Phone Number Geo feature.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/phoneCodeGeoBatchRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
personalNamesWithPhoneNumbers | Array of objects | Required | A list of personal names with phone numbers and their local context. |
[{...}].id | String | Optional | Unique identifier. |
[{...}].firstName | String | Optional | First name (or given name). |
[{...}].lastName | String | Optional | Last name (or family name). |
[{...}].phoneNumber | String | Required | Phone number, formatted or unformatted. |
[{...}].countryIso2 | String | Required | Most likely country of residence, in ISO 3166-1 alpha-2 format. |
[{...}].countryIso2Alt | String | Optional | Second most likely country of residence, in ISO 3166-1 alpha-2 format. |
| Name | Type | Description | Enumerators |
|---|---|---|---|
personalNamesWithPhoneNumbers | Array of objects | List of formatted phone numbers. | |
[{...}].script | String | Name of the script used for the name, in ISO 15924 format. | Script |
[{...}].id | String | Provided unique identifier. | |
[{...}].firstName | String | Submitted first name (or given name). | |
[{...}].lastName | String | Submitted last name (or family name). | |
[{...}].internationalPhoneNumberVerified | String | Positively verified phone number, in E.164 format (according to LibPhoneNumber). | |
[{...}].phoneCountryIso2Verified | String | Positively verified country of origin of the phone number, in ISO 3166-1 alpha-2 format (according to LibPhoneNumber). | Country of residence |
[{...}].phoneCountryCode | Number | Most likely country calling code. | Phone prefix |
[{...}].phoneCountryCodeAlt | Number | Second most likely country calling code. | Phone prefix |
[{...}].phoneCountryIso2 | String | Most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format. | Country of residence |
[{...}].phoneCountryIso2Alt | String | Second most likely country of origin of the phone number, in ISO 3166-1 alpha-2 format. | Country of residence |
[{...}].originCountryIso2 | String | Most likely country of residence of the name, in ISO 3166-1 alpha-2 format. | Country of origin |
[{...}].originCountryIso2Alt | String | Second most likely country of residence of the name, in ISO 3166-1 alpha-2 format. | Country of origin |
[{...}].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. |
Code sample:
Format Phone Number Geo code sample for shell:
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","countryIso2Alt":"CI"}]}'Body parameter:
{
"personalNamesWithPhoneNumbers": [
{
"id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
"firstName": "Teniola",
"lastName": "Apata",
"phoneNumber": "08186472651",
"countryIso2": "NG",
"countryIso2Alt": "CI"
}
]
}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
}
]
}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
GET- Description: Returns the current version of the Namsor software.
- Cost: 1 credit per name.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/softwareVersionRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Description |
|---|---|---|
softwareNameAndVersion | String | Name and version of the API. |
softwareVersion | Array | Software version, as an array (major, minor and patch). |
Code sample:
Software Version code sample for shell:
curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/softwareVersion \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'The above command returns JSON structured like this:
{
"softwareNameAndVersion": "NamSorAPIv2.0.14B01",
"softwareVersion": [
2,
0,
14
]
}Api Status
GET- Description: Returns the current version of the Namsor software and the status of the classifiers (API services).
- Cost: 1 credit per name.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/apiStatusRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Description |
|---|---|---|
softwareVersion | Object | Software version information. |
{...}.softwareNameAndVersion | String | Name and version of the API. |
{...}.softwareVersion | Array | Software version, as an array (major, minor and patch). |
classifiers | Array of objects | List of available classifiers. |
[{...}].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). |
Code sample:
Api Status code sample for shell:
curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/apiStatus \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'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
}
]
}Available Services
GET- Description: Returns a list of the API services (classifiers) and their usage costs in credits.
- Cost: 1 credit per name.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/apiServicesRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Description |
|---|---|---|
apiServices | Array of objects | List of available API services. |
[{...}].serviceName | String | Name of the classifier / service. |
[{...}].serviceGroup | String | Group the classifier / service belong to. |
[{...}].costInUnits | Number | Usage cost of the service, in credits. |
Code sample:
Available Services code sample for shell:
curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/apiServices \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'The above command returns JSON structured like this:
{
"apiServices": [
{
"serviceName": "name_category",
"serviceGroup": "general",
"costInUnits": 1
},
{
"serviceName": "personalname_gender",
"serviceGroup": "gender",
"costInUnits": 1
}
]
}Taxonomy Classes
GET- Description: Returns a list of the possible enumerators for a given classifier.
- Cost: 1 credit per name.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/taxonomyClasses/{classifierName}Request header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Required | Description |
|---|---|---|---|
classifierName | String | Required | Name of the classifier. |
| Name | Type | Description |
|---|---|---|
classifierName | String | Name of the submitted classifier. |
taxonomyClasses | Array | Possible enumerators for this classifier. |
Code sample:
Taxonomy Classes code sample for shell:
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'The above command returns JSON structured like this:
{
"classifierName": "personalname_gender",
"taxonomyClasses": ["female", "male"]
}Api Usage
GET- Description: Returns information on your subscription plan, billing period and current API usage.
- Cost: 1 credit per name.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsageRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Description |
|---|---|---|
subscription | Object | Subscription information. |
{...}.apiKey | String | Your Namsor API key. |
{...}.planStarted | Number | Start date of the plan, in UNIX time format. |
{...}.priorPlanStarted | Number | Datetime when the user subscribed to the prior plan. |
{...}.planEnded | Number | 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 | Number | Total number of credits associated with this plan. |
{...}.priceUSD | Number | Price in US dollars ($). |
{...}.priceOverageUSD | Number | Overage price in US 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 | Billing information. |
{...}.apiKey | String | Your Namsor API key. |
{...}.subscriptionStarted | Number | Subscription start date, in UNIX time format. |
{...}.periodStarted | Number | Subscription period start date, in UNIX time format. |
{...}.periodEnded | Number | Subscription end date, in UNIX time format. |
{...}.stripeCurrentPeriodEnd | Number | End of the current plan in Stripe. |
{...}.stripeCurrentPeriodStart | Number | Start of the current plan in Stripe. |
{...}.billingStatus | String | Status of the current period billing. |
{...}.usage | Number | Number of credits used so far. |
{...}.softLimit | Number | Current soft limit for the period. |
{...}.hardLimit | Number | Current hard limit for the period. |
overageExclTax | Number | Overage amount excluding tax. |
overageInclTax | Number | Overage amount including tax (if applicable). |
overageCurrency | String | Currency of the overage amount. |
overageQuantity | Number | Quantity above monthly quota of the current subscritpion, in credits. |
Code sample:
Api Usage code sample for shell:
curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsage \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'The above command returns JSON structured like this:
{
"subscription": {
"apiKey": "v7menlws2yo8r2mnm10f3uai53tmblth",
"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": "GYUAUzTKPusJ3aqUH5gQte0dOQCr"
},
"billingPeriod": {
"apiKey": "v7menlws2yo8r2mnm10f3uai53tmblth",
"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
}Api Usage History
GET- Description: Returns the detailed usage history, indicating what services where called and what API key parameters where applied.
- Cost: 1 credit per name.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsageHistoryRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Description |
|---|---|---|
detailedUsage | Array of objects | Print historical API usage (NB. new output format form v2.0.15). |
[{...}].apiKey | Object | API key information. |
{...}.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. |
{...}.api_key | String | The user API Key. |
[{...}].apiService | String | Name of the service requested. |
[{...}].createdDateTime | Number | Date of the analysis, in UNIX time format. |
[{...}].totalUsage | Number | Total cost of the analysis in credits. |
[{...}].lastFlushedDateTime | Number | Last time the counter was reset, in UNIX time format. |
[{...}].lastUsedDateTime | Number | Last time the API key was used, in UNIX time format. |
[{...}].serviceFeaturesUsage | Object | Details regarding usage of special features. |
Code sample:
Api Usage History code sample for shell:
curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsageHistory \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'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": {}
}
]
}Api Usage History Aggregate
GET- Description: 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: 1 credit per name.
HTTP request
https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsageHistoryAggregateRequest header
| Property | Required | Description |
|---|---|---|
X-API-KEY | Required | Your Namsor's services API key |
| Name | Type | Description |
|---|---|---|
timeUnit | String | Unit of time used in the "rowHeaders" field. May vary depending on API usage ("DAY", "WEEK" or "MONTH"). |
periodStart | Number | Start of the reporting period, in UNIX time format. |
periodEnd | Number | End of the reporting period, in UNIX time format. |
totalUsage | Number | Total usage during the current period. |
historyTruncated | Boolean | Indicates if returned data was truncaded due to size limits. |
data | Array of arrays | 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. |
Code sample:
Api Usage History Aggregate code sample for shell:
curl --request GET \
--url https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsageHistoryAggregate \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'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"]
}