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
The NamSor API uses the following error codes:
- 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.
Result Explainability
The Namsor API offers the ability to obtain a detailed explanation of how the artificial intelligence arrived at its results for a given request. By enabling this option, an additional field is included in the API response, providing a Python code explanation of the process followed by the AI.
Important
- Additional Cost: Activating explainability incurs an extra cost of 50 credits per name processed.
- Explanation Format: The returned explanation is in Python code. For optimal use, it is recommended to remove tabs and carriage returns so that the code is usable.
How to Activate Explainability:
- Contact the Namsor Team: Before using this feature, please contact our team to activate the explainability option on your client account.
- Configure the Request: Add the following header to your API request:
X-OPTION-EXPLANABILITY: trueBy following these steps, each request will now include a detailed explanation of the result, allowing you to gain deep insights into the workings of our artificial intelligence specialized in onomastics.
AI Act Use Case
The Namsor API can be instrumental in complying with national or supra-national regulations aimed at preventing biased results and discriminatory effects in Artificial Intelligence. Namsor is capable of inferring special categories of personal data from names to estimate the risk of algorithmic biases related to gender, race, cultural/linguistic background, ethnicity, or country of origin.
The European AI Act introduces a new exception regarding “sensitive data” to protect citizens' rights from discrimination that might arise due to bias in AI systems. For the purpose of ensuring bias detection and correction in high-risk AI systems, it permits the processing of special categories of personal data, as a matter of substantial public interest.
Namsor's Explainability Option is designed to provide a closed mathematical formula that includes the entire explanation of name classification (with both training data features and complete model formulas). This can be stored for audit purposes in decision-making AI algorithms.
To protect Namsor's intellectual property, we require specific documentation and a signed NDA before activating this option.
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 | Values | Required | Description |
|---|---|---|---|
X-API-KEY | Required | Your Namsor's services API key | |
X-OPTION-RELIGION-STATS | True | Optional | Returns religious statistics for countries of origin, countries of residence, and estimated diasporas. By default the feature is disabled. Add to the Header of the request the parameter X-OPTION-RELIGION-STATS on True to activate it. |
| 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. | |
| Optional: X-OPTION-RELIGION-STATS = True | |||
[{...}].religionStats | Array of objects | Religious statistics for the most likely country of origin. Returned only if the religious statistics option is enabled (X-OPTION-RELIGION-STATS: True). | |
[{...}].religion | String | Religion in most likely country of origin (countryOrigin). | Religions |
[{...}].pct | Number | Percentage of population practicing this religion in most likely country of origin (countryOrigin). | |
[{...}].religionStatsAlt | Array of objects | Religious statistics for the second most likely country of origin. Returned only if the religious statistics option is enabled (X-OPTION-RELIGION-STATS: True). | |
[{...}].religion | String | Religion in second most likely country of origin (countryOriginAlt). | Religions |
[{...}].pct | Number | Percentage of population practicing this religion in second most likely country of origin (countryOriginAlt). |
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
}
]
}Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.
{
religionStats: [
{ religion: 'Christian', pct: 85.24262131 },
{ religion: 'Unaffiliated', pct: 14.20710355 },
{ religion: 'Other', pct: 0.300150075 },
{ religion: 'Buddhist', pct: 0.050025013 },
{ religion: 'Folk', pct: 0.050025013 },
{ religion: 'Hindu', pct: 0.050025013 },
{ religion: 'Jewish', pct: 0.050025013 },
{ religion: 'Muslim', pct: 0.050025013 },
],
religionStatsAlt: [
{ religion: 'Christian', pct: 88.97427291753932 },
{ religion: 'Unaffiliated', pct: 9.78531187532157 },
{ religion: 'Muslim', pct: 0.6298564872835054 },
{ religion: 'Other', pct: 0.16200879680269425 },
{ religion: 'Buddhist', pct: 0.13284624102403442 },
{ religion: 'Folk', pct: 0.13284624102403442 },
{ religion: 'Hindu', pct: 0.13284624102403442 },
{ religion: 'Jewish', pct: 0.050011199980789234 },
],
}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 | Values | Required | Description |
|---|---|---|---|
X-API-KEY | Required | Your Namsor's services API key | |
X-OPTION-RELIGION-STATS | True | Optional | Returns religious statistics for countries of origin, countries of residence, and estimated diasporas. By default the feature is disabled. Add to the Header of the request the parameter X-OPTION-RELIGION-STATS on True to activate it. |
| 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. | |
| Optional: X-OPTION-RELIGION-STATS = True | |||
[{...}].religionStats | Array of objects | Religious statistics for the most likely country of origin. Returned only if the religious statistics option is enabled (X-OPTION-RELIGION-STATS: True). | |
[{...}].religion | String | Religion in most likely country of origin (countryOrigin). | Religions |
[{...}].pct | Number | Percentage of population practicing this religion in most likely country of origin (countryOrigin). | |
[{...}].religionStatsAlt | Array of objects | Religious statistics for the second most likely country of origin. Returned only if the religious statistics option is enabled (X-OPTION-RELIGION-STATS: True). | |
[{...}].religion | String | Religion in second most likely country of origin (countryOriginAlt). | Religions |
[{...}].pct | Number | Percentage of population practicing this religion in second most likely country of origin (countryOriginAlt). |
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 | Values | Required | Description |
|---|---|---|---|
X-API-KEY | Required | Your Namsor's services API key | |
X-OPTION-RELIGION-STATS | True | Optional | Returns religious statistics for countries of origin, countries of residence, and estimated diasporas. By default the feature is disabled. Add to the Header of the request the parameter X-OPTION-RELIGION-STATS on True to activate it. |
| 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 . | |
| Optional: X-OPTION-RELIGION-STATS = True | |||
[{...}].religionStats | Array of objects | Religious statistics in the country of origin of the most likely diaspora. Returned only if the religious statistics option is enabled (X-OPTION-RELIGION-STATS: True). | |
[{...}].religion | String | Religion within country of origin of most likely diaspora (ethnicity). | Religions |
[{...}].pct | Number | Percentage of the population practicing this religion in the country of origin of the most likely diaspora (ethnicity). | |
[{...}].religionStatsAlt | Array of objects | Religious statistics in the country of origin of the second most likely diaspora. Returned only if the religious statistics option is enabled (X-OPTION-RELIGION-STATS: True). | |
[{...}].religion | String | Religion within country of origin of second most likely diaspora (ethnicityAlt). | Religions |
[{...}].pct | Number | Percentage of the population practicing this religion in the country of origin of the second most likely diaspora (ethnicityAlt). |
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
}
]
}Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.
{
religionStats: [
{ religion: 'Christian', pct: 68.7 },
{ religion: 'Unaffiliated', pct: 24.7 },
{ religion: 'Muslim', pct: 5.8 },
{ religion: 'Buddhist', pct: 0.3 },
{ religion: 'Jewish', pct: 0.3 },
{ religion: 'Other', pct: 0.1 },
{ religion: 'Folk', pct: 0.05 },
{ religion: 'Hindu', pct: 0.05 },
],
religionStatsAlt: [
{ religion: 'Christian', pct: 68.7 },
{ religion: 'Unaffiliated', pct: 24.7 },
{ religion: 'Muslim', pct: 5.8 },
{ religion: 'Buddhist', pct: 0.3 },
{ religion: 'Jewish', pct: 0.3 },
{ religion: 'Other', pct: 0.1 },
{ religion: 'Folk', pct: 0.05 },
{ religion: 'Hindu', pct: 0.05 },
],
}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 | Values | Required | Description |
|---|---|---|---|
X-API-KEY | Required | Your Namsor's services API key | |
X-OPTION-RELIGION-STATS | True | Optional | Returns religious statistics for countries of origin, countries of residence, and estimated diasporas. By default the feature is disabled. Add to the Header of the request the parameter X-OPTION-RELIGION-STATS on True to activate it. |
| 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 . | |
| Optional: X-OPTION-RELIGION-STATS = True | |||
[{...}].religionStats | Array of objects | Religious statistics in the country of origin of the most likely diaspora. Returned only if the religious statistics option is enabled (X-OPTION-RELIGION-STATS: True). | |
[{...}].religion | String | Religion within country of origin of most likely diaspora (ethnicity). | Religions |
[{...}].pct | Number | Percentage of the population practicing this religion in the country of origin of the most likely diaspora (ethnicity). | |
[{...}].religionStatsAlt | Array of objects | Religious statistics in the country of origin of the second most likely diaspora. Returned only if the religious statistics option is enabled (X-OPTION-RELIGION-STATS: True). | |
[{...}].religion | String | Religion within country of origin of second most likely diaspora (ethnicityAlt). | Religions |
[{...}].pct | Number | Percentage of the population practicing this religion in the country of origin of the second most likely diaspora (ethnicityAlt). |
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 | Values | Required | Description |
|---|---|---|---|
X-API-KEY | Required | Your Namsor's services API key | |
X-OPTION-RELIGION-STATS | True | Optional | Returns religious statistics for countries of origin, countries of residence, and estimated diasporas. By default the feature is disabled. Add to the Header of the request the parameter X-OPTION-RELIGION-STATS on True to activate it. |
| 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. | |
| Optional: X-OPTION-RELIGION-STATS = True | |||
[{...}].religionStats | Array of objects | Religious statistics for the most likely country of residence. Returned only if the religious statistics option is enabled (X-OPTION-RELIGION-STATS: True). | |
[{...}].religion | String | Religion in most likely country of residence (country). | Religions |
[{...}].pct | Number | Percentage of population practicing that religion in the country of most likely residence (country). | |
[{...}].religionStatsAlt | Array of objects | Religious statistics for the second most likely country of residence. Returned only if the religious statistics option is enabled (X-OPTION-RELIGION-STATS: True). | |
[{...}].religion | String | Religion in second most likely country of residence (countryAlt). | Religions |
[{...}].pct | Number | Percentage of population practicing this religion in second most likely country of residence (countryAlt). |
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 | Values | Required | Description |
|---|---|---|---|
X-API-KEY | Required | Your Namsor's services API key | |
X-OPTION-RELIGION-STATS | True | Optional | Returns religious statistics for countries of origin, countries of residence, and estimated diasporas. By default the feature is disabled. Add to the Header of the request the parameter X-OPTION-RELIGION-STATS on True to activate it. |
| 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. | |
| Optional: X-OPTION-RELIGION-STATS = True | |||
[{...}].religionStats | Array of objects | Religious statistics for the most likely country of residence. Returned only if the religious statistics option is enabled (X-OPTION-RELIGION-STATS: True). | |
[{...}].religion | String | Religion in most likely country of residence (country). | Religions |
[{...}].pct | Number | Percentage of population practicing that religion in the country of most likely residence (country). | |
[{...}].religionStatsAlt | Array of objects | Religious statistics for the second most likely country of residence. Returned only if the religious statistics option is enabled (X-OPTION-RELIGION-STATS: True). | |
[{...}].religion | String | Religion in second most likely country of residence (countryAlt). | Religions |
[{...}].pct | Number | Percentage of population practicing this religion in second most likely country of residence (countryAlt). |
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
}
]
}Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.
{
religionStats: [
{ religion: 'Christian', pct: 78.3 },
{ religion: 'Unaffiliated', pct: 16.4 },
{ religion: 'Jewish', pct: 1.8 },
{ religion: 'Buddhist', pct: 1.2 },
{ religion: 'Muslim', pct: 0.9 },
{ religion: 'Hindu', pct: 0.6 },
{ religion: 'Other', pct: 0.6 },
{ religion: 'Folk', pct: 0.2 },
],
religionStatsAlt: [
{ religion: 'Christian', pct: 78.3007843079025 },
{ religion: 'Unaffiliated', pct: 16.39975226849653 },
{ religion: 'Jewish', pct: 1.799802305332493 },
{ religion: 'Buddhist', pct: 1.1998700873301702 },
{ religion: 'Muslim', pct: 0.8999039783290091 },
{ religion: 'Other', pct: 0.5999661259551334 },
{ religion: 'Hindu', pct: 0.5999378693278477 },
{ religion: 'Folk', pct: 0.1999830573262992 },
],
}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: 50 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"]
}
}
]
}