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 by using the corresponding Admin route. When set to false for an API key, the data processed using that key will not feed the machine learning algorithm.

If you wish to disable service usage history, please set anonymized to true by using the corresponding Admin route. When set to true for an API key, the data processed using that key will be irreversibly anonymised using SHA encryption. Note that the smart processing for redundant queries will still work even if your data is anonymised.

Authentication

API Key Creation

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 Ethnicity Estimate'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.

info symbol

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 U.S. race ethncities.
  • Process 50 names to determine their countries of residence.
  • Process 500 names to determine their genders.
info symbol

Admin routes are free.

Repeated Operations Tolerance

Our API features smart processing and it will not charge for analyzing identical data for up to 20 times. For example if you submit the same full name 5 times in order to infer it's origin then you will only be charged 1 credit.

Soft Limit vs Hard Limit

In your user account you may set two types of credit usage limits:

  • A soft limit that will trigger an email notification when reached.
  • A hard limit that will trigger an email notification and block the API key when reached.

Track Usage

There are two ways to track your credit usage: check the provided graphics in your user account or query the appropriate Admin routes (API Usage, API Usage History and API Usage History Aggregate).

Errors

The NamSor API uses the following error codes:

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

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 U.S. race classification. We also provide a corridor evalutation API, to check background information about international interactions.

Name Origin

Name Origin feature analyzes a 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".

  • Description: Returns the most likely country of origin of up to 100 first names and/or last names.
  • Cost: 10 credits per name.
  • Test: Name Origin feature.

HTTP request

http requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/originBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names.
[{...}].idStringOptionalUnique identifier.
[{...}].firstNameStringOptionalFirst name, given name, nickname.
[{...}].lastNameStringOptionalLast name, family name, surname.

Response

The HTTP response body is a nested array "personalNames" of objects.

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names with their countries of origin.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].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",
        "DK",
        "MY",
        "SE",
        "CH",
        "NO",
        "EE"
      ],
      "score": 3.736975858512923,
      "regionOrigin": "Europe",
      "topRegionOrigin": "Europe",
      "subRegionOrigin": "Northern Europe",
      "probabilityCalibrated": 0.48126571888420216,
      "probabilityAltCalibrated": 0.622489299549084
    }
  ]
}

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",
        "DK",
        "MY",
        "SE",
        "CH",
        "NO",
        "EE"
      ],
      "score": 3.736975858512923,
      "regionOrigin": "Europe",
      "topRegionOrigin": "Europe",
      "subRegionOrigin": "Northern Europe",
      "probabilityCalibrated": 0.48126571888420216,
      "probabilityAltCalibrated": 0.622489299549084
    }
  ]
}

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",
        "DK",
        "MY",
        "SE",
        "CH",
        "NO",
        "EE"
      ],
      "score": 3.736975858512923,
      "regionOrigin": "Europe",
      "topRegionOrigin": "Europe",
      "subRegionOrigin": "Northern Europe",
      "probabilityCalibrated": 0.48126571888420216,
      "probabilityAltCalibrated": 0.622489299549084
    }
  ]
}

Name Origin code sample for javascript :

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

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",
        "DK",
        "MY",
        "SE",
        "CH",
        "NO",
        "EE"
      ],
      "score": 3.736975858512923,
      "regionOrigin": "Europe",
      "topRegionOrigin": "Europe",
      "subRegionOrigin": "Northern Europe",
      "probabilityCalibrated": 0.48126571888420216,
      "probabilityAltCalibrated": 0.622489299549084
    }
  ]
}
info symbol

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

HTTP request

http requestGET
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

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis.Alphabets
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": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
  "firstName": "Keith",
  "lastName": "Haring",
  "countryOrigin": "GB",
  "countryOriginAlt": "IE",
  "countriesOriginTop": [
    "GB",
    "IE",
    "DE",
    "NL",
    "DK",
    "MY",
    "SE",
    "CH",
    "NO",
    "EE"
  ],
  "score": 3.736975858512923,
  "regionOrigin": "Europe",
  "topRegionOrigin": "Europe",
  "subRegionOrigin": "Northern Europe",
  "probabilityCalibrated": 0.48126571888420216,
  "probabilityAltCalibrated": 0.622489299549084
}

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": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
  "firstName": "Keith",
  "lastName": "Haring",
  "countryOrigin": "GB",
  "countryOriginAlt": "IE",
  "countriesOriginTop": [
    "GB",
    "IE",
    "DE",
    "NL",
    "DK",
    "MY",
    "SE",
    "CH",
    "NO",
    "EE"
  ],
  "score": 3.736975858512923,
  "regionOrigin": "Europe",
  "topRegionOrigin": "Europe",
  "subRegionOrigin": "Northern Europe",
  "probabilityCalibrated": 0.48126571888420216,
  "probabilityAltCalibrated": 0.622489299549084
}

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": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
  "firstName": "Keith",
  "lastName": "Haring",
  "countryOrigin": "GB",
  "countryOriginAlt": "IE",
  "countriesOriginTop": [
    "GB",
    "IE",
    "DE",
    "NL",
    "DK",
    "MY",
    "SE",
    "CH",
    "NO",
    "EE"
  ],
  "score": 3.736975858512923,
  "regionOrigin": "Europe",
  "topRegionOrigin": "Europe",
  "subRegionOrigin": "Northern Europe",
  "probabilityCalibrated": 0.48126571888420216,
  "probabilityAltCalibrated": 0.622489299549084
}

Name Origin code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/origin/Keith/Haring", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

The above command returns JSON structured like this :

{
  "script": "LATIN",
  "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
  "firstName": "Keith",
  "lastName": "Haring",
  "countryOrigin": "GB",
  "countryOriginAlt": "IE",
  "countriesOriginTop": [
    "GB",
    "IE",
    "DE",
    "NL",
    "DK",
    "MY",
    "SE",
    "CH",
    "NO",
    "EE"
  ],
  "score": 3.736975858512923,
  "regionOrigin": "Europe",
  "topRegionOrigin": "Europe",
  "subRegionOrigin": "Northern Europe",
  "probabilityCalibrated": 0.48126571888420216,
  "probabilityAltCalibrated": 0.622489299549084
}

Name Diaspora

Name Diaspora feature analyzes a 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.

  • Description: Returns the most likely ethnicity or diaspora of up to 100 first names and/or last names, according to their country of residence.
  • Cost: 20 credits per name.
  • Test: Name Diaspora feature.

HTTP request

http requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/diasporaBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

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

The HTTP response body is a nested array "personalNames" of objects.

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names with their ethnicities.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].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": 10.578504679244919,
      "ethnicityAlt": "British",
      "ethnicity": "German",
      "lifted": false,
      "countryIso2": "US",
      "ethnicitiesTop": [
        "German",
        "British",
        "Dutch",
        "Danish",
        "Irish",
        "Jewish",
        "Norwegian",
        "HispanoLatino",
        "Swedish",
        "AfricanAmerican"
      ],
      "probabilityCalibrated": 0.6115763692637636,
      "probabilityAltCalibrated": 0.6115763692637636
    }
  ]
}

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": 10.578504679244919,
      "ethnicityAlt": "British",
      "ethnicity": "German",
      "lifted": false,
      "countryIso2": "US",
      "ethnicitiesTop": [
        "German",
        "British",
        "Dutch",
        "Danish",
        "Irish",
        "Jewish",
        "Norwegian",
        "HispanoLatino",
        "Swedish",
        "AfricanAmerican"
      ],
      "probabilityCalibrated": 0.6115763692637636,
      "probabilityAltCalibrated": 0.6115763692637636
    }
  ]
}

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": 10.578504679244919,
      "ethnicityAlt": "British",
      "ethnicity": "German",
      "lifted": false,
      "countryIso2": "US",
      "ethnicitiesTop": [
        "German",
        "British",
        "Dutch",
        "Danish",
        "Irish",
        "Jewish",
        "Norwegian",
        "HispanoLatino",
        "Swedish",
        "AfricanAmerican"
      ],
      "probabilityCalibrated": 0.6115763692637636,
      "probabilityAltCalibrated": 0.6115763692637636
    }
  ]
}

Name Diaspora code sample for javascript :

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": "{
  "personalNames": [
    {
      "id": "0d7d6417-0bbb-4205-951d-b3473f605b56",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

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": 10.578504679244919,
      "ethnicityAlt": "British",
      "ethnicity": "German",
      "lifted": false,
      "countryIso2": "US",
      "ethnicitiesTop": [
        "German",
        "British",
        "Dutch",
        "Danish",
        "Irish",
        "Jewish",
        "Norwegian",
        "HispanoLatino",
        "Swedish",
        "AfricanAmerican"
      ],
      "probabilityCalibrated": 0.6115763692637636,
      "probabilityAltCalibrated": 0.6115763692637636
    }
  ]
}
info symbol

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 and/or last name, according to the country of residence.
  • Cost: 20 credits per name.
  • Test: Name Diaspora feature.

HTTP request

http requestGET
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.
firstNameStringRequiredFirst name, given name, nickname.
lastNameStringRequiredLast name, family name, surname.

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis.Alphabets
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": 10.578504679244919,
  "ethnicityAlt": "British",
  "ethnicity": "German",
  "lifted": false,
  "countryIso2": "US",
  "ethnicitiesTop": [
    "German",
    "British",
    "Dutch",
    "Danish",
    "Irish",
    "Jewish",
    "Norwegian",
    "HispanoLatino",
    "Swedish",
    "AfricanAmerican"
  ],
  "probabilityCalibrated": 0.6115763692637636,
  "probabilityAltCalibrated": 0.6115763692637636
}

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": 10.578504679244919,
  "ethnicityAlt": "British",
  "ethnicity": "German",
  "lifted": false,
  "countryIso2": "US",
  "ethnicitiesTop": [
    "German",
    "British",
    "Dutch",
    "Danish",
    "Irish",
    "Jewish",
    "Norwegian",
    "HispanoLatino",
    "Swedish",
    "AfricanAmerican"
  ],
  "probabilityCalibrated": 0.6115763692637636,
  "probabilityAltCalibrated": 0.6115763692637636
}

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": 10.578504679244919,
  "ethnicityAlt": "British",
  "ethnicity": "German",
  "lifted": false,
  "countryIso2": "US",
  "ethnicitiesTop": [
    "German",
    "British",
    "Dutch",
    "Danish",
    "Irish",
    "Jewish",
    "Norwegian",
    "HispanoLatino",
    "Swedish",
    "AfricanAmerican"
  ],
  "probabilityCalibrated": 0.6115763692637636,
  "probabilityAltCalibrated": 0.6115763692637636
}

Name Diaspora code sample for javascript :

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

The above command returns JSON structured like this :

{
  "script": "LATIN",
  "id": "0d7d6417-0bbb-4205-951d-b3473f605b56",
  "firstName": "Keith",
  "lastName": "Haring",
  "score": 10.578504679244919,
  "ethnicityAlt": "British",
  "ethnicity": "German",
  "lifted": false,
  "countryIso2": "US",
  "ethnicitiesTop": [
    "German",
    "British",
    "Dutch",
    "Danish",
    "Irish",
    "Jewish",
    "Norwegian",
    "HispanoLatino",
    "Swedish",
    "AfricanAmerican"
  ],
  "probabilityCalibrated": 0.6115763692637636,
  "probabilityAltCalibrated": 0.6115763692637636
}

Name US Race

Name U.S. Race feature analyzes a name to identify the most likely U.S. race ethnicity. The feature returns the most likely U.S. race ethnicity and a list of the most likely U.S. race ethnicities, sorted from most likely to least likely. Each ethnicity returned is accompanied by a calibrated probability.

U.S. race and ethnicity is a categorization from United States Census Taxonomy

HTTP request

http requestPOST
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).

Request body

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

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

The HTTP response body is a nested array "personalNames" of objects.

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names with their race ethnicity.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].idStringProvided unique identifier.
[{...}].firstNameStringSubmitted first name.
[{...}].lastNameStringSubmitted last name.
[{...}].raceEthnicityAltStringSecond most likely ethnicity (U.S. race and ethnicity categorization from US Census Taxonomy).U.S. race ethnicities
[{...}].raceEthnicityStringMost likely ethnicity (U.S. race and ethnicity categorization from US Census Taxonomy).U.S. race ethnicities
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.
[{...}].raceEthnicitiesTopArrayMost likely ethnicity, sorted from most likely to least likely (U.S. race and ethnicity categorization 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": "AI_AN",
      "raceEthnicity": "W_NL",
      "score": 7.104050454229515,
      "raceEthnicitiesTop": [
        "W_NL",
        "AI_AN",
        "B_NL",
        "A",
        "PI",
        "HL"
      ],
      "probabilityCalibrated": 0.7271969971540807,
      "probabilityAltCalibrated": 0.8701551006716921
    }
  ]
}

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": "AI_AN",
      "raceEthnicity": "W_NL",
      "score": 7.104050454229515,
      "raceEthnicitiesTop": [
        "W_NL",
        "AI_AN",
        "B_NL",
        "A",
        "PI",
        "HL"
      ],
      "probabilityCalibrated": 0.7271969971540807,
      "probabilityAltCalibrated": 0.8701551006716921
    }
  ]
}

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": "AI_AN",
      "raceEthnicity": "W_NL",
      "score": 7.104050454229515,
      "raceEthnicitiesTop": [
        "W_NL",
        "AI_AN",
        "B_NL",
        "A",
        "PI",
        "HL"
      ],
      "probabilityCalibrated": 0.7271969971540807,
      "probabilityAltCalibrated": 0.8701551006716921
    }
  ]
}

Name US Race code sample for javascript :

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": "{
  "personalNames": [
    {
      "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

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": "AI_AN",
      "raceEthnicity": "W_NL",
      "score": 7.104050454229515,
      "raceEthnicitiesTop": [
        "W_NL",
        "AI_AN",
        "B_NL",
        "A",
        "PI",
        "HL"
      ],
      "probabilityCalibrated": 0.7271969971540807,
      "probabilityAltCalibrated": 0.8701551006716921
    }
  ]
}
info symbol

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 requestGET
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).

Request parameters

NameTypeRequiredDescription
firstNameStringRequiredFirst name, given name, nickname.
lastNameStringRequiredLast name, family name, surname.

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis.Alphabets
idStringUnique identifier.
firstNameStringSubmitted first name.
lastNameStringSubmitted last name.
raceEthnicityAltStringSecond most likely ethnicity (U.S. race and ethnicity categorization from US Census Taxonomy).U.S. race ethnicities
raceEthnicityStringMost likely ethnicity (U.S. race and ethnicity categorization from US Census Taxonomy).U.S. race ethnicities
scoreNumberHigher implies a more reliable result, score is not normalized.
raceEthnicitiesTopArrayMost likely ethnicity, sorted from most likely to least likely (U.S. race and ethnicity categorization 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": "AI_AN",
  "raceEthnicity": "W_NL",
  "score": 7.104050454229515,
  "raceEthnicitiesTop": [
    "W_NL",
    "AI_AN",
    "B_NL",
    "A",
    "PI",
    "HL"
  ],
  "probabilityCalibrated": 0.7271969971540807,
  "probabilityAltCalibrated": 0.8701551006716921
}

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": "AI_AN",
  "raceEthnicity": "W_NL",
  "score": 7.104050454229515,
  "raceEthnicitiesTop": [
    "W_NL",
    "AI_AN",
    "B_NL",
    "A",
    "PI",
    "HL"
  ],
  "probabilityCalibrated": 0.7271969971540807,
  "probabilityAltCalibrated": 0.8701551006716921
}

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": "AI_AN",
  "raceEthnicity": "W_NL",
  "score": 7.104050454229515,
  "raceEthnicitiesTop": [
    "W_NL",
    "AI_AN",
    "B_NL",
    "A",
    "PI",
    "HL"
  ],
  "probabilityCalibrated": 0.7271969971540807,
  "probabilityAltCalibrated": 0.8701551006716921
}

Name US Race code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicity/Keith/Haring", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

The above command returns JSON structured like this :

{
  "script": "LATIN",
  "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
  "firstName": "Keith",
  "lastName": "Haring",
  "raceEthnicityAlt": "AI_AN",
  "raceEthnicity": "W_NL",
  "score": 7.104050454229515,
  "raceEthnicitiesTop": [
    "W_NL",
    "AI_AN",
    "B_NL",
    "A",
    "PI",
    "HL"
  ],
  "probabilityCalibrated": 0.7271969971540807,
  "probabilityAltCalibrated": 0.8701551006716921
}

Name US Race ZIP

Name U.S. Race ZIP feature analyzes a name to identify the most likely U.S. race ethnicity with improved accuracy than the basic feature Name U.S. Race. The feature returns the most likely U.S. race ethnicity and a list of the most likely U.S. race ethnicities, sorted from most likely to least likely. Each ethnicity returned is accompanied by a calibrated probability.

U.S. race and ethnicity is a categorization from United States Census Taxonomy

HTTP request

http requestPOST
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).

Request body

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

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

The HTTP response body is a nested array "personalNames" of objects.

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names with their race ethnicity.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].idStringProvided unique identifier.
[{...}].firstNameStringSubmitted first name.
[{...}].lastNameStringSubmitted last name.
[{...}].raceEthnicityAltStringSecond most likely ethnicity (U.S. race and ethnicity categorization from US Census Taxonomy).U.S. race ethnicities
[{...}].raceEthnicityStringMost likely ethnicity (U.S. race and ethnicity categorization from US Census Taxonomy).U.S. race ethnicities
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.
[{...}].raceEthnicitiesTopArrayMost likely ethnicity, sorted from most likely to least likely (U.S. race and ethnicity categorization 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": "AI_AN",
      "raceEthnicity": "W_NL",
      "score": 3.9085123822664136,
      "raceEthnicitiesTop": [
        "W_NL",
        "AI_AN",
        "A",
        "B_NL",
        "PI",
        "HL"
      ],
      "probabilityCalibrated": 0.6021205204922562,
      "probabilityAltCalibrated": 0.8421508050514268
    }
  ]
}

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": "AI_AN",
      "raceEthnicity": "W_NL",
      "score": 3.9085123822664136,
      "raceEthnicitiesTop": [
        "W_NL",
        "AI_AN",
        "A",
        "B_NL",
        "PI",
        "HL"
      ],
      "probabilityCalibrated": 0.6021205204922562,
      "probabilityAltCalibrated": 0.8421508050514268
    }
  ]
}

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": "AI_AN",
      "raceEthnicity": "W_NL",
      "score": 3.9085123822664136,
      "raceEthnicitiesTop": [
        "W_NL",
        "AI_AN",
        "A",
        "B_NL",
        "PI",
        "HL"
      ],
      "probabilityCalibrated": 0.6021205204922562,
      "probabilityAltCalibrated": 0.8421508050514268
    }
  ]
}

Name US Race ZIP code sample for javascript :

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": "{
  "personalNames": [
    {
      "id": "728767f9-c5b2-4ed3-a071-828077f16552",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US",
      "zipCode": "10019"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

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": "AI_AN",
      "raceEthnicity": "W_NL",
      "score": 3.9085123822664136,
      "raceEthnicitiesTop": [
        "W_NL",
        "AI_AN",
        "A",
        "B_NL",
        "PI",
        "HL"
      ],
      "probabilityCalibrated": 0.6021205204922562,
      "probabilityAltCalibrated": 0.8421508050514268
    }
  ]
}
info symbol

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 requestGET
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).

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

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis.Alphabets
idStringUnique identifier.
firstNameStringSubmitted first name.
lastNameStringSubmitted last name.
raceEthnicityAltStringSecond most likely ethnicity (U.S. race and ethnicity categorization from US Census Taxonomy).U.S. race ethnicities
raceEthnicityStringMost likely ethnicity (U.S. race and ethnicity categorization from US Census Taxonomy).U.S. race ethnicities
scoreNumberHigher implies a more reliable result, score is not normalized.
raceEthnicitiesTopArrayMost likely ethnicity, sorted from most likely to least likely (U.S. race and ethnicity categorization 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": "AI_AN",
  "raceEthnicity": "W_NL",
  "score": 3.9085123822664136,
  "raceEthnicitiesTop": [
    "W_NL",
    "AI_AN",
    "A",
    "B_NL",
    "PI",
    "HL"
  ],
  "probabilityCalibrated": 0.6021205204922562,
  "probabilityAltCalibrated": 0.8421508050514268
}

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": "AI_AN",
  "raceEthnicity": "W_NL",
  "score": 3.9085123822664136,
  "raceEthnicitiesTop": [
    "W_NL",
    "AI_AN",
    "A",
    "B_NL",
    "PI",
    "HL"
  ],
  "probabilityCalibrated": 0.6021205204922562,
  "probabilityAltCalibrated": 0.8421508050514268
}

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": "AI_AN",
  "raceEthnicity": "W_NL",
  "score": 3.9085123822664136,
  "raceEthnicitiesTop": [
    "W_NL",
    "AI_AN",
    "A",
    "B_NL",
    "PI",
    "HL"
  ],
  "probabilityCalibrated": 0.6021205204922562,
  "probabilityAltCalibrated": 0.8421508050514268
}

Name US Race ZIP code sample for javascript :

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

The above command returns JSON structured like this :

{
  "script": "LATIN",
  "id": "728767f9-c5b2-4ed3-a071-828077f16552",
  "firstName": "Keith",
  "lastName": "Haring",
  "raceEthnicityAlt": "AI_AN",
  "raceEthnicity": "W_NL",
  "score": 3.9085123822664136,
  "raceEthnicitiesTop": [
    "W_NL",
    "AI_AN",
    "A",
    "B_NL",
    "PI",
    "HL"
  ],
  "probabilityCalibrated": 0.6021205204922562,
  "probabilityAltCalibrated": 0.8421508050514268
}

Name Country

Name Country feature analyzes a 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.

  • Description: Returns the most likely country of residence of up to 100 first names, last names or full names.
  • Cost: 10 credits per name.
  • Test: Name Country feature.

HTTP request

http requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/countryBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names.
[{...}].idStringOptionalUnique identifier.
[{...}].nameStringRequiredFirst name, or last name, or full name.

Response

The HTTP response body is a nested array "personalNames" of objects.

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names with their countries of residence.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].idStringProvided unique identifier.
[{...}].nameStringSubmitted 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/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": 14.474855749439138,
      "country": "US",
      "countryAlt": "NZ",
      "region": "Northern America",
      "topRegion": "Americas",
      "subRegion": "Northern America",
      "countriesTop": [
        "US",
        "NZ",
        "AU",
        "GB",
        "IE",
        "CA",
        "DE",
        "SG",
        "JM",
        "HK"
      ],
      "probabilityCalibrated": 0.5543051242619337,
      "probabilityAltCalibrated": 0.5722556327291567
    }
  ]
}

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": 14.474855749439138,
      "country": "US",
      "countryAlt": "NZ",
      "region": "Northern America",
      "topRegion": "Americas",
      "subRegion": "Northern America",
      "countriesTop": [
        "US",
        "NZ",
        "AU",
        "GB",
        "IE",
        "CA",
        "DE",
        "SG",
        "JM",
        "HK"
      ],
      "probabilityCalibrated": 0.5543051242619337,
      "probabilityAltCalibrated": 0.5722556327291567
    }
  ]
}

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": 14.474855749439138,
      "country": "US",
      "countryAlt": "NZ",
      "region": "Northern America",
      "topRegion": "Americas",
      "subRegion": "Northern America",
      "countriesTop": [
        "US",
        "NZ",
        "AU",
        "GB",
        "IE",
        "CA",
        "DE",
        "SG",
        "JM",
        "HK"
      ],
      "probabilityCalibrated": 0.5543051242619337,
      "probabilityAltCalibrated": 0.5722556327291567
    }
  ]
}

Name Country code sample for javascript :

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": "{
  "personalNames": [
    {
      "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
      "name": "Keith Haring"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

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": 14.474855749439138,
      "country": "US",
      "countryAlt": "NZ",
      "region": "Northern America",
      "topRegion": "Americas",
      "subRegion": "Northern America",
      "countriesTop": [
        "US",
        "NZ",
        "AU",
        "GB",
        "IE",
        "CA",
        "DE",
        "SG",
        "JM",
        "HK"
      ],
      "probabilityCalibrated": 0.5543051242619337,
      "probabilityAltCalibrated": 0.5722556327291567
    }
  ]
}
info symbol

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, a last name or a full name.
  • Cost: 10 credits per name.
  • Test: Name Country feature.

HTTP request

http requestGET
https://v2.namsor.com/NamSorAPIv2/api2/json/country/{name}

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request parameters

NameTypeRequiredDescription
nameStringRequiredFirst name, or last name, or full name.

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis.Alphabets
idStringUnique identifier.
nameStringThe provided full name.
scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
countryStringMost likely country of origin, in ISO 3166-1 alpha-2 format.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/country/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",
  "name": "Keith Haring",
  "score": 14.474855749439138,
  "country": "US",
  "countryAlt": "NZ",
  "region": "Northern America",
  "topRegion": "Americas",
  "subRegion": "Northern America",
  "countriesTop": [
    "US",
    "NZ",
    "AU",
    "GB",
    "IE",
    "CA",
    "DE",
    "SG",
    "JM",
    "HK"
  ],
  "probabilityCalibrated": 0.5543051242619337,
  "probabilityAltCalibrated": 0.5722556327291567
}

Name Country code sample for java :

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/country/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",
  "name": "Keith Haring",
  "score": 14.474855749439138,
  "country": "US",
  "countryAlt": "NZ",
  "region": "Northern America",
  "topRegion": "Americas",
  "subRegion": "Northern America",
  "countriesTop": [
    "US",
    "NZ",
    "AU",
    "GB",
    "IE",
    "CA",
    "DE",
    "SG",
    "JM",
    "HK"
  ],
  "probabilityCalibrated": 0.5543051242619337,
  "probabilityAltCalibrated": 0.5722556327291567
}

Name Country code sample for python :

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/country/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",
  "name": "Keith Haring",
  "score": 14.474855749439138,
  "country": "US",
  "countryAlt": "NZ",
  "region": "Northern America",
  "topRegion": "Americas",
  "subRegion": "Northern America",
  "countriesTop": [
    "US",
    "NZ",
    "AU",
    "GB",
    "IE",
    "CA",
    "DE",
    "SG",
    "JM",
    "HK"
  ],
  "probabilityCalibrated": 0.5543051242619337,
  "probabilityAltCalibrated": 0.5722556327291567
}

Name Country code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/country/Keith Haring", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

The above command returns JSON structured like this :

{
  "script": "LATIN",
  "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
  "name": "Keith Haring",
  "score": 14.474855749439138,
  "country": "US",
  "countryAlt": "NZ",
  "region": "Northern America",
  "topRegion": "Americas",
  "subRegion": "Northern America",
  "countriesTop": [
    "US",
    "NZ",
    "AU",
    "GB",
    "IE",
    "CA",
    "DE",
    "SG",
    "JM",
    "HK"
  ],
  "probabilityCalibrated": 0.5543051242619337,
  "probabilityAltCalibrated": 0.5722556327291567
}

Names Corridor

Name Corridor feature analyzes two person's first names, last names, and country codes of their 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 requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/corridorBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

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

The HTTP response body is a nested array "corridorFromTo" of objects.

NameTypeDescriptionEnumerators
corridorFromToArray of objectsA list of classified name pairs..
[{...}].idStringUnique identifier.
[{...}].firstLastNameGeoFromGenderObjectGender data for the sender name..
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringUnique identifier.
{...}.firstNameString.
{...}.lastNameString.
{...}.likelyGenderString.Genders
{...}.genderScaleNumber.
{...}.scoreNumber.
{...}.probabilityCalibratedNumber.
[{...}].firstLastNameGeoToGenderObjectGender data for the receiver name..
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringUnique identifier.
{...}.firstNameString.
{...}.lastNameString.
{...}.likelyGenderString.Genders
{...}.genderScaleNumber.
{...}.scoreNumber.
{...}.probabilityCalibratedNumber.
[{...}].firstLastNameGeoFromOriginObjectOrigin data for the sender name..
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringUnique identifier.
{...}.firstNameString.
{...}.lastNameString.
{...}.countryOriginString.Country of origin
{...}.countryOriginAltString.Country of origin
{...}.countriesOriginTopArray.Country of origin
{...}.scoreNumber.
{...}.regionOriginString.Regions of origin or residence
{...}.topRegionOriginString.Regions of origin or residence
{...}.subRegionOriginString.Sub regions of origin or residence
{...}.probabilityCalibratedNumber.
{...}.probabilityAltCalibratedNumber.
[{...}].firstLastNameGeoToOriginObjectOrigin data for the receiver name..
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringUnique identifier.
{...}.firstNameString.
{...}.lastNameString.
{...}.countryOriginString.Country of origin
{...}.countryOriginAltString.Country of origin
{...}.countriesOriginTopArray.Country of origin
{...}.scoreNumber.
{...}.regionOriginString.Regions of origin or residence
{...}.topRegionOriginString.Regions of origin or residence
{...}.subRegionOriginString.Sub regions of origin or residence
{...}.probabilityCalibratedNumber.
{...}.probabilityAltCalibratedNumber.
[{...}].firstLastNameGeoFromDiasporaObjectDiaspora data for the sender name..
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringUnique identifier.
{...}.firstNameString.
{...}.lastNameString.
{...}.scoreNumber.
{...}.ethnicityAltString.Ethnicities or diasporas
{...}.ethnicityString.Ethnicities or diasporas
{...}.liftedBoolean.
{...}.countryIso2String.Country of residence
{...}.ethnicitiesTopArray.Ethnicities or diasporas
[{...}].firstLastNameGeoToDiasporaObjectDiaspora data for the receiver name..
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringUnique identifier.
{...}.firstNameString.
{...}.lastNameString.
{...}.scoreNumber.
{...}.ethnicityAltString.Ethnicities or diasporas
{...}.ethnicityString.Ethnicities or diasporas
{...}.liftedBoolean.
{...}.countryIso2String.Country of residence
{...}.ethnicitiesTopArray.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 :

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": "{
  "corridorFromTo": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstLastNameGeoFrom": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "countryIso2": "GB"
      },
      "firstLastNameGeoTo": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
        "firstName": "Nicolas",
        "lastName": "Tesla",
        "countryIso2": "US"
      }
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

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

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 requestGET
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

The HTTP response body is an object.

NameTypeDescriptionEnumerators
idStringUnique identifier.
firstLastNameGeoFromGenderObjectGender data for the sender name..
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringUnique identifier.
{...}.firstNameStringFirst name (or given name).
{...}.lastNameStringLast name (or family name).
{...}.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..
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringUnique identifier.
{...}.firstNameStringFirst name (or given name).
{...}.lastNameStringLast name (or family name).
{...}.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..
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringUnique identifier.
{...}.firstNameStringFirst name (or given name).
{...}.lastNameStringLast name (or family 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, but score is not normalized. Use probabilityCalibrated if available.
{...}.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 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..
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringUnique identifier.
{...}.firstNameStringFirst name (or given name).
{...}.lastNameStringLast name (or family 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, but score is not normalized. Use probabilityCalibrated if available.
{...}.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 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..
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringUnique identifier.
{...}.firstNameStringFirst name (or given name).
{...}.lastNameStringLast name (or family name).
{...}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
{...}.ethnicityAltStringSecond most likely ethnicity.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.
{...}.countryIso2StringMost likely country of origin, 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
firstLastNameGeoToDiasporaObjectDiaspora data for the receiver name..
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringUnique identifier.
{...}.firstNameStringFirst name (or given name).
{...}.lastNameStringLast name (or family name).
{...}.scoreNumberHigher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
{...}.ethnicityAltStringSecond most likely ethnicity.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.
{...}.countryIso2StringMost likely country of origin, 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

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 :

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"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

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

Name Country Subclassification

  • Description: Returns the most likely geographic subdivision context of up to 100 first names and last names. Subdivision are either a country's states or regions. At the moment this is only supported for India (ISO 3166-1 alpha-2 code "IN").
  • Cost: 10 credits per name.

HTTP request

http requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/subclassificationBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names.
[{...}].idStringOptionalProvided unique identifier.
[{...}].countryIso2StringRequiredMost likely country of origin, in ISO 3166-1 alpha-2 format.
[{...}].firstNameStringOptionalFirst name, given name, nickname.
[{...}].lastNameStringOptionalLast name, family name, surname.

Response

The HTTP response body is a nested array "personalNames" of objects.

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names with their most likely geographic subdivision context.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].idStringProvided unique identifier.
[{...}].firstNameStringSubmitted first name.
[{...}].lastNameStringSubmitted last name.
[{...}].countryIso2StringSubmitted country of origin, in ISO 3166-1 alpha-2 format.Country of residence
[{...}].subClassificationStringMost likely subclassification, in ISO 3166-2 alpha-2 format (country-region).
[{...}].subClassificationAltStringSecond most likely subclassification, in ISO 3166-2 alpha-2 format (country-region).
[{...}].subclassificationTopArrayTop 10 most likely subclassification, in ISO 3166-2 alpha-2 format (country-region), sorted from most likely to least likely.
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.
[{...}].probabilityCalibratedNumberThe calibrated probability for subClassification to have been guessed correctly. -1 = still calibrating..
[{...}].probabilityAltCalibratedNumberThe calibrated probability for subClassification OR subClassificationAlt to have been guessed correctly. -1 = still calibrating..

Code sample

Name Country Subclassification code sample for shell :

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/subclassificationBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","countryIso2":"IN","firstName":"Jannat","lastName":"Rahmani"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "countryIso2": "IN",
      "firstName": "Jannat",
      "lastName": "Rahmani"
    }
  ]
}

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Jannat",
      "lastName": "Rahmani",
      "countryIso2": "IN",
      "subClassification": "IN-CH",
      "subClassificationAlt": "IN-PY",
      "subclassificationTop": [
        "IN-CH",
        "IN-PY",
        "IN-UP",
        "IN-AN",
        "IN-RJ",
        "IN-JH",
        "IN-KL",
        "IN-BR",
        "IN-DL",
        "IN-UT"
      ],
      "score": 2.5087208339960445,
      "probabilityCalibrated": 0.3684249074494664,
      "probabilityAltCalibrated": 0.4738687735374875
    }
  ]
}

Name Country Subclassification code sample for java :

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

Body parameter:

{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "countryIso2": "IN",
      "firstName": "Jannat",
      "lastName": "Rahmani"
    }
  ]
}

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Jannat",
      "lastName": "Rahmani",
      "countryIso2": "IN",
      "subClassification": "IN-CH",
      "subClassificationAlt": "IN-PY",
      "subclassificationTop": [
        "IN-CH",
        "IN-PY",
        "IN-UP",
        "IN-AN",
        "IN-RJ",
        "IN-JH",
        "IN-KL",
        "IN-BR",
        "IN-DL",
        "IN-UT"
      ],
      "score": 2.5087208339960445,
      "probabilityCalibrated": 0.3684249074494664,
      "probabilityAltCalibrated": 0.4738687735374875
    }
  ]
}

Name Country Subclassification code sample for python :

import requests

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

payload = {
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "countryIso2": "IN",
      "firstName": "Jannat",
      "lastName": "Rahmani"
    }
  ]
}
headers = {
    "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",
      "countryIso2": "IN",
      "firstName": "Jannat",
      "lastName": "Rahmani"
    }
  ]
}

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Jannat",
      "lastName": "Rahmani",
      "countryIso2": "IN",
      "subClassification": "IN-CH",
      "subClassificationAlt": "IN-PY",
      "subclassificationTop": [
        "IN-CH",
        "IN-PY",
        "IN-UP",
        "IN-AN",
        "IN-RJ",
        "IN-JH",
        "IN-KL",
        "IN-BR",
        "IN-DL",
        "IN-UT"
      ],
      "score": 2.5087208339960445,
      "probabilityCalibrated": 0.3684249074494664,
      "probabilityAltCalibrated": 0.4738687735374875
    }
  ]
}

Name Country Subclassification code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/subclassificationBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": "{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "countryIso2": "IN",
      "firstName": "Jannat",
      "lastName": "Rahmani"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Body parameter:

{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "countryIso2": "IN",
      "firstName": "Jannat",
      "lastName": "Rahmani"
    }
  ]
}

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Jannat",
      "lastName": "Rahmani",
      "countryIso2": "IN",
      "subClassification": "IN-CH",
      "subClassificationAlt": "IN-PY",
      "subclassificationTop": [
        "IN-CH",
        "IN-PY",
        "IN-UP",
        "IN-AN",
        "IN-RJ",
        "IN-JH",
        "IN-KL",
        "IN-BR",
        "IN-DL",
        "IN-UT"
      ],
      "score": 2.5087208339960445,
      "probabilityCalibrated": 0.3684249074494664,
      "probabilityAltCalibrated": 0.4738687735374875
    }
  ]
}
info symbol

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 geographic subdivision context of a first name and a last name. Subdivision are either a country's states or regions. At the moment this is only supported for India (ISO 3166-1 alpha-2 code "IN").
  • Cost: 10 credits per name.
  • Test: Name Country Subclassification feature.

HTTP request

http requestGET
https://v2.namsor.com/NamSorAPIv2/api2/json/subclassification/{countryIso2}/{firstName}/{lastName}

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request parameters

NameTypeRequiredDescription
countryIso2StringRequiredMost likely country of origin, in ISO 3166-1 alpha-2 format.
firstNameStringRequiredFirst name, given name, nickname.
lastNameStringRequiredLast name, family name, surname.

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis.Alphabets
idStringProvided unique identifier.
firstNameStringSubmitted first name.
lastNameStringSubmitted last name.
countryIso2StringSubmitted country of origin, in ISO 3166-1 alpha-2 format.Country of residence
subClassificationStringMost likely subclassification, in ISO 3166-2 alpha-2 format (country-region).
subClassificationAltStringSecond most likely subclassification, in ISO 3166-2 alpha-2 format (country-region).
subclassificationTopArrayTop 10 most likely subclassification, in ISO 3166-2 alpha-2 format (country-region), sorted from most likely to least likely.
scoreNumberHigher implies a more reliable result, score is not normalized.
probabilityCalibratedNumberThe calibrated probability for subClassification to have been guessed correctly. -1 = still calibrating..
probabilityAltCalibratedNumberThe calibrated probability for subClassification OR subClassificationAlt to have been guessed correctly. -1 = still calibrating..

Code sample

Name Country Subclassification code sample for shell :

curl --request GET \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/subclassification/IN/Amitabh/Bachchan \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'

The above command returns JSON structured like this :

{
  "script": "LATIN",
  "id": "5dd784f2-d1d3-41b8-bba5-c064a836646b",
  "firstName": "Amitabh",
  "lastName": "Bachchan",
  "countryIso2": "IN",
  "subClassification": "IN-CH",
  "subClassificationAlt": "IN-UT",
  "subclassificationTop": [
    "IN-CH",
    "IN-UT",
    "IN-AN",
    "IN-UP",
    "IN-DL",
    "IN-HR",
    "IN-RJ",
    "IN-HP",
    "IN-BR",
    "IN-KL"
  ],
  "score": 8.02456285165782,
  "probabilityCalibrated": 0.5561082178046067,
  "probabilityAltCalibrated": 0.698831534498132
}

Name Country Subclassification code sample for java :

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

The above command returns JSON structured like this :

{
  "script": "LATIN",
  "id": "5dd784f2-d1d3-41b8-bba5-c064a836646b",
  "firstName": "Amitabh",
  "lastName": "Bachchan",
  "countryIso2": "IN",
  "subClassification": "IN-CH",
  "subClassificationAlt": "IN-UT",
  "subclassificationTop": [
    "IN-CH",
    "IN-UT",
    "IN-AN",
    "IN-UP",
    "IN-DL",
    "IN-HR",
    "IN-RJ",
    "IN-HP",
    "IN-BR",
    "IN-KL"
  ],
  "score": 8.02456285165782,
  "probabilityCalibrated": 0.5561082178046067,
  "probabilityAltCalibrated": 0.698831534498132
}

Name Country Subclassification code sample for python :

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/subclassification/IN/Amitabh/Bachchan"

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": "5dd784f2-d1d3-41b8-bba5-c064a836646b",
  "firstName": "Amitabh",
  "lastName": "Bachchan",
  "countryIso2": "IN",
  "subClassification": "IN-CH",
  "subClassificationAlt": "IN-UT",
  "subclassificationTop": [
    "IN-CH",
    "IN-UT",
    "IN-AN",
    "IN-UP",
    "IN-DL",
    "IN-HR",
    "IN-RJ",
    "IN-HP",
    "IN-BR",
    "IN-KL"
  ],
  "score": 8.02456285165782,
  "probabilityCalibrated": 0.5561082178046067,
  "probabilityAltCalibrated": 0.698831534498132
}

Name Country Subclassification code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/subclassification/IN/Amitabh/Bachchan", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

The above command returns JSON structured like this :

{
  "script": "LATIN",
  "id": "5dd784f2-d1d3-41b8-bba5-c064a836646b",
  "firstName": "Amitabh",
  "lastName": "Bachchan",
  "countryIso2": "IN",
  "subClassification": "IN-CH",
  "subClassificationAlt": "IN-UT",
  "subclassificationTop": [
    "IN-CH",
    "IN-UT",
    "IN-AN",
    "IN-UP",
    "IN-DL",
    "IN-HR",
    "IN-RJ",
    "IN-HP",
    "IN-BR",
    "IN-KL"
  ],
  "score": 8.02456285165782,
  "probabilityCalibrated": 0.5561082178046067,
  "probabilityAltCalibrated": 0.698831534498132
}

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. 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 requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/genderBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names.
[{...}].idStringOptionalUnique identifier.
[{...}].firstNameStringRequiredFirst name, given name, nickname.
[{...}].lastNameStringOptionalLast name, family name, surname.

Response

The HTTP response body is a nested array "personalNames" of objects.

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names genderized.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].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 :

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": "{
  "personalNames": [
    {
      "id": "b590b04c-da23-4f2f-a334-aee384ee420a",
      "firstName": "Keith",
      "lastName": "Haring"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

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

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 requestGET
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

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis.Alphabets
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 :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/gender/Keith/Haring", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

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. 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 requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeoBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

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

The HTTP response body is a nested array "personalNames" of objects.

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names genderized.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].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 :

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": "{
  "personalNames": [
    {
      "id": "27fb45db-eddf-40d0-95c1-de9978a166b0",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

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

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 requestGET
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

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis.Alphabets
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 :

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

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.

Alert symbol

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 requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal full names.
[{...}].idStringOptionalUnique identifier.
[{...}].nameStringRequiredUnsplit full name (first name and last name).

Response

The HTTP response body is a nested array "personalNames" of objects.

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted full names genderized.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].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 :

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": "{
  "personalNames": [
    {
      "id": "0f472330-11a9-49ad-a0f5-bcac90a3f6bf",
      "name": "Keith Haring"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

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

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

HTTP request

http requestGET
https://v2.namsor.com/NamSorAPIv2/api2/json/genderFull/{name}

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request parameters

NameTypeRequiredDescription
nameStringRequiredUnsplit full name (first name and last name).

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis.Alphabets
idStringUnique 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 GET \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderFull/Keith Haring \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'

The above command returns JSON structured like this :

{
  "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.get("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFull/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": "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/genderFull/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": "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 :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFull/Keith Haring", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

The above command returns JSON structured like this :

{
  "script": "LATIN",
  "id": "0f472330-11a9-49ad-a0f5-bcac90a3f6bf",
  "name": "Keith Haring",
  "likelyGender": "male",
  "genderScale": -0.8744219712791637,
  "score": 11.2727995452283,
  "probabilityCalibrated": 0.9372109856395818
}

Genderize Full Name Geo

Genderize Full Name Geo feature analyzes an unsplit full name (first name and last name) based on a country of residence, to identify its most likely gender with improved accuracy than the basic feature Genderize Full Name. The feature returns most likely gender accompanied by a calibrated probability. If the probability of the returned gender is between 45% and 55%, the name can be interpreted as a unisex name.

Alert symbol

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

  • Description: Returns the most likely gender of up to 100 unsplit full names, according to their geographic context.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Genderize Full Name Geo feature.

HTTP request

http requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeoBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

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.

Response

The HTTP response body is a nested array "personalNames" of objects.

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted full names genderized.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].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 Geo code sample for shell :

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeoBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f","name":"Keith Haring","countryIso2":"US"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f",
      "name": "Keith Haring",
      "countryIso2": "US"
    }
  ]
}

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f",
      "name": "Keith Haring",
      "likelyGender": "male",
      "genderScale": -0.8716298606148474,
      "score": 11.225679376737641,
      "probabilityCalibrated": 0.9358149303074237
    }
  ]
}

Genderize Full Name Geo code sample for java :

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeoBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f\",\"name\":\"Keith Haring\",\"countryIso2\":\"US\"}]}")
.asString();

Body parameter:

{
  "personalNames": [
    {
      "id": "3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f",
      "name": "Keith Haring",
      "countryIso2": "US"
    }
  ]
}

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f",
      "name": "Keith Haring",
      "likelyGender": "male",
      "genderScale": -0.8716298606148474,
      "score": 11.225679376737641,
      "probabilityCalibrated": 0.9358149303074237
    }
  ]
}

Genderize Full Name Geo code sample for python :

import requests

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

payload = {
  "personalNames": [
    {
      "id": "3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f",
      "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": "3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f",
      "name": "Keith Haring",
      "countryIso2": "US"
    }
  ]
}

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f",
      "name": "Keith Haring",
      "likelyGender": "male",
      "genderScale": -0.8716298606148474,
      "score": 11.225679376737641,
      "probabilityCalibrated": 0.9358149303074237
    }
  ]
}

Genderize Full Name Geo code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeoBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": "{
  "personalNames": [
    {
      "id": "3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f",
      "name": "Keith Haring",
      "countryIso2": "US"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Body parameter:

{
  "personalNames": [
    {
      "id": "3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f",
      "name": "Keith Haring",
      "countryIso2": "US"
    }
  ]
}

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f",
      "name": "Keith Haring",
      "likelyGender": "male",
      "genderScale": -0.8716298606148474,
      "score": 11.225679376737641,
      "probabilityCalibrated": 0.9358149303074237
    }
  ]
}
info symbol

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 an unsplit full name, according to its geographic context.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Genderize Full Name Geo feature.

HTTP request

http requestGET
https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeo/{name}/{countryIso2}

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request parameters

NameTypeRequiredDescription
nameStringRequiredUnsplit full name (first name and last name).
countryIso2StringRequiredMost likely country of origin, in ISO 3166-1 alpha-2 format.

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis.Alphabets
idStringUnique 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 Geo code sample for shell :

curl --request GET \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeo/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": "3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f",
  "name": "Keith Haring",
  "likelyGender": "male",
  "genderScale": -0.8716298606148474,
  "score": 11.225679376737641,
  "probabilityCalibrated": 0.9358149303074237
}

Genderize Full Name Geo code sample for java :

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeo/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": "3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f",
  "name": "Keith Haring",
  "likelyGender": "male",
  "genderScale": -0.8716298606148474,
  "score": 11.225679376737641,
  "probabilityCalibrated": 0.9358149303074237
}

Genderize Full Name Geo code sample for python :

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeo/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": "3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f",
  "name": "Keith Haring",
  "likelyGender": "male",
  "genderScale": -0.8716298606148474,
  "score": 11.225679376737641,
  "probabilityCalibrated": 0.9358149303074237
}

Genderize Full Name Geo code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeo/Keith Haring/US", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

The above command returns JSON structured like this :

{
  "script": "LATIN",
  "id": "3a2d203a-a6a4-42f9-acd1-1b5c56c7d39f",
  "name": "Keith Haring",
  "likelyGender": "male",
  "genderScale": -0.8716298606148474,
  "score": 11.225679376737641,
  "probabilityCalibrated": 0.9358149303074237
}

Name Type Recognition

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

Name Type

Name Type feature analyzes a proper noun to determine if it's the name of a person (anthroponym), a geographic name (toponym) or the name of a brand. We recommend that you submit the entire name (full name) if applicable.

  • Description: Returns the type of up to 100 submitted proper nouns. Ex: John Smith = personal name, Namsor = brand name.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Name Type feature.

HTTP request

http requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

NameTypeRequiredDescription
properNounsArray of objectsRequiredA list of proper names.
[{...}].idStringOptionalUnique identifier.
[{...}].nameStringRequiredA proper noun (person, brand, etc.).

Response

The HTTP response body is a nested array "properNouns" of objects.

NameTypeDescriptionEnumerators
properNounsArray of objectsA list of commonTypeized names..
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].idStringProvided unique identifier.
[{...}].nameStringSubmitted proper noun.
[{...}].commonTypeStringMost likely type of the proper noun.Name categories
[{...}].commonTypeAltStringSecond most likely type of the proper noun.Name categories
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.

Code sample

Name Type code sample for shell :

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"properNouns":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","name":"Zippo"}]}'

Body parameter:

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

The above command returns JSON structured like this :

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

Name Type code sample for java :

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

Body parameter:

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

The above command returns JSON structured like this :

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

Name Type code sample for python :

import requests

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

payload = {
  "properNouns": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "Zippo"
    }
  ]
}
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:

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

The above command returns JSON structured like this :

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

Name Type code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": "{
  "properNouns": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "Zippo"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Body parameter:

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

The above command returns JSON structured like this :

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

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 type of a submitted proper noun. Ex: John Smith = personal name, Namsor = brand name.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Name Type feature.

HTTP request

http requestGET
https://v2.namsor.com/NamSorAPIv2/api2/json/nameType/{name}

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request parameters

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

Response

The HTTP response body is an object.

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

Code sample

Name Type code sample for shell :

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

The above command returns JSON structured like this :

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

Name Type code sample for java :

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

The above command returns JSON structured like this :

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

Name Type code sample for python :

import requests

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

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": "a88b1bf1-56f1-40d3-84db-4daf57121b1d",
  "name": "Zippo",
  "commonType": "brand-name",
  "commonTypeAlt": "toponym",
  "score": 7.717552234146745
}

Name Type code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/nameType/Zippo", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

The above command returns JSON structured like this :

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

Name Type Geo

Name Type feature analyzes a proper noun based on a local context to determine if it's the name of a person (anthroponym), a geographic name (toponym) or the name of a brand, with improved accuracy than the basic feature Name Type.

  • Description: Returns the type of up to 100 submitted proper nouns using their geographic context. Ex: John Smith = personal name, Namsor = brand name.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Name Type Geo feature.

HTTP request

http requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeGeoBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

NameTypeRequiredDescription
properNounsArray of objectsRequiredA list of proper names.
[{...}].idStringOptionalUnique identifier.
[{...}].nameStringRequiredA proper noun (person, brand, etc.).
[{...}].countryIso2StringRequiredMost likely country of origin, in ISO 3166-1 alpha-2 format.

Response

The HTTP response body is a nested array "properNouns" of objects.

NameTypeDescriptionEnumerators
properNounsArray of objectsA list of commonTypeized names..
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].idStringProvided unique identifier.
[{...}].nameStringSubmitted proper noun.
[{...}].commonTypeStringMost likely type of the proper noun.Name categories
[{...}].commonTypeAltStringSecond most likely type of the proper noun.Name categories
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.

Code sample

Name Type Geo code sample for shell :

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeGeoBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"properNouns":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","name":"Edi Gathegi","countryIso2":"KE"}]}'

Body parameter:

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

The above command returns JSON structured like this :

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

Name Type Geo code sample for java :

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

Body parameter:

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

The above command returns JSON structured like this :

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

Name Type Geo code sample for python :

import requests

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

payload = {
  "properNouns": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "Edi Gathegi",
      "countryIso2": "KE"
    }
  ]
}
headers = {
    "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:

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

The above command returns JSON structured like this :

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

Name Type Geo code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeGeoBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": "{
  "properNouns": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "Edi Gathegi",
      "countryIso2": "KE"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Body parameter:

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

The above command returns JSON structured like this :

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

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 type of up to 100 submitted proper nouns using its geographic context. Ex: John Smith = personal name, Namsor = brand name.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Name Type Geo feature.

HTTP request

http requestGET
https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeGeo/{name}/{countryIso2}

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request parameters

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

Response

The HTTP response body is an object.

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

Code sample

Name Type Geo code sample for shell :

curl --request GET \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeGeo/Edi Gathegi/KE \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'

The above command returns JSON structured like this :

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

Name Type Geo code sample for java :

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

The above command returns JSON structured like this :

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

Name Type Geo code sample for python :

import requests

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

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": "a941ea3f-3b3c-4ff1-af28-c01b086b7d79",
  "name": "Edi Gathegi",
  "commonType": "anthroponym",
  "commonTypeAlt": "brand-name",
  "score": 18.5790039224226
}

Name Type Geo code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/nameTypeGeo/Edi Gathegi/KE", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

The above command returns JSON structured like this :

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

Split names

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

Split Name

Split Name feature identifies the first name and the last name from an unsplit full name. The Split Name Geo feature helps improve accuracy when splitting the full name by adding a country of residence.

  • Description: Returns the most likely first name and last name structure of up to 100 full names.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Split Name feature.

HTTP request

http requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/parseNameBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of unsplit full names.
[{...}].idStringOptionalUnique identifier.
[{...}].nameStringRequiredFull name (first name and last name).

Response

The HTTP response body is a nested array "personalNames" of objects.

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names separated into first name and last name structure.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].idStringProvided unique identifier.
[{...}].nameStringSubmitted full name.
[{...}].nameParserTypeStringMost likely structure of the name.Name structures
[{...}].nameParserTypeAltStringSecond most likely structure of the name.Name structures
[{...}].firstLastNameObjectSplit name.
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringProvided unique identifier.
{...}.firstNameStringFirst name (or given name).
{...}.lastNameStringLast name (or family name).
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.

Code sample

Split Name code sample for shell :

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/parseNameBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","name":"John Smith"}]}'

Body parameter:

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

The above command returns JSON structured like this :

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

Split Name code sample for java :

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

Body parameter:

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

The above command returns JSON structured like this :

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

Split Name code sample for python :

import requests

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

payload = {
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "John Smith"
    }
  ]
}
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": "John Smith"
    }
  ]
}

The above command returns JSON structured like this :

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

Split Name code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/parseNameBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": "{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "John Smith"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Body parameter:

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

The above command returns JSON structured like this :

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

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 first name and last name structure of a full name.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Split Name feature.

HTTP request

http requestGET
https://v2.namsor.com/NamSorAPIv2/api2/json/parseName/{name}

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request parameters

NameTypeRequiredDescription
nameStringRequiredFull name (first name and last name).

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis.Alphabets
idStringProvided unique identifier.
nameStringSubmitted full name.
nameParserTypeStringMost likely structure of the name.Name structures
nameParserTypeAltStringSecond most likely structure of the name.Name structures
firstLastNameObjectSplit name.
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringProvided unique identifier.
{...}.firstNameStringFirst name (or given name).
{...}.lastNameStringLast name (or family name).
scoreNumberHigher implies a more reliable result, score is not normalized.

Code sample

Split Name code sample for shell :

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

The above command returns JSON structured like this :

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

Split Name code sample for java :

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

The above command returns JSON structured like this :

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

Split Name code sample for python :

import requests

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

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": "3fb36d3d-f9cd-4ccc-a348-38d9e5b5232d",
  "name": "John Smith",
  "nameParserType": "FN1LN1",
  "nameParserTypeAlt": null,
  "firstLastName": {
    "script": null,
    "id": null,
    "firstName": "John",
    "lastName": "Smith"
  },
  "score": 23.313692197779005
}

Split Name code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/parseName/John Smith", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

The above command returns JSON structured like this :

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

Split Name Geo

Split Name Geo feature processes an unsplit full name with a country of residence to identify the first name and the last name, with improved accuracy than the basic feature Split Name.

  • Description: Returns the most likely first name and last name structure of up to 100 full names using their geographic context.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Split Name Geo feature.

HTTP request

http requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/parseNameGeoBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of unsplit full names with their country of residence.
[{...}].idStringOptionalUnique identifier.
[{...}].nameStringRequiredFull name (first name and last name).
[{...}].countryIso2StringRequiredMost likely country of origin, in ISO 3166-1 alpha-2 format.

Response

The HTTP response body is a nested array "personalNames" of objects.

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names separated into first name and last name structure.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].idStringProvided unique identifier.
[{...}].nameStringSubmitted full name.
[{...}].nameParserTypeStringMost likely structure of the name.Name structures
[{...}].nameParserTypeAltStringSecond most likely structure of the name.Name structures
[{...}].firstLastNameObjectSplit name.
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringProvided unique identifier.
{...}.firstNameStringFirst name (or given name).
{...}.lastNameStringLast name (or family name).
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.

Code sample

Split Name Geo code sample for shell :

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/parseNameGeoBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","name":"Ricardo Darín","countryIso2":"AR"}]}'

Body parameter:

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

The above command returns JSON structured like this :

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

Split Name Geo code sample for java :

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

Body parameter:

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

The above command returns JSON structured like this :

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

Split Name Geo code sample for python :

import requests

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

payload = {
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "Ricardo Darín",
      "countryIso2": "AR"
    }
  ]
}
headers = {
    "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": "Ricardo Darín",
      "countryIso2": "AR"
    }
  ]
}

The above command returns JSON structured like this :

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

Split Name Geo code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/parseNameGeoBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": "{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "Ricardo Darín",
      "countryIso2": "AR"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Body parameter:

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

The above command returns JSON structured like this :

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

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 first name and last name structure of a full name using its geographic context.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Split Name Geo feature.

HTTP request

http requestGET
https://v2.namsor.com/NamSorAPIv2/api2/json/parseName/{name}/{countryIso2}

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request parameters

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

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis.Alphabets
idStringProvided unique identifier.
nameStringSubmitted full name.
nameParserTypeStringMost likely structure of the name.Name structures
nameParserTypeAltStringSecond most likely structure of the name.Name structures
firstLastNameObjectSplit name.
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringProvided unique identifier.
{...}.firstNameStringFirst name (or given name).
{...}.lastNameStringLast name (or family name).
scoreNumberHigher implies a more reliable result, score is not normalized.

Code sample

Split Name Geo code sample for shell :

curl --request GET \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/parseName/Ricardo Darín/AR \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'

The above command returns JSON structured like this :

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

Split Name Geo code sample for java :

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/parseName/Ricardo Darín/AR")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.asString();

The above command returns JSON structured like this :

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

Split Name Geo code sample for python :

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/parseName/Ricardo Darín/AR"

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": "dbe186ee-cfd6-48e0-a449-00c70df61ec3",
  "name": "Ricardo Darín",
  "nameParserType": "FN1LN1",
  "nameParserTypeAlt": "FN1LN2",
  "firstLastName": {
    "script": null,
    "id": null,
    "firstName": "Ricardo",
    "lastName": "Darín"
  },
  "score": 3.4476222927492017
}

Split Name Geo code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/parseName/Ricardo Darín/AR", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

The above command returns JSON structured like this :

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

Japanese names

Namsor provides a specialized name processing API dedicated to analysing names in the Japanese language. We have developed a name converter, focused on Japanese names, to help you find the best transcriptions possible. With our API, you can convert Japanese names both ways between Kanji and English. You can evaluate the quality of a transcriptions between a name in Kanji and a name in Latin characters. It is also possible to split Japansese full names, in either Kanji or Latin characters, into a first name and a last name as well as establish the gender of a name.

Translate Japanese Name To Latin

Translate Japanese Name To Latin feature converts a Japanese first name or a Japanese last name (or both for more precision) written in Kanji characters, into Latin alphabet. The conversion of a Japanese name written in Kanji into Latin alphabet is called romanization. Several conversions for the same name are possible. This is why the feature returns a list of converted names, accompanied by a calibrated probability and sorted from most likely to least likely.

  • Description: Returns the most likely latin transcriptions for up to 100 Japanese first names and/or last names in Kanji characters.
  • Cost: 1 credit per name.
  • Test: Translate Japanese Name To Latin feature.

HTTP request

http requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameLatinCandidatesBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal Japanese names in Kanji characters.
[{...}].idStringOptionalUnique identifier.
[{...}].firstNameStringOptionalJapanese first name (or given name) in Kanji.
[{...}].lastNameStringOptionalJapanese last name (or family name) in Kanji.

Response

The HTTP response body is a nested array "namesAndMatchCandidates" of objects.

NameTypeDescriptionEnumerators
namesAndMatchCandidatesArray of objectsList of submitted names converted to Latin alphabet.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].idStringProvided unique identifier.
[{...}].firstNameStringSubmitted first name.
[{...}].lastNameStringSubmitted last name.
[{...}].orderOptionStringSorting order for matchCandidates.
[{...}].matchCandidatesArray of objectsList of possible transcriptions for the submitted name.
[{...}].candidateNameStringInferred transcription of the submitted name to Latin alphabet.
[{...}].probabilityNumberHigher implies a more reliable result, ranges from 0 to 1.
[{...}].predScoreGivenNameNumberHigher implies a more reliable result (for given name or first name).
[{...}].predScoreFamilyNameNumberHigher implies a more reliable result (for family name or last name).

Code sample

Translate Japanese Name To Latin code sample for shell :

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameLatinCandidatesBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"塩田","lastName":"千春"}]}'

Body parameter:

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

The above command returns JSON structured like this :

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

Translate Japanese Name To Latin code sample for java :

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

Body parameter:

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

The above command returns JSON structured like this :

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

Translate Japanese Name To Latin code sample for python :

import requests

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

payload = {
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "塩田",
      "lastName": "千春"
    }
  ]
}
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": "塩田",
      "lastName": "千春"
    }
  ]
}

The above command returns JSON structured like this :

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

Translate Japanese Name To Latin code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameLatinCandidatesBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": "{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "塩田",
      "lastName": "千春"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Body parameter:

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

The above command returns JSON structured like this :

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

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 latin transcriptions (romanization) for a Japanese first name and/or last name in Kanji characters.
  • Cost: 1 credit per name.
  • Test: Translate Japanese Name To Latin feature.

HTTP request

http requestGET
https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameLatinCandidates/{lastName}/{firstName}

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request parameters

NameTypeRequiredDescription
lastNameStringRequiredJapanese last name (or family name) in Kanji.
firstNameStringRequiredJapanese first name (or given name) in Kanji.

Response

The HTTP response body is an object.

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

Code sample

Translate Japanese Name To Latin code sample for shell :

curl --request GET \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameLatinCandidates/千春/塩田 \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'

The above command returns JSON structured like this :

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

Translate Japanese Name To Latin code sample for java :

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

The above command returns JSON structured like this :

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

Translate Japanese Name To Latin code sample for python :

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameLatinCandidates/千春/塩田"

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

Translate Japanese Name To Latin code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameLatinCandidates/千春/塩田", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

The above command returns JSON structured like this :

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

Translate Japanese Name To Kanji

Translate Japanese Name To Kanji feature transcribes a Japanese first name or a Japanese last name (or both for more precision) written in Latin alphabet, into Kanji characters. The conversion of a Japanese name written in Kanji into Latin alphabet is called romanization. Several transcriptions for the same name are possible. This is why the feature returns a list of transcribed names, accompanied by a calibrated probability and sorted from most likely to least likely.

Alert symbol

The name transcription will work with greater accuracy for names identified as Japanese.

  • Description: Returns the most likely Kanji transcriptions for up to 100 Japanese first names and/or last names in Latin alphabet (romanized).
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Translate Japanese Name To Kanji feature.

HTTP request

http requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidatesBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal Japanese names in Latin alphabet.
[{...}].idStringOptionalUnique identifier.
[{...}].firstNameStringOptionalJapanese first name (or given name) in Latin.
[{...}].lastNameStringOptionalJapanese last name (or family name) in Latin.

Response

The HTTP response body is a nested array "namesAndMatchCandidates" of objects.

NameTypeDescriptionEnumerators
namesAndMatchCandidatesArray of objectsList of submitted names converted to Kanji characters.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].idStringProvided unique identifier.
[{...}].firstNameStringSubmitted first name.
[{...}].lastNameStringSubmitted last name.
[{...}].orderOptionStringSorting order for matchCandidates.
[{...}].matchCandidatesArray of objectsList of possible transcriptions for the submitted name.
[{...}].candidateNameStringInferred transcription of the submitted name to Kanji.
[{...}].probabilityNumberHigher implies a more reliable result, ranges from 0 to 1.
[{...}].predScoreGivenNameNumberHigher implies a more reliable result (for given name or first name).
[{...}].predScoreFamilyNameNumberHigher implies a more reliable result (for family name or last name).

Code sample

Translate Japanese Name To Kanji code sample for shell :

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidatesBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Sanae","lastName":"Yamamoto"}]}'

Body parameter:

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

The above command returns JSON structured like this :

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

Translate Japanese Name To Kanji code sample for java :

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

Body parameter:

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

The above command returns JSON structured like this :

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

Translate Japanese Name To Kanji code sample for python :

import requests

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

payload = {
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Sanae",
      "lastName": "Yamamoto"
    }
  ]
}
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": "Sanae",
      "lastName": "Yamamoto"
    }
  ]
}

The above command returns JSON structured like this :

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

Translate Japanese Name To Kanji code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidatesBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": "{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Sanae",
      "lastName": "Yamamoto"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Body parameter:

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

The above command returns JSON structured like this :

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

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 Kanji transcriptions for a Japanese first name and/or last name in Latin alphabet (romanized).
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Translate Japanese Name To Kanji feature.

HTTP request

http requestGET
https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidates/{lastName}/{firstName}

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request parameters

NameTypeRequiredDescription
lastNameStringRequiredJapanese last name (or family name) in Latin.
firstNameStringRequiredJapanese first name (or given name) in Latin.

Response

The HTTP response body is an object.

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

Code sample

Translate Japanese Name To Kanji code sample for shell :

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

The above command returns JSON structured like this :

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

Translate Japanese Name To Kanji code sample for java :

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

The above command returns JSON structured like this :

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

Translate Japanese Name To Kanji code sample for python :

import requests

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

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": null,
  "firstName": "Sanae",
  "lastName": "Yamamoto",
  "orderOption": "OrderScoreSquareFNLN",
  "matchCandidates": [
    {
      "candidateName": "山本 早苗",
      "probability": 0.5000000000000001,
      "predScoreGivenName": -0.03954087197780609,
      "predScoreFamilyName": -0.014371121302247047
    },
    {
      "candidateName": "山本 沙苗",
      "probability": 0.25000000000000006,
      "predScoreGivenName": -5.180787086486816,
      "predScoreFamilyName": -0.014371121302247047
    }
  ]
}

Translate Japanese Name To Kanji code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidates/Yamamoto/Sanae", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

The above command returns JSON structured like this :

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

Translate Japanese Name To Kanji Gender

Translate Japanese Name To Kanji Gender feature transcribes a Japanese first name or a Japanese last name (or both) written in Latin alphabet, into Kanji characters. This feature is based on gender to improved accuracy of the transcription than the basic feature Translate Japanese Name To Kanji. The feature returns a list of the most likely transcribed names accompanied by a calibrated probability and sorted from most likely to least likely.

Alert symbol

The name transcription will work with greater accuracy for names identified as Japanese.

  • Description: Returns the most likely Kanji transcriptions for up to 100 Japanese first names and/or last names in Latin alphabet, according to their gender.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Translate Japanese Name To Kanji Gender feature.

HTTP request

http requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameGenderKanjiCandidatesBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal Japanese names in Latin alphabet and their known gender.
[{...}].idStringOptionalUnique identifier.
[{...}].firstNameStringOptionalJapanese first name (or given name) in Latin.
[{...}].lastNameStringOptionalJapanese last name (or family name) in Latin.
[{...}].genderStringRequiredMost likely gender (female, or male).

Response

The HTTP response body is a nested array "namesAndMatchCandidates" of objects.

NameTypeDescriptionEnumerators
namesAndMatchCandidatesArray of objectsList of submitted names converted to Kanji characters.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].idStringProvided unique identifier.
[{...}].firstNameStringSubmitted first name.
[{...}].lastNameStringSubmitted last name.
[{...}].orderOptionStringSorting order for matchCandidates.
[{...}].matchCandidatesArray of objectsList of possible transcriptions for the submitted name.
[{...}].candidateNameStringInferred transcription of the submitted name to Kanji.
[{...}].probabilityNumberHigher implies a more reliable result, ranges from 0 to 1.
[{...}].predScoreGivenNameNumberHigher implies a more reliable result (for given name or first name).
[{...}].predScoreFamilyNameNumberHigher implies a more reliable result (for family name or last name).

Code sample

Translate Japanese Name To Kanji Gender code sample for shell :

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameGenderKanjiCandidatesBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Takashi","lastName":"Murakami","gender":"male"}]}'

Body parameter:

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

The above command returns JSON structured like this :

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

Translate Japanese Name To Kanji Gender code sample for java :

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

Body parameter:

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

The above command returns JSON structured like this :

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

Translate Japanese Name To Kanji Gender code sample for python :

import requests

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

payload = {
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Takashi",
      "lastName": "Murakami",
      "gender": "male"
    }
  ]
}
headers = {
    "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": "Takashi",
      "lastName": "Murakami",
      "gender": "male"
    }
  ]
}

The above command returns JSON structured like this :

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

Translate Japanese Name To Kanji Gender code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameGenderKanjiCandidatesBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": "{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Takashi",
      "lastName": "Murakami",
      "gender": "male"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Body parameter:

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

The above command returns JSON structured like this :

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

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 Kanji transcriptions for a Japanese first name and/or last name in Latin alphabet (romanized), according to their gender.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Translate Japanese Name To Kanji Gender feature.

HTTP request

http requestGET
https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidates/{lastName}/{firstName}/{gender}

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request parameters

NameTypeRequiredDescription
lastNameStringRequiredJapanese last name (or family name) in Latin.
firstNameStringRequiredJapanese first name (or given name) in Latin.
genderStringRequiredMost likely gender (female, or male).

Response

The HTTP response body is an object.

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

Code sample

Translate Japanese Name To Kanji Gender code sample for shell :

curl --request GET \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidates/Yamamoto/Sanae/male \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'

The above command returns JSON structured like this :

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

Translate Japanese Name To Kanji Gender code sample for java :

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

The above command returns JSON structured like this :

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

Translate Japanese Name To Kanji Gender code sample for python :

import requests

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

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": null,
  "firstName": "Sanae",
  "lastName": "Yamamoto",
  "orderOption": "OrderScoreSquareFNLN",
  "matchCandidates": [
    {
      "candidateName": "山本 早苗",
      "probability": 0.5000000000000001,
      "predScoreGivenName": -0.031474947929382324,
      "predScoreFamilyName": -0.014371121302247047
    },
    {
      "candidateName": "山本 佐苗",
      "probability": 0.25000000000000006,
      "predScoreGivenName": -4.911670207977295,
      "predScoreFamilyName": -0.014371121302247047
    }
  ]
}

Translate Japanese Name To Kanji Gender code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameKanjiCandidates/Yamamoto/Sanae/male", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

The above command returns JSON structured like this :

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

Match Japanese Name

Match Japanese Name feature assesses and grades the quality of a transcription between a Japanese name in Latin characters and a Japanese name in Kanji. The feature returns the status of the match, and scores the names transcription.

  • Description: Matches up to 100 full names in Kanji against corresponding family names and given names in Latin alphabet.
  • Cost: 1 credit per name.
  • Test: Match Japanese Name feature.

HTTP request

http requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameMatchBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal Japanese names in Kanji characters and in Latin aplhabet.
[{...}].idStringOptionalUnique identifier.
[{...}].name1ObjectRequired.
{...}.idStringOptionalUnique identifier.
{...}.firstNameStringRequiredJapanese first name (or given name) in Latin alphabet.
{...}.lastNameStringRequiredJapanese last name (or family name) in Latin alphabet.
[{...}].name2ObjectRequired.
{...}.idStringOptionalUnique identifier.
{...}.nameStringRequiredJapanese full name (family name and given name) in Kanji.

Response

The HTTP response body is a nested array "matchedNames" of objects.

NameTypeDescriptionEnumerators
matchedNamesArray of objectsList of submitted Japanese names with the status of their transcription.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].idStringProvided unique identifier.
[{...}].matchStatusStringSuccess status of the match.Match status
[{...}].scoreNumberHigher implies a better match, score is not normalized.

Code sample

Match Japanese Name code sample for shell :

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

Body parameter:

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

The above command returns JSON structured like this :

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

Match Japanese Name code sample for java :

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

Body parameter:

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

The above command returns JSON structured like this :

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

Match Japanese Name code sample for python :

import requests

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

payload = {
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
      "name1": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
        "firstName": "Tessai",
        "lastName": "Tomioka"
      },
      "name2": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
        "name": "富岡 鉄斎"
      }
    }
  ]
}
headers = {
    "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-648aa8a21c41",
      "name1": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
        "firstName": "Tessai",
        "lastName": "Tomioka"
      },
      "name2": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
        "name": "富岡 鉄斎"
      }
    }
  ]
}

The above command returns JSON structured like this :

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

Match Japanese Name code sample for javascript :

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

Body parameter:

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

The above command returns JSON structured like this :

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

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: Matches a full name in Kanji against a family name and a given name in Latin alphabet.
  • Cost: 1 credit per name.
  • Test: Match Japanese Name feature.

HTTP request

http requestGET
https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameMatch/{lastName}/{firstName}/{name}

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request parameters

NameTypeRequiredDescription
lastNameStringRequiredJapanese last name (or family name) in Latin alphabet.
firstNameStringRequiredJapanese first name (or given name) in Latin alphabet.
nameStringRequiredJapanese full name (family name and given name) in Kanji.

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis.Alphabets
idStringUnique identifier.
matchStatusStringSuccess status of the match.Match status
scoreNumberHigher implies a better match, score is not normalized.

Code sample

Match Japanese Name code sample for shell :

curl --request GET \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameMatch/Tomioka/Tessai/富岡 鉄斎 \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'

The above command returns JSON structured like this :

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

Match Japanese Name code sample for java :

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameMatch/Tomioka/Tessai/富岡 鉄斎")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.asString();

The above command returns JSON structured like this :

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

Match Japanese Name code sample for python :

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameMatch/Tomioka/Tessai/富岡 鉄斎"

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": null,
  "id": null,
  "matchStatus": "Match",
  "score": 1.002224089213585
}

Match Japanese Name code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/japaneseNameMatch/Tomioka/Tessai/富岡 鉄斎", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

The above command returns JSON structured like this :

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

Genderize Japanese Name

Genderize Japanese Name feature accurately identifies the gender of a Japanese first name and a Japanese last name (optional), written in Kanji or in Latin alphabet, with slightly improved accuracy than the Genderize Japanese Full Name feature. The feature returns the most likely gender accompanied by a calibrated probability. If the probability of the returned gender is between 45% and 55%, the name can be interpreted as a gender neutral name.

  • Description: Returns the most likely gender of up to 100 Japanese first names and last names (optional) in Latin alphabet or in Kanji characters.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Genderize Japanese Name feature.

HTTP request

http requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of Japanese names.
[{...}].idStringOptionalUnique identifier.
[{...}].firstNameStringRequiredJapanese first name (given name) in Latin or Kanji characters.
[{...}].lastNameStringOptionalJapanese last name (surname) in Latin or Kanji characters.

Response

The HTTP response body is a nested array "personalNames" of objects.

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted Japanese names genderized.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].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 Japanese Name code sample for shell :

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Satoshi","lastName":"Nakamoto"}]}'

Body parameter:

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

The above command returns JSON structured like this :

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

Genderize Japanese Name code sample for java :

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

Body parameter:

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

The above command returns JSON structured like this :

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

Genderize Japanese Name code sample for python :

import requests

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

payload = {
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Satoshi",
      "lastName": "Nakamoto"
    }
  ]
}
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": "Satoshi",
      "lastName": "Nakamoto"
    }
  ]
}

The above command returns JSON structured like this :

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

Genderize Japanese Name code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": "{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Satoshi",
      "lastName": "Nakamoto"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Body parameter:

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

The above command returns JSON structured like this :

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

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 Japanese first name and a last name in Latin alphabet or in Kanji characters.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Genderize Japanese Name feature.

HTTP request

http requestGET
https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseName/{lastName}/{firstName}

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request parameters

NameTypeRequiredDescription
lastNameStringRequiredJapanese last name (surname) in Latin or Kanji characters.
firstNameStringRequiredJapanese first name (given name) in Latin or Kanji characters.

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis.Alphabets
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 Japanese Name code sample for shell :

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

The above command returns JSON structured like this :

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

Genderize Japanese Name code sample for java :

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

The above command returns JSON structured like this :

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

Genderize Japanese Name code sample for python :

import requests

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

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": "9cfd8321-0924-4570-a4b7-29a611ce5089",
  "firstName": "Satoshi",
  "lastName": "Nakamoto",
  "likelyGender": "male",
  "genderScale": -0.9828731991489774,
  "score": 24.94061932678776,
  "probabilityCalibrated": 0.9914365995744887
}

Genderize Japanese Name code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseName/Nakamoto/Satoshi", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

The above command returns JSON structured like this :

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

Genderize Japanese Full Name

Genderize Japanese Full Name feature accurately identifies the gender of an unsplit Japanese full name (last and first name) written in Kanji characters. The feature returns most likely gender accompanied by a calibrated probability. If the probability of the returned gender is between 45% and 55%, the name can be interpreted as a unisex name.

Alert symbol

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

  • Description: Returns the most likely gender of up to 100 unsplit Japanese full names (surnames and given names), written in Kanji characters or in Latin alphabet.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Genderize Japanese Full Name feature.

HTTP request

http requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFullBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of Japanese full names.
[{...}].idStringOptionalUnique identifier.
[{...}].nameStringRequiredUnsplit Japanese full name (last name and first name) in Kanji or Latin alphabet.

Response

The HTTP response body is a nested array "personalNames" of objects.

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted Japanese full names genderized.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].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 Japanese Full Name code sample for shell :

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFullBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","name":"中松 義郎"}]}'

Body parameter:

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

The above command returns JSON structured like this :

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

Genderize Japanese Full Name code sample for java :

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

Body parameter:

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

The above command returns JSON structured like this :

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

Genderize Japanese Full Name code sample for python :

import requests

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

payload = {
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "中松 義郎"
    }
  ]
}
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": "中松 義郎"
    }
  ]
}

The above command returns JSON structured like this :

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

Genderize Japanese Full Name code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFullBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": "{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "中松 義郎"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Body parameter:

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

The above command returns JSON structured like this :

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

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 an unsplit Japanese full name (surname and given name), written in Kanji characters or in Latin alphabet.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Genderize Japanese Full Name feature.

HTTP request

http requestGET
https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFull/{name}

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request parameters

NameTypeRequiredDescription
nameStringRequiredUnsplit Japanese full name (last name and first name) in Kanji or Latin alphabet.

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis.Alphabets
idStringUnique 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 Japanese Full Name code sample for shell :

curl --request GET \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFull/中松 義郎 \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'

The above command returns JSON structured like this :

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

Genderize Japanese Full Name code sample for java :

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

The above command returns JSON structured like this :

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

Genderize Japanese Full Name code sample for python :

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFull/中松 義郎"

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": "HAN",
  "id": "36990426-d289-43b3-99dc-50ccfe2e5ade",
  "name": "中松 義郎",
  "likelyGender": "male",
  "genderScale": -0.22231473979961303,
  "score": 3.72410721464353,
  "probabilityCalibrated": 0.6111573698998065
}

Genderize Japanese Full Name code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFull/中松 義郎", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

The above command returns JSON structured like this :

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

Split Japanese Name

Split Japanese Name feature accurately identifies the first name and the last name from an unsplit Japanese full name written in Latin alphabet or in Kanji characters.

  • Description: Returns the most likely first name and last name structure of up to 100 full names (family names and given names) in Kanji or Latin alphabet.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Split Japanese Name feature.

HTTP request

http requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/parseJapaneseNameBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of Japanese unsplit full names.
[{...}].idStringOptionalUnique identifier.
[{...}].nameStringRequiredJapanese full name (last name and first name) in Kanji or Latin alphabet.

Response

The HTTP response body is a nested array "personalNames" of objects.

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted Japanese names separated into first name and last name structure.
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].idStringProvided unique identifier.
[{...}].nameStringSubmitted full name.
[{...}].nameParserTypeStringMost likely structure of the name.Name structures
[{...}].nameParserTypeAltStringSecond most likely structure of the name.Name structures
[{...}].firstLastNameObjectSplit name.
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringProvided unique identifier.
{...}.firstNameStringFirst name (or given name).
{...}.lastNameStringLast name (or family name).
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.

Code sample

Split Japanese Name code sample for shell :

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/parseJapaneseNameBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","name":"小島 秀夫"}]}'

Body parameter:

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

The above command returns JSON structured like this :

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

Split Japanese Name code sample for java :

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

Body parameter:

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

The above command returns JSON structured like this :

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

Split Japanese Name code sample for python :

import requests

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

payload = {
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "小島 秀夫"
    }
  ]
}
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": "小島 秀夫"
    }
  ]
}

The above command returns JSON structured like this :

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

Split Japanese Name code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/parseJapaneseNameBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": "{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "小島 秀夫"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Body parameter:

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

The above command returns JSON structured like this :

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

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 first name and last name structure of a full name (family name and given name) in Kanji or Latin alphabet.
  • Precision:Precision gauge
  • Cost: 1 credit per name.
  • Test: Split Japanese Name feature.

HTTP request

http requestGET
https://v2.namsor.com/NamSorAPIv2/api2/json/parseJapaneseName/{name}

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request parameters

NameTypeRequiredDescription
nameStringRequiredJapanese full name (last name and first name) in Kanji or Latin alphabet.

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis.Alphabets
idStringProvided unique identifier.
nameStringSubmitted full name.
nameParserTypeStringMost likely structure of the name.Name structures
nameParserTypeAltStringSecond most likely structure of the name.Name structures
firstLastNameObjectSplit name.
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringProvided unique identifier.
{...}.firstNameStringFirst name (or given name).
{...}.lastNameStringLast name (or family name).
scoreNumberHigher implies a more reliable result, score is not normalized.

Code sample

Split Japanese Name code sample for shell :

curl --request GET \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/parseJapaneseName/小島 秀夫 \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'

The above command returns JSON structured like this :

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

Split Japanese Name code sample for java :

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

The above command returns JSON structured like this :

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

Split Japanese Name code sample for python :

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/parseJapaneseName/小島 秀夫"

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

Split Japanese Name code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/parseJapaneseName/小島 秀夫", {
  "method": "GET",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json"
  }
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

The above command returns JSON structured like this :

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

Chinese names

Namsor provides dedicated name analysis API for the processing of Chinese names. Our name recognition AI can translate Chinese names to English (Pinyin). Among other features you can: infer the gender of a Chinese name or split a Chinese full name into a first name and a last name. We are also able to rate the quality of a transcriptions between a name in Pinyin and a name in Standard Mandarin Chinese.

Translate Chinese Name To Pinyin

Translate Chinese Name To Pinyin feature transcribes a Chinese full name written in standard Mandarin Chinese, into Pinyin (Latin alphabet). Pinyin is used to depict Mandarin logograms with the Latin alphabet, used by languages such as English.

Alert symbol

The name transcription in Pinyin will only work with a Chinese full name (last name and first name).

  • Description: Returns the most likely Pinyin transcription of up to 100 Chinese full names (last name and first name) in Standard Mandarin Chinese.
  • Cost: 1 credit per name.
  • Test: Translate Chinese Name To Pinyin feature.

HTTP request

http requestPOST
https://v2.namsor.com/NamSorAPIv2/api2/json/pinyinChineseNameBatch

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal Chinese full names (last name and first name) in standard Mandarin Chinese.
[{...}].idStringOptionalUnique identifier.
[{...}].nameStringRequiredChinese full name (last name and first name) in Standard Mandarin Chinese.

Response

The HTTP response body is a nested array "personalNames" of objects.

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names converted to Pinyin (Latin alphabet).
[{...}].scriptStringCharacter set used for analysis.Alphabets
[{...}].idStringProvided unique identifier.
[{...}].nameStringSubmitted full name.
[{...}].nameParserTypeStringMost likely structure of the name.Name structures
[{...}].nameParserTypeAltStringSecond most likely structure of the name.Name structures
[{...}].firstLastNameObjectTranscribed name.
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringProvided unique identifier.
{...}.firstNameStringMost likely first name (or given name) transcription in Pinyin.
{...}.lastNameStringMost likely last name (or family name) transcription in Pinyin.
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.

Code sample

Translate Chinese Name To Pinyin code sample for shell :

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/pinyinChineseNameBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","name":"赵丽颖"}]}'

Body parameter:

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

The above command returns JSON structured like this :

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

Translate Chinese Name To Pinyin code sample for java :

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

Body parameter:

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

The above command returns JSON structured like this :

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

Translate Chinese Name To Pinyin code sample for python :

import requests

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

payload = {
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "赵丽颖"
    }
  ]
}
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": "赵丽颖"
    }
  ]
}

The above command returns JSON structured like this :

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

Translate Chinese Name To Pinyin code sample for javascript :

fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/pinyinChineseNameBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": "{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "赵丽颖"
    }
  ]
}"
})
.then(response => {
  console.log(response.json());
})
.catch(err => {
  console.error(err);
});

Body parameter:

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

The above command returns JSON structured like this :

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

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 Pinyin transcription of a Chinese full name (last name and first name) in Standard Mandarin Chinese.
  • Cost: 1 credit per name.
  • Test: Translate Chinese Name To Pinyin feature.

HTTP request

http requestGET
https://v2.namsor.com/NamSorAPIv2/api2/json/pinyinChineseName/{name}

Request header

PropertyRequiredDescription
X-API-KEYRequiredYour Namsor's services API key

Request parameters

NameTypeRequiredDescription
nameStringRequiredChinese full name (last name and first name) in Standard Mandarin Chinese.

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptStringCharacter set used for analysis.Alphabets
idStringProvided unique identifier.
nameStringSubmitted full name.
nameParserTypeStringMost likely structure of the name.Name structures
nameParserTypeAltStringSecond most likely structure of the name.Name structures
firstLastNameObjectTranscribed name.
{...}.scriptStringCharacter set used for analysis.Alphabets
{...}.idStringProvided unique identifier.
{...}.firstNameStringMost likely first name (or given name) transcription in Pinyin.
{...}.lastNameStringMost likely last name (or family name) transcription in Pinyin.
scoreNumberHigher implies a more reliable result, score is not normalized.

Code sample

Translate Chinese Name To Pinyin code sample for shell :

curl --request GET \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/pinyinChineseName/赵丽颖 \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'

The above command returns JSON structured like this :

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

Translate Chinese Name To Pinyin code sample for java :

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

The above command returns JSON structured like this :

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

Translate Chinese Name To Pinyin code sample for python :

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/pinyinChineseName/赵丽颖"

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

Translate Chinese Name To Pinyin code sample for javascript :