Namsor

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

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.

information

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.
information

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:Precision gauge
  • Cost: 10 credits per name.
  • Test: Name Origin feature.

HTTP request

http request
POST
https://v2.namsor.com/NamSorAPIv2/api2/json/originBatch
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request body
NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names.
[{...}].idStringOptionalUnique identifier.
[{...}].firstNameStringOptionalFirst name, given name, nickname.
[{...}].lastNameStringOptionalLast name, family name, surname.
Response
NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names with their countries of origin.
[{...}].scriptStringName of the script used for the name, in ISO 15924 format.Script
[{...}].idStringProvided unique identifier.
[{...}].firstNameStringSubmitted first name, given name or nickname.
[{...}].lastNameStringSubmitted last name, family name or surname.
[{...}].countryOriginStringMost likely country of origin, in ISO 3166-1 alpha-2 format.Country of origin
[{...}].countryOriginAltStringSecond most likely country of origin, in ISO 3166-1 alpha-2 format.Country of origin
[{...}].countriesOriginTopArrayTop 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely.Country of origin
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.
[{...}].regionOriginStringMost likely region of origin.Regions of origin or residence
[{...}].topRegionOriginStringMost likely region of origin (alternative classification).Regions of origin or residence
[{...}].subRegionOriginStringMost likely sub-region of origin.Sub regions of origin or residence
[{...}].probabilityCalibratedNumberThe calibrated probability that countryOrigin has been guessed correctly. -1 = still calibrating.
[{...}].probabilityAltCalibratedNumberThe 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
        }
    ]
}

Name Origin code sample for java:

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

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
        }
    ]
}

Name Origin code sample for python:

import requests

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

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

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

print(response.text)

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
        }
    ]
}

Name Origin code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/originBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Keith",
      "lastName": "Haring"
    }
  ]
})
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

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
        }
    ]
}
information

For requests with a GET method all parameters are required. For more ease in the use of our requests we recommend that you use the POST method.

  • Description: Returns the most likely country of origin of a first name and/or a last name.
  • Precision:Precision gauge
  • Cost: 10 credits per name.
  • Test: Name Origin feature.

HTTP request

http request
GET
https://v2.namsor.com/NamSorAPIv2/api2/json/origin/{firstName}/{lastName}
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request parameters
NameTypeRequiredDescription
firstNameStringRequiredFirst name (or given name).
lastNameStringRequiredLast name (or family name).
Response
NameTypeDescriptionEnumerators
scriptStringName of the script used for the name, in ISO 15924 format.Script
idStringProvided unique identifier.
firstNameStringSubmitted first name.
lastNameStringSubmitted last name.
countryOriginStringMost likely country of origin, in ISO 3166-1 alpha-2 format.Country of origin
countryOriginAltStringSecond most likely country of origin, in ISO 3166-1 alpha-2 format.Country of origin
countriesOriginTopArrayTop 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely.Country of origin
scoreNumberHigher implies a more reliable result, score is not normalized.
regionOriginStringMost likely region of origin.Regions of origin or residence
topRegionOriginStringMost likely region of origin (alternative classification).Regions of origin or residence
subRegionOriginStringMost likely sub-region of origin.Sub regions of origin or residence
probabilityCalibratedNumberThe calibrated probability that countryOrigin has been guessed correctly. -1 = still calibrating.
probabilityAltCalibratedNumberThe calibrated probability that countryOrigin OR countryOriginAlt have been guessed correctly. -1 = still calibrating.

Code sample:

Name Origin code sample for shell:

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

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "76d53c84-623b-4e8c-9414-3e68b9b1d171",
    "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
}

Name Origin code sample for java:

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

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "76d53c84-623b-4e8c-9414-3e68b9b1d171",
    "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
}

Name Origin code sample for python:

import requests

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

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

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

print(response.text)

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "76d53c84-623b-4e8c-9414-3e68b9b1d171",
    "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
}

Name Origin code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/origin/Keith/Haring", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "76d53c84-623b-4e8c-9414-3e68b9b1d171",
    "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".

information

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:Precision gauge
  • Cost: 10 credits per name.
  • Test: Full Name Origin feature.

HTTP request

http request
POST
https://v2.namsor.com/NamSorAPIv2/api2/json/originFullBatch
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request body
NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names.
[{...}].idStringOptionalUnique identifier.
[{...}].nameStringRequiredUnsplit full name (first name and last name).
Response
NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted full names with their countries of origin.
[{...}].scriptStringName of the script used for the name, in ISO 15924 format.Script
[{...}].idStringProvided unique identifier.
[{...}].nameStringSubmitted full name.
[{...}].countryOriginStringMost likely country of origin, in ISO 3166-1 alpha-2 format.Country of origin
[{...}].countryOriginAltStringSecond most likely country of origin, in ISO 3166-1 alpha-2 format.Country of origin
[{...}].countriesOriginTopArrayTop 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely.Country of origin
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.
[{...}].regionOriginStringMost likely region of origin.Regions of origin or residence
[{...}].topRegionOriginStringMost likely region of origin (alternative classification).Regions of origin or residence
[{...}].subRegionOriginStringMost likely sub-region of origin.Sub regions of origin or residence
[{...}].probabilityCalibratedNumberThe calibrated probability that countryOrigin has been guessed correctly. -1 = still calibrating.
[{...}].probabilityAltCalibratedNumberThe 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
        }
    ]
}

Full Name Origin code sample for java:

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

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
        }
    ]
}

Full Name Origin code sample for python:

import requests

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

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

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

print(response.text)

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
        }
    ]
}

Full Name Origin code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/originFullBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "Keith Haring"
    }
  ]
})
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

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
        }
    ]
}
information

For requests with a GET method all parameters are required. For more ease in the use of our requests we recommend that you use the POST method.

  • Description: Returns the most likely country of origin of an unsplit full name.
  • Precision:Precision gauge
  • Cost: 10 credits per name.
  • Test: Full Name Origin feature.

HTTP request

http request
GET
https://v2.namsor.com/NamSorAPIv2/api2/json/originFull/{name}
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request parameters
NameTypeRequiredDescription
nameStringRequiredUnsplit full name (first name and last name).
Response
NameTypeDescriptionEnumerators
scriptStringName of the script used for the name, in ISO 15924 format.Script
idStringProvided unique identifier.
nameStringSubmitted full name.
countryOriginStringMost likely country of origin, in ISO 3166-1 alpha-2 format.Country of origin
countryOriginAltStringSecond most likely country of origin, in ISO 3166-1 alpha-2 format.Country of origin
countriesOriginTopArrayTop 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely.Country of origin
scoreNumberHigher implies a more reliable result, score is not normalized.
regionOriginStringMost likely region of origin.Regions of origin or residence
topRegionOriginStringMost likely region of origin (alternative classification).Regions of origin or residence
subRegionOriginStringMost likely sub-region of origin.Sub regions of origin or residence
probabilityCalibratedNumberThe calibrated probability that countryOrigin has been guessed correctly. -1 = still calibrating.
probabilityAltCalibratedNumberThe calibrated probability that countryOrigin OR countryOriginAlt have been guessed correctly. -1 = still calibrating.

Code sample:

Full Name Origin code sample for shell:

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

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "76d53c84-623b-4e8c-9414-3e68b9b1d171",
    "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
}

Full Name Origin code sample for java:

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

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "76d53c84-623b-4e8c-9414-3e68b9b1d171",
    "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
}

Full Name Origin code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/originFull/Keith%20Haring"

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

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

print(response.text)

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "76d53c84-623b-4e8c-9414-3e68b9b1d171",
    "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
}

Full Name Origin code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/originFull/Keith%20Haring", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "76d53c84-623b-4e8c-9414-3e68b9b1d171",
    "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:Precision gauge
  • Cost: 20 credits per name.
  • Test: Name Diaspora feature.

HTTP request

http request
POST
https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaBatch
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request body
NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names with their country of residence.
[{...}].idStringOptionalUnique identifier.
[{...}].firstNameStringOptionalFirst name, given name, nickname.
[{...}].lastNameStringRequiredLast name, family name, surname.
[{...}].countryIso2StringOptionalCountry of residence, in ISO 3166-1 alpha-2 format. "US" by default (if no value indicated).
Response
NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names with their ethnicities.
[{...}].scriptStringName of the script used for the name, in ISO 15924 format.Script
[{...}].idStringProvided unique identifier.
[{...}].firstNameStringSubmitted first name.
[{...}].lastNameStringSubmitted last name.
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.
[{...}].ethnicityAltStringSecond most likely ethnicity.Ethnicities or diasporas
[{...}].ethnicityStringMost likely ethnicity.Ethnicities or diasporas
[{...}].liftedBooleanIndicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule.
[{...}].countryIso2StringSubmitted country of residence, in ISO 3166-1 alpha-2 format.Country of residence
[{...}].ethnicitiesTopArrayTop 10 most likely ethnicities, ordered from most likely to least likely.Ethnicities or diasporas
[{...}].probabilityCalibratedNumberThe calibrated probability that ethnicity has been guessed correctly. -1 = still calibrating .
[{...}].probabilityAltCalibratedNumberThe 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
        }
    ]
}

Name Diaspora code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"0d7d6417-0bbb-4205-951d-b3473f605b56\",\"firstName\":\"Keith\",\"lastName\":\"Haring\",\"countryIso2\":\"US\"}]}")
.asString();

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
        }
    ]
}

Name Diaspora code sample for python:

import requests

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

payload = {
  "personalNames": [
    {
      "id": "0d7d6417-0bbb-4205-951d-b3473f605b56",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US"
    }
  ]
}
headers = {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
}

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

print(response.text)

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
        }
    ]
}

Name Diaspora code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
  "personalNames": [
    {
      "id": "0d7d6417-0bbb-4205-951d-b3473f605b56",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US"
    }
  ]
})
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

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
        }
    ]
}
information

For requests with a GET method all parameters are required. For more ease in the use of our requests we recommend that you use the POST method.

  • Description: Returns the most likely ethnicity or diaspora of a first name (optional) and a last name, according to the country of residence.
  • Precision:Precision gauge
  • Cost: 20 credits per name.
  • Test: Name Diaspora feature.

HTTP request

http request
GET
https://v2.namsor.com/NamSorAPIv2/api2/json/diaspora/{countryIso2}/{firstName}/{lastName}
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request parameters
NameTypeRequiredDescription
countryIso2StringRequiredCountry of residence, in ISO 3166-1 alpha-2 format. "US" by default (if no value indicated).
firstNameStringRequiredFirst name, given name, nickname.
lastNameStringRequiredLast name, family name, surname.
Response
NameTypeDescriptionEnumerators
scriptStringName of the script used for the name, in ISO 15924 format.Script
idStringUnique identifier.
firstNameStringSubmitted first name.
lastNameStringSubmitted last name.
scoreNumberHigher implies a more reliable result, score is not normalized.
ethnicityAltStringSecond most likely ethnicity.Ethnicities or diasporas
ethnicityStringMost likely ethnicity.Ethnicities or diasporas
liftedBooleanIndicates if the result of the "ethnicity" field is based on machine learning only, or further lifted as a known fact by a country-specific rule.
countryIso2StringCountry of residence, in ISO 3166-1 alpha-2 format.Country of residence
ethnicitiesTopArrayTop 10 most likely ethnicities, ordered from most likely to least likely.Ethnicities or diasporas
probabilityCalibratedNumberThe calibrated probability that ethnicity has been guessed correctly. -1 = still calibrating .
probabilityAltCalibratedNumberThe calibrated probability that ethnicity OR ethnicityAlt have been guessed correctly. -1 = still calibrating .

Code sample:

Name Diaspora code sample for shell:

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

The above command returns JSON structured like this:

{
    "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
}

Name Diaspora code sample for java:

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

The above command returns JSON structured like this:

{
    "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
}

Name Diaspora code sample for python:

import requests

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

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

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

print(response.text)

The above command returns JSON structured like this:

{
    "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
}

Name Diaspora code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/diaspora/US/Keith/Haring", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

The above command returns JSON structured like this:

{
    "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.

information

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:Precision gauge
  • Cost: 20 credits per name.
  • Test: Full Name Diaspora feature.

HTTP request

http request
POST
https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaFullBatch
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request body
NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal full names with their country of residence.
[{...}].idStringOptionalUnique identifier.
[{...}].nameStringRequiredUnsplit full name (first name and last name).
[{...}].countryIso2StringRequiredCountry of residence, in ISO 3166-1 alpha-2 format. "US" by default (if no value indicated).
Response
NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted full names with their ethnicities.
[{...}].scriptStringName of the script used for the name, in ISO 15924 format.Script
[{...}].idStringProvided unique identifier.
[{...}].nameStringSubmitted full name.
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.
[{...}].ethnicityAltStringSecond most likely ethnicity.Ethnicities or diasporas
[{...}].ethnicityStringMost likely ethnicity.Ethnicities or diasporas
[{...}].liftedBooleanIndicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule.
[{...}].countryIso2StringSubmitted country of residence, in ISO 3166-1 alpha-2 format.Country of residence
[{...}].ethnicitiesTopArrayTop 10 most likely ethnicities, ordered from most likely to least likely.Ethnicities or diasporas
[{...}].probabilityCalibratedNumberThe calibrated probability that ethnicity has been guessed correctly. -1 = still calibrating .
[{...}].probabilityAltCalibratedNumberThe 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
        }
    ]
}

Full Name Diaspora code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaFullBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"0d7d6417-0bbb-4205-951d-b3473f605b56\",\"name\":\"Keith Haring\",\"countryIso2\":\"US\"}]}")
.asString();

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
        }
    ]
}

Full Name Diaspora code sample for python:

import requests

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

payload = {
  "personalNames": [
    {
      "id": "0d7d6417-0bbb-4205-951d-b3473f605b56",
      "name": "Keith Haring",
      "countryIso2": "US"
    }
  ]
}
headers = {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
}

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

print(response.text)

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
        }
    ]
}

Full Name Diaspora code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaFullBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
  "personalNames": [
    {
      "id": "0d7d6417-0bbb-4205-951d-b3473f605b56",
      "name": "Keith Haring",
      "countryIso2": "US"
    }
  ]
})
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

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
        }
    ]
}
information

For requests with a GET method all parameters are required. For more ease in the use of our requests we recommend that you use the POST method.

  • Description: Returns the most likely ethnicity or diaspora of an unsplit full name, according to the country of residence.
  • Precision:Precision gauge
  • Cost: 20 credits per name.
  • Test: Full Name Diaspora feature.

HTTP request

http request
GET
https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaFull/{countryIso2}/{name}
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request parameters
NameTypeRequiredDescription
countryIso2StringRequiredCountry of residence, in ISO 3166-1 alpha-2 format. "US" by default (if no value indicated).
nameStringRequiredUnsplit full name (first name and last name).
Response
NameTypeDescriptionEnumerators
scriptStringName of the script used for the name, in ISO 15924 format.Script
idStringUnique identifier.
nameStringSubmitted full name.
scoreNumberHigher implies a more reliable result, score is not normalized.
ethnicityAltStringSecond most likely ethnicity.Ethnicities or diasporas
ethnicityStringMost likely ethnicity.Ethnicities or diasporas
liftedBooleanIndicates if the result of the "ethnicity" field is based on machine learning only, or further lifted as a known fact by a country-specific rule.
countryIso2StringCountry of residence, in ISO 3166-1 alpha-2 format.Country of residence
ethnicitiesTopArrayTop 10 most likely ethnicities, ordered from most likely to least likely.Ethnicities or diasporas
probabilityCalibratedNumberThe calibrated probability that ethnicity has been guessed correctly. -1 = still calibrating .
probabilityAltCalibratedNumberThe calibrated probability that ethnicity OR ethnicityAlt have been guessed correctly. -1 = still calibrating .

Code sample:

Full Name Diaspora code sample for shell:

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

The above command returns JSON structured like this:

{
    "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
}

Full Name Diaspora code sample for java:

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

The above command returns JSON structured like this:

{
    "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
}

Full Name Diaspora code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaFull/US/Keith%20Haring"

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

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

print(response.text)

The above command returns JSON structured like this:

{
    "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
}

Full Name Diaspora code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaFull/US/Keith%20Haring", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

The above command returns JSON structured like this:

{
    "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:Precision gauge
  • Cost: 10 credits per name.
  • Test: Name US Race feature.

HTTP request

http request
POST
https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityBatch
Request header
PropertyValuesRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
X-OPTION-USRACEETHNICITY-TAXONOMYUSRACEETHNICITY-6CLASSESOptionalEnumerators 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.
Request body
NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names with their country of residence.
[{...}].idStringOptionalUnique identifier.
[{...}].firstNameStringOptionalFirst name, given name, nickname.
[{...}].lastNameStringOptionalLast name, family name, surname.
[{...}].countryIso2StringOptionalCountry of residence, in ISO 3166-1 alpha-2 format.
Response
NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names with their race.
[{...}].scriptStringName of the script used for the name, in ISO 15924 format.Script
[{...}].idStringProvided unique identifier.
[{...}].firstNameStringSubmitted first name.
[{...}].lastNameStringSubmitted last name.
[{...}].raceEthnicityAltStringSecond most likely race (US race categorization from US Census Taxonomy).U.S. race ethnicities
[{...}].raceEthnicityStringMost likely race (US race categorization from US Census Taxonomy).U.S. race ethnicities
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.
[{...}].raceEthnicitiesTopArrayMost likely race, sorted from most likely to least likely (US race categorization from US Census Taxonomy).U.S. race ethnicities
[{...}].probabilityCalibratedNumberThe calibrated probability that raceEthnicity has been guessed correctly. -1 = still calibrating.
[{...}].probabilityAltCalibratedNumberThe 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 code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"85dd5f48-b9e1-4019-88ce-ccc7e56b763f\",\"firstName\":\"Keith\",\"lastName\":\"Haring\",\"countryIso2\":\"US\"}]}")
.asString();

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 code sample for python:

import requests

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

payload = {
  "personalNames": [
    {
      "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US"
    }
  ]
}
headers = {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
}

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

print(response.text)

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 code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
  "personalNames": [
    {
      "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US"
    }
  ]
})
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

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
        }
    ]
}
information

For requests with a GET method all parameters are required. For more ease in the use of our requests we recommend that you use the POST method.

  • Description: Returns the most likely US race from a first name and/or a last name.
  • Precision:Precision gauge
  • Cost: 10 credits per name.
  • Test: Name US Race feature.

HTTP request

http request
GET
https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicity/{firstName}/{lastName}
Request header
PropertyValuesRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
X-OPTION-USRACEETHNICITY-TAXONOMYUSRACEETHNICITY-6CLASSESOptionalEnumerators 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.
Request parameters
NameTypeRequiredDescription
firstNameStringRequiredFirst name, given name, nickname.
lastNameStringRequiredLast name, family name, surname.
Response
NameTypeDescriptionEnumerators
scriptStringName of the script used for the name, in ISO 15924 format.Script
idStringUnique identifier.
firstNameStringSubmitted first name.
lastNameStringSubmitted last name.
raceEthnicityAltStringSecond most likely race (US race categorization from US Census Taxonomy).U.S. race ethnicities
raceEthnicityStringMost likely race (US race categorization from US Census Taxonomy).U.S. race ethnicities
scoreNumberHigher implies a more reliable result, score is not normalized.
raceEthnicitiesTopArrayMost likely race ethnicities, sorted from most likely to least likely (US race categorization from US Census Taxonomy).U.S. race ethnicities
probabilityCalibratedNumberThe calibrated probability that raceEthnicity has been guessed correctly. -1 = still calibrating.
probabilityAltCalibratedNumberThe calibrated probability that raceEthnicity OR raceEthnicityAlt have been guessed correctly. -1 = still calibrating.

Code sample:

Name US Race code sample for shell:

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

The above command returns JSON structured like this:

{
    "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 code sample for java:

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

The above command returns JSON structured like this:

{
    "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 code sample for python:

import requests

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

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

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

print(response.text)

The above command returns JSON structured like this:

{
    "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 code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicity/Keith/Haring", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

The above command returns JSON structured like this:

{
    "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:Precision gauge
  • Cost: 10 credits per name.
  • Test: Name US Race ZIP feature.

HTTP request

http request
POST
https://v2.namsor.com/NamSorAPIv2/api2/json/usZipRaceEthnicityBatch
Request header
PropertyValuesRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
X-OPTION-USRACEETHNICITY-TAXONOMYUSRACEETHNICITY-6CLASSESOptionalEnumerators 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.
Request body
NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names with their country of residence and postal code.
[{...}].idStringOptionalUnique identifier.
[{...}].firstNameStringOptionalFirst name, given name, nickname.
[{...}].lastNameStringOptionalLast name, family name, surname.
[{...}].countryIso2StringOptionalCountry of residence, in ISO 3166-1 alpha-2 format.
[{...}].zipCodeStringRequiredPostal code (5-digit) of residence used by the United States Postal Service (USPS).
Response
NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names with their race.
[{...}].scriptStringName of the script used for the name, in ISO 15924 format.Script
[{...}].idStringProvided unique identifier.
[{...}].firstNameStringSubmitted first name.
[{...}].lastNameStringSubmitted last name.
[{...}].raceEthnicityAltStringSecond most likely race (US race categorization from US Census Taxonomy).U.S. race ethnicities
[{...}].raceEthnicityStringMost likely race (US race categorization from US Census Taxonomy).U.S. race ethnicities
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.
[{...}].raceEthnicitiesTopArrayMost likely race, sorted from most likely to least likely (US race categorization from US Census Taxonomy).U.S. race ethnicities
[{...}].probabilityCalibratedNumberThe calibrated probability that raceEthnicity has been guessed correctly. -1 = still calibrating.
[{...}].probabilityAltCalibratedNumberThe 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
        }
    ]
}

Name US Race ZIP code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/usZipRaceEthnicityBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"728767f9-c5b2-4ed3-a071-828077f16552\",\"firstName\":\"Keith\",\"lastName\":\"Haring\",\"countryIso2\":\"US\",\"zipCode\":\"10019\"}]}")
.asString();

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
        }
    ]
}

Name US Race ZIP code sample for python:

import requests

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

payload = {
  "personalNames": [
    {
      "id": "728767f9-c5b2-4ed3-a071-828077f16552",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US",
      "zipCode": "10019"
    }
  ]
}
headers = {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
}

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

print(response.text)

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
        }
    ]
}

Name US Race ZIP code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/usZipRaceEthnicityBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
  "personalNames": [
    {
      "id": "728767f9-c5b2-4ed3-a071-828077f16552",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US",
      "zipCode": "10019"
    }
  ]
})
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

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
        }
    ]
}
information

For requests with a GET method all parameters are required. For more ease in the use of our requests we recommend that you use the POST method.

  • Description: Returns the most likely US race from a first name and/or a last name using their ZIP code.
  • Precision:Precision gauge
  • Cost: 10 credits per name.
  • Test: Name US Race ZIP feature.

HTTP request

http request
GET
https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityZIP5/{firstName}/{lastName}/{zipCode}
Request header
PropertyValuesRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
X-OPTION-USRACEETHNICITY-TAXONOMYUSRACEETHNICITY-6CLASSESOptionalEnumerators 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.
Request parameters
NameTypeRequiredDescription
firstNameStringRequiredFirst name, given name, nickname.
lastNameStringRequiredLast name, family name, surname.
zipCodeStringRequiredPostal code (5-digit) of residence used by the United States Postal Service (USPS).
Response
NameTypeDescriptionEnumerators
scriptStringName of the script used for the name, in ISO 15924 format.Script
idStringUnique identifier.
firstNameStringSubmitted first name.
lastNameStringSubmitted last name.
raceEthnicityAltStringSecond most likely race (US race categorization from US Census Taxonomy).U.S. race ethnicities
raceEthnicityStringMost likely race (US race categorization from US Census Taxonomy).U.S. race ethnicities
scoreNumberHigher implies a more reliable result, score is not normalized.
raceEthnicitiesTopArrayMost likely race, sorted from most likely to least likely (US race categorization from US Census Taxonomy).U.S. race ethnicities
probabilityCalibratedNumberThe calibrated probability that raceEthnicity has been guessed correctly. -1 = still calibrating.
probabilityAltCalibratedNumberThe 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 GET \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityZIP5/Keith/Haring/10019 \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'

The above command returns JSON structured like this:

{
    "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
}

Name US Race ZIP code sample for java:

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

The above command returns JSON structured like this:

{
    "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
}

Name US Race ZIP code sample for python:

import requests

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

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

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

print(response.text)

The above command returns JSON structured like this:

{
    "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
}

Name US Race ZIP code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityZIP5/Keith/Haring/10019", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

The above command returns JSON structured like this:

{
    "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

information

If the first and last name are clearly identifiable, the Name US Race feature will be slightly more accurate.

HTTP request

http request
POST
https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityFullBatch
Request header
PropertyValuesRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
X-OPTION-USRACEETHNICITY-TAXONOMYUSRACEETHNICITY-6CLASSESOptionalEnumerators 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.
Request body
NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal full names with their country of residence.
[{...}].idStringOptionalUnique identifier.
[{...}].nameStringRequiredUnsplit full name (first name and last name).
[{...}].countryIso2StringOptionalCountry of residence, in ISO 3166-1 alpha-2 format.
Response
NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted full names with their race.
[{...}].scriptStringName of the script used for the name, in ISO 15924 format.Script
[{...}].idStringProvided unique identifier.
[{...}].nameStringSubmitted full name.
[{...}].raceEthnicityAltStringSecond most likely race (US race categorization from US Census Taxonomy).U.S. race ethnicities
[{...}].raceEthnicityStringMost likely race (US race categorization from US Census Taxonomy).U.S. race ethnicities
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.
[{...}].raceEthnicitiesTopArrayMost likely race, sorted from most likely to least likely (US race categorization from US Census Taxonomy).U.S. race ethnicities
[{...}].probabilityCalibratedNumberThe calibrated probability that raceEthnicity has been guessed correctly. -1 = still calibrating.
[{...}].probabilityAltCalibratedNumberThe 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
        }
    ]
}

Full Name US Race code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityFullBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"85dd5f48-b9e1-4019-88ce-ccc7e56b763f\",\"name\":\"Keith Haring\",\"countryIso2\":\"US\"}]}")
.asString();

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
        }
    ]
}

Full Name US Race code sample for python:

import requests

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

payload = {
  "personalNames": [
    {
      "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
      "name": "Keith Haring",
      "countryIso2": "US"
    }
  ]
}
headers = {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
}

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

print(response.text)

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
        }
    ]
}

Full Name US Race code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityFullBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
  "personalNames": [
    {
      "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
      "name": "Keith Haring",
      "countryIso2": "US"
    }
  ]
})
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

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
        }
    ]
}
information

For requests with a GET method all parameters are required. For more ease in the use of our requests we recommend that you use the POST method.

HTTP request

http request
GET
https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityFull/{name}
Request header
PropertyValuesRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
X-OPTION-USRACEETHNICITY-TAXONOMYUSRACEETHNICITY-6CLASSESOptionalEnumerators 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.
Request parameters
NameTypeRequiredDescription
nameStringRequiredUnsplit full name (first name and last name).
Response
NameTypeDescriptionEnumerators
scriptStringName of the script used for the name, in ISO 15924 format.Script
idStringUnique identifier.
nameStringSubmitted full name.
raceEthnicityAltStringSecond most likely race (US race categorization from US Census Taxonomy).U.S. race ethnicities
raceEthnicityStringMost likely race (US race categorization from US Census Taxonomy).U.S. race ethnicities
scoreNumberHigher implies a more reliable result, score is not normalized.
raceEthnicitiesTopArrayMost likely race ethnicities, sorted from most likely to least likely (US race categorization from US Census Taxonomy).U.S. race ethnicities
probabilityCalibratedNumberThe calibrated probability that raceEthnicity has been guessed correctly. -1 = still calibrating.
probabilityAltCalibratedNumberThe 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 GET \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityFull/Keith%20Haring \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'

The above command returns JSON structured like this:

{
    "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
}

Full Name US Race code sample for java:

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

The above command returns JSON structured like this:

{
    "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
}

Full Name US Race code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityFull/Keith%20Haring"

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

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

print(response.text)

The above command returns JSON structured like this:

{
    "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
}

Full Name US Race code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityFull/Keith%20Haring", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

The above command returns JSON structured like this:

{
    "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:Precision gauge
  • Cost: 10 credits per name.
  • Test: Name Country feature.

HTTP request

http request
POST
https://v2.namsor.com/NamSorAPIv2/api2/json/countryFnLnBatch
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request body
NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names.
[{...}].idStringOptionalUnique identifier.
[{...}].firstNameStringOptionalFirst name, given name, nickname.
[{...}].lastNameStringOptionalLast name, family name, surname.
Response
NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names with their countries of residence.
[{...}].scriptStringName of the script used for the name, in ISO 15924 format.Script
[{...}].idStringProvided unique identifier.
[{...}].firstNameStringSubmitted first name.
[{...}].lastNameStringSubmitted last name.
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.
[{...}].countryStringMost likely country of residence, in ISO 3166-1 alpha-2 format.Country of residence
[{...}].countryAltStringSecond most likely country of residence, in ISO 3166-1 alpha-2 format.Country of residence
[{...}].regionStringMost likely region of residence.Regions of origin or residence
[{...}].topRegionStringMost likely region of residence (alternative classification).Regions of origin or residence
[{...}].subRegionStringMost likely sub-region of residence.Sub regions of origin or residence
[{...}].countriesTopArrayTop 10 most likely countries of residence, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely.
[{...}].probabilityCalibratedNumberThe calibrated probability that country has been guessed correctly. -1 = still calibrating.
[{...}].probabilityAltCalibratedNumberThe 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
        }
    ]
}

Name Country code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/countryFnLnBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4\",\"firstName\":\"Keith\",\"lastName\":\"Haring\"}]}")
.asString();

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
        }
    ]
}

Name Country code sample for python:

import requests

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

payload = {
  "personalNames": [
    {
      "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
      "firstName": "Keith",
      "lastName": "Haring"
    }
  ]
}
headers = {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
}

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

print(response.text)

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
        }
    ]
}

Name Country code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/countryFnLnBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
  "personalNames": [
    {
      "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
      "firstName": "Keith",
      "lastName": "Haring"
    }
  ]
})
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

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
        }
    ]
}
information

For requests with a GET method all parameters are required. For more ease in the use of our requests we recommend that you use the POST method.

  • Description: Returns the most likely country of residence from a first name and/or a last name.
  • Precision:Precision gauge
  • Cost: 10 credits per name.
  • Test: Name Country feature.

HTTP request

http request
GET
https://v2.namsor.com/NamSorAPIv2/api2/json/countryFnLn/{firstName}/{lastName}
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request parameters
NameTypeRequiredDescription
firstNameStringRequiredFirst name, given name, nickname.
lastNameStringRequiredLast name, family name, surname.
Response
NameTypeDescriptionEnumerators
scriptStringName of the script used for the name, in ISO 15924 format.Script
idStringUnique identifier.
firstNameStringSubmitted first name, given name or nickname.
lastNameStringSubmitted last name, family name or surname.
scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
countryStringMost likely country of origin, in ISO 3166-1 alpha-2 format.Country of residence
countryAltStringSecond most likely country of origin, in ISO 3166-1 alpha-2 format.Country of residence
regionStringMost likely region of origin.Regions of origin or residence
topRegionStringMost likely region of origin (alternative classification).Regions of origin or residence
subRegionStringMost likely sub-region of origin.Sub regions of origin or residence
countriesTopArrayTop 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely.
probabilityCalibratedNumberThe calibrated probability that country has been guessed correctly. -1 = still calibrating.
probabilityAltCalibratedNumberThe calibrated probability that country OR countryAlt have been guessed correctly. -1 = still calibrating.

Code sample:

Name Country code sample for shell:

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

The above command returns JSON structured like this:

{
    "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
}

Name Country code sample for java:

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

The above command returns JSON structured like this:

{
    "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
}

Name Country code sample for python:

import requests

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

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

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

print(response.text)

The above command returns JSON structured like this:

{
    "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
}

Name Country code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/countryFnLn/Keith/Haring", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

The above command returns JSON structured like this:

{
    "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.

information

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:Precision gauge
  • Cost: 10 credits per name.
  • Test: Full Name Country feature.

HTTP request

http request
POST
https://v2.namsor.com/NamSorAPIv2/api2/json/countryBatch
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request body
NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names.
[{...}].idStringOptionalUnique identifier.
[{...}].nameStringRequiredUnsplit full name (first name and last name).
Response
NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted full names with their countries of residence.
[{...}].scriptStringName of the script used for the name, in ISO 15924 format.Script
[{...}].idStringProvided unique identifier.
[{...}].nameStringSubmitted full name.
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.
[{...}].countryStringMost likely country of residence, in ISO 3166-1 alpha-2 format.Country of residence
[{...}].countryAltStringSecond most likely country of residence, in ISO 3166-1 alpha-2 format.Country of residence
[{...}].regionStringMost likely region of residence.Regions of origin or residence
[{...}].topRegionStringMost likely region of residence (alternative classification).Regions of origin or residence
[{...}].subRegionStringMost likely sub-region of residence.Sub regions of origin or residence
[{...}].countriesTopArrayTop 10 most likely countries of residence, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely.
[{...}].probabilityCalibratedNumberThe calibrated probability that country has been guessed correctly. -1 = still calibrating.
[{...}].probabilityAltCalibratedNumberThe 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
        }
    ]
}

Full Name Country code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/countryBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4\",\"name\":\"Keith Haring\"}]}")
.asString();

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
        }
    ]
}

Full Name Country code sample for python:

import requests

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

payload = {
  "personalNames": [
    {
      "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
      "name": "Keith Haring"
    }
  ]
}
headers = {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
}

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

print(response.text)

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
        }
    ]
}

Full Name Country code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/countryBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
  "personalNames": [
    {
      "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
      "name": "Keith Haring"
    }
  ]
})
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

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
        }
    ]
}
information

For requests with a GET method all parameters are required. For more ease in the use of our requests we recommend that you use the POST method.

  • Description: Returns the most likely country of residence from an unsplit full name.
  • Precision:Precision gauge
  • Cost: 10 credits per name.
  • Test: Full Name Country feature.

HTTP request

http request
GET
https://v2.namsor.com/NamSorAPIv2/api2/json/country/{name}
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request parameters
NameTypeRequiredDescription
nameStringRequiredUnsplit full name (first name and last name).
Response
NameTypeDescriptionEnumerators
scriptStringName of the script used for the name, in ISO 15924 format.Script
idStringUnique identifier.
nameStringSubmitted full name.
scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
countryStringMost likely country of origin, in ISO 3166-1 alpha-2 format.Country of residence
countryAltStringSecond most likely country of origin, in ISO 3166-1 alpha-2 format.Country of residence
regionStringMost likely region of origin.Regions of origin or residence
topRegionStringMost likely region of origin (alternative classification).Regions of origin or residence
subRegionStringMost likely sub-region of origin.Sub regions of origin or residence
countriesTopArrayTop 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely.
probabilityCalibratedNumberThe calibrated probability that country has been guessed correctly. -1 = still calibrating.
probabilityAltCalibratedNumberThe calibrated probability that country OR countryAlt have been guessed correctly. -1 = still calibrating.

Code sample:

Full Name Country code sample for shell:

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

The above command returns JSON structured like this:

{
    "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
}

Full Name Country code sample for java:

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

The above command returns JSON structured like this:

{
    "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
}

Full Name Country code sample for python:

import requests

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

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

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

print(response.text)

The above command returns JSON structured like this:

{
    "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
}

Full Name Country code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/country/Keith%20Haring", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

The above command returns JSON structured like this:

{
    "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

http request
POST
https://v2.namsor.com/NamSorAPIv2/api2/json/corridorBatch
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request body
NameTypeRequiredDescription
corridorFromToArray of objectsRequiredA list of name pairs, with country code (nameFrom -> nameTo)..
[{...}].idStringOptionalUnique identifier.
[{...}].firstLastNameGeoFromObjectRequired.
{...}.idStringOptionalUnique identifier.
{...}.firstNameStringRequiredFirst name (or given name) of the sender.
{...}.lastNameStringRequiredLast name (or family name) of the sender.
{...}.countryIso2StringRequiredCountry of origin of the sender, in ISO 3166-1 alpha-2 format.
[{...}].firstLastNameGeoToObjectRequired.
{...}.idStringOptionalUnique identifier.
{...}.firstNameStringRequiredFirst name (or given name) of the receiver.
{...}.lastNameStringRequiredLast name (or family name) of the receiver.
{...}.countryIso2StringRequiredCountry of origin of the receiver, in ISO 3166-1 alpha-2 format.
Response
NameTypeDescriptionEnumerators
corridorFromToArray of objectsA list of classified name pairs..
[{...}].idStringUnique identifier.
[{...}].firstLastNameGeoFromGenderObjectGender data for the sender name.
{...}.scriptStringName of the script used for the name, in ISO 15924 format.Script
{...}.idStringUnique identifier.
{...}.firstNameStringSubmitted first name (or given name) of the sender.
{...}.lastNameStringSubmitted last name (or family name) of the sender.
{...}.likelyGenderStringMost likely gender.Genders
{...}.genderScaleNumberGender scale ranging from -1 (male) to +1 (female).
{...}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
{...}.probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1.
[{...}].firstLastNameGeoToGenderObjectGender data for the receiver name.
{...}.scriptStringName of the script used for the name, in ISO 15924 format.Script
{...}.idStringUnique identifier.
{...}.firstNameStringSubmitted first name (or given name) of the receiver.
{...}.lastNameStringSubmitted last name (or family name) of the receiver.
{...}.likelyGenderStringMost likely gender.Genders
{...}.genderScaleNumberGender scale ranging from -1 (male) to +1 (female).
{...}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
{...}.probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1.
[{...}].firstLastNameGeoFromOriginObjectOrigin data for the sender name.
{...}.scriptStringName of the script used for the name, in ISO 15924 format.Script
{...}.idStringUnique identifier.
{...}.firstNameStringSubmitted first name (or given name) of the sender.
{...}.lastNameStringSubmitted last name (or family name) of the sender.
{...}.countryOriginStringMost likely country of origin of the sender, in ISO 3166-1 alpha-2 format.Country of origin
{...}.countryOriginAltStringSecond most likely country of origin of the sender, in ISO 3166-1 alpha-2 format.Country of origin
{...}.countriesOriginTopArrayTop 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
{...}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
{...}.regionOriginStringMost likely region of origin of the sender.Regions of origin or residence
{...}.topRegionOriginStringMost likely region of origin of the sender (alternative classification).Regions of origin or residence
{...}.subRegionOriginStringMost likely sub-region of origin of the sender.Sub regions of origin or residence
{...}.probabilityCalibratedNumberThe calibrated probability for countryOrigin to have been guessed correctly. -1 = still calibrating.
{...}.probabilityAltCalibratedNumberThe calibrated probability for countryOrigin OR countryOriginAlt to have been guessed correctly. -1 = still calibrating.
[{...}].firstLastNameGeoToOriginObjectOrigin data for the receiver name.
{...}.scriptStringName of the script used for the name, in ISO 15924 format.Script
{...}.idStringUnique identifier.
{...}.firstNameStringSubmitted first name (or given name) of the receiver.
{...}.lastNameStringSubmitted last name (or family name) of the receiver.
{...}.countryOriginStringMost likely country of origin of the receiver, in ISO 3166-1 alpha-2 format.Country of origin
{...}.countryOriginAltStringSecond most likely country of origin of the receiver, in ISO 3166-1 alpha-2 format.Country of origin
{...}.countriesOriginTopArrayTop 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
{...}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
{...}.regionOriginStringMost likely region of origin.Regions of origin or residence
{...}.topRegionOriginStringMost likely region of origin of the receiver (alternative classification).Regions of origin or residence
{...}.subRegionOriginStringMost likely sub-region of origin of the receiver.Sub regions of origin or residence
{...}.probabilityCalibratedNumberThe calibrated probability for countryOrigin to have been guessed correctly. -1 = still calibrating.
{...}.probabilityAltCalibratedNumberThe calibrated probability for countryOrigin OR countryOriginAlt to have been guessed correctly. -1 = still calibrating.
[{...}].firstLastNameGeoFromDiasporaObjectDiaspora data for the sender name.
{...}.scriptStringName of the script used for the name, in ISO 15924 format.Script
{...}.idStringUnique identifier.
{...}.firstNameStringSubmitted first name (or given name) of the sender.
{...}.lastNameStringSubmitted last name (or family name) of the sender.
{...}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
{...}.ethnicityAltStringSecond most likely ethnicity of the sender.Ethnicities or diasporas
{...}.ethnicityStringMost likely ethnicity of the sender.Ethnicities or diasporas
{...}.liftedBooleanIndicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule.
{...}.countryIso2StringSubmitted country of origin of the sender, in ISO 3166-1 alpha-2 format.Country of residence
{...}.ethnicitiesTopArrayTop 10 most likely ethnicities of the sender, ordered from most likely to least likely.Ethnicities or diasporas
[{...}].firstLastNameGeoToDiasporaObjectDiaspora data for the receiver name.
{...}.scriptStringName of the script used for the name, in ISO 15924 format.Script
{...}.idStringUnique identifier.
{...}.firstNameStringSubmitted first name (or given name) of the receiver.
{...}.lastNameStringSubmitted last name (or family name) of the receiver.
{...}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
{...}.ethnicityAltStringSecond most likely ethnicity of the receiver.Ethnicities or diasporas
{...}.ethnicityStringMost likely ethnicity of the receiver.Ethnicities or diasporas
{...}.liftedBooleanIndicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule.
{...}.countryIso2StringSubmitted country of origin of the receiver, in ISO 3166-1 alpha-2 format.Country of residence
{...}.ethnicitiesTopArrayTop 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"]
            }
        }
    ]
}

Names Corridor code sample for java:

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

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"]
            }
        }
    ]
}

Names Corridor code sample for python:

import requests

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

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

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

print(response.text)

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"]
            }
        }
    ]
}

Names Corridor code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/corridorBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
  "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"
      }
    }
  ]
})
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

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"]
            }
        }
    ]
}
information

For requests with a GET method all parameters are required. For more ease in the use of our requests we recommend that you use the POST method.

  • Description: Returns complete analysis of a cross border interactions between two names using their geographic context. The sender is the one who initiated the interaction (from) while the receiver is the one intended to receive the interaction (to).
  • Cost: 20 credits per name.
  • Test: Names Corridor feature.

HTTP request

http request
GET
https://v2.namsor.com/NamSorAPIv2/api2/json/corridor/{countryIso2}/{firstName}/{lastName}/{countryIso2}/{firstName}/{lastName}
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request parameters
NameTypeRequiredDescription
countryIso2StringRequiredCountry of origin of the sender, in ISO 3166-1 alpha-2 format.
firstNameStringRequiredFirst name (or given name) of the sender.
lastNameStringRequiredLast name (or family name) of the sender.
countryIso2StringRequiredCountry of origin of the receiver, in ISO 3166-1 alpha-2 format.
firstNameStringRequiredFirst name (or given name) of the receiver.
lastNameStringRequiredLast name (or family name) of the receiver.
Response
NameTypeDescriptionEnumerators
idStringUnique identifier.
firstLastNameGeoFromGenderObjectGender data for the sender name.
{...}.scriptStringName of the script used for the name, in ISO 15924 format.Script
{...}.idStringUnique identifier.
{...}.firstNameStringSubmitted first name (or given name) of the sender.
{...}.lastNameStringSubmitted last name (or family name) of the sender.
{...}.likelyGenderStringMost likely gender.Genders
{...}.genderScaleNumberGender scale ranging from -1 (male) to +1 (female).
{...}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
{...}.probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1.
firstLastNameGeoToGenderObjectGender data for the receiver name.
{...}.scriptStringName of the script used for the name, in ISO 15924 format.Script
{...}.idStringUnique identifier.
{...}.firstNameStringSubmitted first name (or given name) of the receiver.
{...}.lastNameStringSubmitted last name (or family name) of the receiver.
{...}.likelyGenderStringMost likely gender.Genders
{...}.genderScaleNumberGender scale ranging from -1 (male) to +1 (female).
{...}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
{...}.probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1.
firstLastNameGeoFromOriginObjectOrigin data for the sender name.
{...}.scriptStringName of the script used for the name, in ISO 15924 format.Script
{...}.idStringUnique identifier.
{...}.firstNameStringSubmitted first name (or given name) of the sender.
{...}.lastNameStringSubmitted last name (or family name) of the sender.
{...}.countryOriginStringMost likely country of origin of the sender, in ISO 3166-1 alpha-2 format.Country of origin
{...}.countryOriginAltStringSecond most likely country of origin of the sender, in ISO 3166-1 alpha-2 format.Country of origin
{...}.countriesOriginTopArrayTop 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
{...}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
{...}.regionOriginStringMost likely region of origin of the sender.Regions of origin or residence
{...}.topRegionOriginStringMost likely region of origin of the sender (alternative classification).Regions of origin or residence
{...}.subRegionOriginStringMost likely sub-region of origin of the sender.Sub regions of origin or residence
{...}.probabilityCalibratedNumberThe calibrated probability for countryOrigin to have been guessed correctly. -1 = still calibrating.
{...}.probabilityAltCalibratedNumberThe calibrated probability for countryOrigin OR countryOriginAlt to have been guessed correctly. -1 = still calibrating.
firstLastNameGeoToOriginObjectOrigin data for the receiver name.
{...}.scriptStringName of the script used for the name, in ISO 15924 format.Script
{...}.idStringUnique identifier.
{...}.firstNameStringSubmitted first name (or given name) of the receiver.
{...}.lastNameStringSubmitted last name (or family name) of the receiver.
{...}.countryOriginStringMost likely country of origin of the receiver, in ISO 3166-1 alpha-2 format.Country of origin
{...}.countryOriginAltStringSecond most likely country of origin of the receiver, in ISO 3166-1 alpha-2 format.Country of origin
{...}.countriesOriginTopArrayTop 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
{...}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
{...}.regionOriginStringMost likely region of origin.Regions of origin or residence
{...}.topRegionOriginStringMost likely region of origin of the receiver (alternative classification).Regions of origin or residence
{...}.subRegionOriginStringMost likely sub-region of origin of the receiver.Sub regions of origin or residence
{...}.probabilityCalibratedNumberThe calibrated probability for countryOrigin to have been guessed correctly. -1 = still calibrating.
{...}.probabilityAltCalibratedNumberThe calibrated probability for countryOrigin OR countryOriginAlt to have been guessed correctly. -1 = still calibrating.
firstLastNameGeoFromDiasporaObjectDiaspora data for the sender name.
{...}.scriptStringName of the script used for the name, in ISO 15924 format.Script
{...}.idStringUnique identifier.
{...}.firstNameStringSubmitted first name (or given name) of the sender.
{...}.lastNameStringSubmitted last name (or family name) of the sender.
{...}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
{...}.ethnicityAltStringSecond most likely ethnicity of the sender.Ethnicities or diasporas
{...}.ethnicityStringMost likely ethnicity of the sender.Ethnicities or diasporas
{...}.liftedBooleanIndicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule.
{...}.countryIso2StringSubmitted country of origin of the sender, in ISO 3166-1 alpha-2 format.Country of residence
{...}.ethnicitiesTopArrayTop 10 most likely ethnicities of the sender, ordered from most likely to least likely.Ethnicities or diasporas
firstLastNameGeoToDiasporaObjectDiaspora data for the receiver name.
{...}.scriptStringName of the script used for the name, in ISO 15924 format.Script
{...}.idStringUnique identifier.
{...}.firstNameStringSubmitted first name (or given name) of the receiver.
{...}.lastNameStringSubmitted last name (or family name) of the receiver.
{...}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
{...}.ethnicityAltStringSecond most likely ethnicity of the receiver.Ethnicities or diasporas
{...}.ethnicityStringMost likely ethnicity of the receiver.Ethnicities or diasporas
{...}.liftedBooleanIndicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule.
{...}.countryIso2StringSubmitted country of origin of the receiver, in ISO 3166-1 alpha-2 format.Country of residence
{...}.ethnicitiesTopArrayTop 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 GET \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/corridor/GB/Ada/Lovelace/US/Nicolas/Tesla \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'

The above command returns JSON structured like this:

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

Names Corridor code sample for java:

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

The above command returns JSON structured like this:

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

Names Corridor code sample for python:

import requests

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

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

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

print(response.text)

The above command returns JSON structured like this:

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

Names Corridor code sample for javascript:

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

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

The above command returns JSON structured like this:

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

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:Precision gauge
  • Cost: 1 credit per name.
  • Test: Genderize Name feature.

HTTP request

http request
POST
https://v2.namsor.com/NamSorAPIv2/api2/json/genderBatch
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request body
NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names.
[{...}].idStringOptionalUnique identifier.
[{...}].firstNameStringRequiredFirst name, given name, nickname.
[{...}].lastNameStringOptionalLast name, family name, surname.
Response
NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names genderized.
[{...}].scriptStringName of the script used for the name, in ISO 15924 format.Script
[{...}].idStringProvided unique identifier.
[{...}].firstNameStringSubmitted first name.
[{...}].lastNameStringSubmitted last name.
[{...}].likelyGenderStringMost likely gender.Genders
[{...}].genderScaleNumberGender scale ranging from -1 (male) to +1 (female).
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.
[{...}].probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1.

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 code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"b590b04c-da23-4f2f-a334-aee384ee420a\",\"firstName\":\"Keith\",\"lastName\":\"Haring\"}]}")
.asString();

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 code sample for python:

import requests

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

payload = {
  "personalNames": [
    {
      "id": "b590b04c-da23-4f2f-a334-aee384ee420a",
      "firstName": "Keith",
      "lastName": "Haring"
    }
  ]
}
headers = {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
}

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

print(response.text)

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 code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
  "personalNames": [
    {
      "id": "b590b04c-da23-4f2f-a334-aee384ee420a",
      "firstName": "Keith",
      "lastName": "Haring"
    }
  ]
})
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

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
        }
    ]
}
information

For requests with a GET method all parameters are required. For more ease in the use of our requests we recommend that you use the POST method.

  • Description: Returns the most likely gender of a first name and a last name.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Genderize Name feature.

HTTP request

http request
GET
https://v2.namsor.com/NamSorAPIv2/api2/json/gender/{firstName}/{lastName}
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request parameters
NameTypeRequiredDescription
firstNameStringRequiredFirst name, given name, nickname.
lastNameStringRequiredLast name, family name, surname.
Response
NameTypeDescriptionEnumerators
scriptStringName of the script used for the name, in ISO 15924 format.Script
idStringUnique identifier.
firstNameStringSubmitted first name.
lastNameStringSubmitted last name.
likelyGenderStringMost likely gender.Genders
genderScaleNumberGender scale ranging from -1 (male) to +1 (female).
scoreNumberHigher implies a more reliable result, score is not normalized.
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1.

Code sample:

Genderize Name code sample for shell:

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

The above command returns JSON structured like this:

{
    "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 code sample for java:

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

The above command returns JSON structured like this:

{
    "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 code sample for python:

import requests

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

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

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

print(response.text)

The above command returns JSON structured like this:

{
    "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 code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/gender/Keith/Haring", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

The above command returns JSON structured like this:

{
    "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:Precision gauge
  • Cost: 1 credit per name.
  • Test: Genderize Name Geo feature.

HTTP request

http request
POST
https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeoBatch
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request body
NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names with their country of residence.
[{...}].idStringOptionalUnique identifier.
[{...}].firstNameStringRequiredFirst name, given name, nickname.
[{...}].lastNameStringOptionalLast name, family name, surname.
[{...}].countryIso2StringRequiredMost likely country of residence, in ISO 3166-1 alpha-2 format.
Response
NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names genderized.
[{...}].scriptStringName of the script used for the name, in ISO 15924 format.Script
[{...}].idStringProvided unique identifier.
[{...}].firstNameStringSubmitted first name.
[{...}].lastNameStringSubmitted last name.
[{...}].likelyGenderStringMost likely gender.Genders
[{...}].genderScaleNumberGender scale ranging from -1 (male) to +1 (female).
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.
[{...}].probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1.

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 Name Geo code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeoBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"27fb45db-eddf-40d0-95c1-de9978a166b0\",\"firstName\":\"Keith\",\"lastName\":\"Haring\",\"countryIso2\":\"US\"}]}")
.asString();

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 Name Geo code sample for python:

import requests

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

payload = {
  "personalNames": [
    {
      "id": "27fb45db-eddf-40d0-95c1-de9978a166b0",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US"
    }
  ]
}
headers = {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
}

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

print(response.text)

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 Name Geo code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeoBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
  "personalNames": [
    {
      "id": "27fb45db-eddf-40d0-95c1-de9978a166b0",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US"
    }
  ]
})
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

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
        }
    ]
}
information

For requests with a GET method all parameters are required. For more ease in the use of our requests we recommend that you use the POST method.

  • Description: Returns the most likely gender of a first name and a last name using its geographic context.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Genderize Name Geo feature.

HTTP request

http request
GET
https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeo/{firstName}/{lastName}/{countryIso2}
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request parameters
NameTypeRequiredDescription
firstNameStringRequiredFirst name, given name, nickname.
lastNameStringRequiredLast name, family name, surname.
countryIso2StringRequiredMost likely country of origin, in ISO 3166-1 alpha-2 format.
Response
NameTypeDescriptionEnumerators
scriptStringName of the script used for the name, in ISO 15924 format.Script
idStringUnique identifier.
firstNameStringSubmitted first name.
lastNameStringSubmitted last name.
likelyGenderStringMost likely gender.Genders
genderScaleNumberGender scale ranging from -1 (male) to +1 (female).
scoreNumberHigher implies a more reliable result, score is not normalized.
probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1.

Code sample:

Genderize Name Geo code sample for shell:

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

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "27fb45db-eddf-40d0-95c1-de9978a166b0",
    "firstName": "Keith",
    "lastName": "Haring",
    "likelyGender": "male",
    "genderScale": -0.8889514731555574,
    "score": 16.03594419932244,
    "probabilityCalibrated": 0.9444757365777787
}

Genderize Name Geo code sample for java:

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

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "27fb45db-eddf-40d0-95c1-de9978a166b0",
    "firstName": "Keith",
    "lastName": "Haring",
    "likelyGender": "male",
    "genderScale": -0.8889514731555574,
    "score": 16.03594419932244,
    "probabilityCalibrated": 0.9444757365777787
}

Genderize Name Geo code sample for python:

import requests

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

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

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

print(response.text)

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "27fb45db-eddf-40d0-95c1-de9978a166b0",
    "firstName": "Keith",
    "lastName": "Haring",
    "likelyGender": "male",
    "genderScale": -0.8889514731555574,
    "score": 16.03594419932244,
    "probabilityCalibrated": 0.9444757365777787
}

Genderize Name Geo code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeo/Keith/Haring/US", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

The above command returns JSON structured like this:

{
    "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.

information

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:Precision gauge
  • Cost: 1 credit per name.
  • Test: Genderize Full Name feature.

HTTP request

http request
POST
https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullBatch
Request header
PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
Request body
NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal full names.
[{...}].idStringOptionalUnique identifier.
[{...}].nameStringRequiredUnsplit full name (first name and last name).
Response
NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted full names genderized.
[{...}].scriptStringName of the script used for the name, in ISO 15924 format.Script
[{...}].idStringProvided unique identifier.
[{...}].nameStringSubmitted full name.
[{...}].likelyGenderStringMost likely gender.Genders
[{...}].genderScaleNumberGender scale ranging from -1 (male) to +1 (female).
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.
[{...}].probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1.

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 code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"0f472330-11a9-49ad-a0f5-bcac90a3f6bf\",\"name\":\"Keith Haring\"}]}")
.asString();

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 code sample for python:

import requests

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

payload = {
  "personalNames": [
    {
      "id": "0f472330-11a9-49ad-a0f5-bcac90a3f6bf",
      "name": "Keith Haring"
    }
  ]
}
headers = {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
}

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

print(response.text)

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 code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
  "personalNames": [
    {
      "id": "0f472330-11a9-49ad-a0f5-bcac90a3f6bf",
      "name": "Keith Haring"
    }
  ]
})
});

if (response.ok) {
  const data = await response.json(); // Extract JSON data from response
  console.log(data); // View data in the console
} else {
  console.error("The request failed with status:", response.status, response);
}

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
        }
    ]
}
information</