API version: 2.0.21

API key:

API documentation

Introduction

Gender from names

Genderize Name
Gender from first name , last name (optional).
Genderize Name Geo
Gender from first name , last name (optional), country code .
Genderize Full Name
Gender from full name .
Genderize Full Name Geo
Gender from full name , country code .

Origin from names

Name Origin
Origin from first name (optional), last name (optional).
Full Name Origin
Origin from full name .

Diaspora from names

Name Diaspora
Diaspora from first name (optional), last name , country code (optional).
Full Name Diaspora
Diaspora from full name , country code .

Country of residence from names

Name Country
Country of residence from first name (optional), last name (optional).
Full Name Country
Country of residence from full name .
Names Corridor
Interaction from first name , last name , country code , first name , last name , country code .

US race ethnicity from names

Name US Race
US race from first name (optional), last name (optional), country code (optional).
Full Name US Race
US race from full name , country code (optional).
Name US Race ZIP
US race from first name (optional), last name (optional), country code (optional), 5 digit zip code .

Indian names

Caste Indian Name
Caste group from first name (optional), last name (optional), state .
Caste Indian Full Name
Caste group from full name , state .
Religion Indian Name
Religion from first name (optional), last name (optional), state .
Religion Indian Full Name
Religion from full name , state .
Subclassification Indian Name
Indian State or Union territory from first name (optional), last name (optional).
Subclassification Indian Full Name
Indian State or Union territory from full name .

Split full names

Split Name
Split name from full name .
Split Name Geo
Split name from full name , country code .

Name type recognition

Name Type
Name type from proper noun .
Name Type Geo
Name type from proper noun , country code .

Phone number format

Format Phone Number
Phone prefix from first name (optional), last name (optional), phone number .
Format Phone Number Geo
Phone prefix from first name (optional), last name (optional), phone number , country code .

Admin

Country API – Estimate country of residence from names

Namsor's Country of Residence API estimates where a person currently lives based on their identity. It accepts either a full name or a combination of first and last names, making it easy to integrate into any application or research workflow. Our model goes beyond basic nationality detection by analyzing worldwide naming patterns to identify someone's likely country of residence.

Unlike legal nationality, which may not reflect a person's current situation, our API focuses on the country where an individual has likely spent most of the past year. This gives you richer, more actionable insights. It's especially valuable for market analysis, migration studies, fraud detection, and more. Namsor outperforms generic "nationality guessers" by using real-world data and advanced onomastics to pinpoint where people live—not just where they're from on paper.

600+Research contributions

99.99%Names availability

11B billionsNames processed

Name Country

Country of residence from first name (optional), last name (optional).

{
    "script": "LATIN",
    "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
    "firstName": "Keith",
    "lastName": "Haring",
    "score": 1.0276301745383112,
    "country": "AU",
    "countryAlt": "GB",
    "region": "Oceania",
    "topRegion": "Oceania",
    "subRegion": "Australia and New Zealand",
    "countriesTop": [
        "AU", "GB", "US", "CA", "NZ", "TT", "SG", "JM", "IE", "DE"
    ],
    "probabilityCalibrated": 0.2748899815464943,
    "probabilityAltCalibrated": 0.3641355716648853
}

Name Country analyzes a first name and/or last name to determine the most likely country of residence, with slightly higher accuracy than the Full Name Country feature. The response includes the region of residence, the most likely country of residence, and a ranked list of the top 10 countries, each accompanied by a calibrated probability.

Precision:
Cost: 10 credits per name.
Description: Returns the most likely country of residence of up to 100 first names and/or last names.
More about: Name Country

HTTP request

POST

https://v2.namsor.com/NamSorAPIv2/api2/json/countryFnLnBatch

Request header
Property	Values	Required	Description
`X-API-KEY`		Required	Your Namsor's services API key
`X-OPTION-RELIGION-STATS`	`True`	Optional	Returns religious statistics for estimated countries of residence. By default the feature is disabled. Add to the Header of the request the parameter `X-OPTION-RELIGION-STATS` on `True` to activate it.

To get an API key for free, please create an account.

Request body
Name	Type	Required	Description
`personalNames`	Array of objects	Required	A list of personal names.
`[{...}].id`	String	Optional	Unique identifier.
`[{...}].firstName`	String	Optional	First name, given name, nickname.
`[{...}].lastName`	String	Optional	Last name, family name, surname.

Response
Name	Type	Description	Enumerators
`personalNames`	Array of objects	List of submitted names with their countries of residence.
`[{...}].script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`[{...}].id`	String	Provided unique identifier.
`[{...}].firstName`	String	Submitted first name.
`[{...}].lastName`	String	Submitted last name.
`[{...}].score`	Number	Higher implies a more reliable result, score is not normalized.
`[{...}].country`	String	Most likely country of residence, in ISO 3166-1 alpha-2 format.	Country of residence
`[{...}].countryAlt`	String	Second most likely country of residence, in ISO 3166-1 alpha-2 format.	Country of residence
`[{...}].region`	String	Most likely region of residence.	Regions of origin or residence
`[{...}].topRegion`	String	Most likely region of residence (alternative classification).	Regions of origin or residence
`[{...}].subRegion`	String	Most likely sub-region of residence.	Sub regions of origin or residence
`[{...}].countriesTop`	Array	Top 10 most likely countries of residence, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely.
`[{...}].probabilityCalibrated`	Number	The calibrated probability that country has been guessed correctly. -1 = still calibrating.
`[{...}].probabilityAltCalibrated`	Number	The calibrated probability that country OR countryAlt have been guessed correctly. -1 = still calibrating.
			Optional: `X-OPTION-RELIGION-STATS = True`
`[{...}].religionStats`	Array of objects	Religious statistics for the most likely country of residence. Returned only if the religious statistics option is enabled (X-OPTION-RELIGION-STATS: True).
`[{...}].religion`	String	Religion in most likely country of residence (country).	Religions
`[{...}].pct`	Number	Percentage of population practicing that religion in the country of most likely residence (country).
`[{...}].religionStatsAlt`	Array of objects	Religious statistics for the second most likely country of residence. Returned only if the religious statistics option is enabled (X-OPTION-RELIGION-STATS: True).
`[{...}].religion`	String	Religion in second most likely country of residence (countryAlt).	Religions
`[{...}].pct`	Number	Percentage of population practicing this religion in second most likely country of residence (countryAlt).

Code sample:

Name Country code sample for shell:

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/countryFnLnBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4","firstName":"Keith","lastName":"Haring"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
      "firstName": "Keith",
      "lastName": "Haring"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
            "firstName": "Keith",
            "lastName": "Haring",
            "score": 1.0276301745383112,
            "country": "AU",
            "countryAlt": "GB",
            "region": "Oceania",
            "topRegion": "Oceania",
            "subRegion": "Australia and New Zealand",
            "countriesTop": ["AU", "GB", "US", "CA", "NZ", "TT", "SG", "JM", "IE", "DE"],
            "probabilityCalibrated": 0.2748899815464943,
            "probabilityAltCalibrated": 0.3641355716648853
        }
    ]
}

Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.

{
  religionStats: [
    { religion: 'Christian', pct: 78.3 },
    { religion: 'Unaffiliated', pct: 16.4 },
    { religion: 'Jewish', pct: 1.8 },
    { religion: 'Buddhist', pct: 1.2 },
    { religion: 'Muslim', pct: 0.9 },
    { religion: 'Hindu', pct: 0.6 },
    { religion: 'Other', pct: 0.6 },
    { religion: 'Folk', pct: 0.2 },
  ],
  religionStatsAlt: [
    { religion: 'Christian', pct: 78.3007843079025 },
    { religion: 'Unaffiliated', pct: 16.39975226849653 },
    { religion: 'Jewish', pct: 1.799802305332493 },
    { religion: 'Buddhist', pct: 1.1998700873301702 },
    { religion: 'Muslim', pct: 0.8999039783290091 },
    { religion: 'Other', pct: 0.5999661259551334 },
    { religion: 'Hindu', pct: 0.5999378693278477 },
    { religion: 'Folk', pct: 0.1999830573262992 },
  ],
}

Name Country code sample for java:

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

Body parameter:

{
  "personalNames": [
    {
      "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
      "firstName": "Keith",
      "lastName": "Haring"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
            "firstName": "Keith",
            "lastName": "Haring",
            "score": 1.0276301745383112,
            "country": "AU",
            "countryAlt": "GB",
            "region": "Oceania",
            "topRegion": "Oceania",
            "subRegion": "Australia and New Zealand",
            "countriesTop": ["AU", "GB", "US", "CA", "NZ", "TT", "SG", "JM", "IE", "DE"],
            "probabilityCalibrated": 0.2748899815464943,
            "probabilityAltCalibrated": 0.3641355716648853
        }
    ]
}

Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.

{
  religionStats: [
    { religion: 'Christian', pct: 78.3 },
    { religion: 'Unaffiliated', pct: 16.4 },
    { religion: 'Jewish', pct: 1.8 },
    { religion: 'Buddhist', pct: 1.2 },
    { religion: 'Muslim', pct: 0.9 },
    { religion: 'Hindu', pct: 0.6 },
    { religion: 'Other', pct: 0.6 },
    { religion: 'Folk', pct: 0.2 },
  ],
  religionStatsAlt: [
    { religion: 'Christian', pct: 78.3007843079025 },
    { religion: 'Unaffiliated', pct: 16.39975226849653 },
    { religion: 'Jewish', pct: 1.799802305332493 },
    { religion: 'Buddhist', pct: 1.1998700873301702 },
    { religion: 'Muslim', pct: 0.8999039783290091 },
    { religion: 'Other', pct: 0.5999661259551334 },
    { religion: 'Hindu', pct: 0.5999378693278477 },
    { religion: 'Folk', pct: 0.1999830573262992 },
  ],
}

Name Country code sample for python:

import requests

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

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

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

print(response.text)

Body parameter:

{
  "personalNames": [
    {
      "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
      "firstName": "Keith",
      "lastName": "Haring"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
            "firstName": "Keith",
            "lastName": "Haring",
            "score": 1.0276301745383112,
            "country": "AU",
            "countryAlt": "GB",
            "region": "Oceania",
            "topRegion": "Oceania",
            "subRegion": "Australia and New Zealand",
            "countriesTop": ["AU", "GB", "US", "CA", "NZ", "TT", "SG", "JM", "IE", "DE"],
            "probabilityCalibrated": 0.2748899815464943,
            "probabilityAltCalibrated": 0.3641355716648853
        }
    ]
}

Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.

{
  religionStats: [
    { religion: 'Christian', pct: 78.3 },
    { religion: 'Unaffiliated', pct: 16.4 },
    { religion: 'Jewish', pct: 1.8 },
    { religion: 'Buddhist', pct: 1.2 },
    { religion: 'Muslim', pct: 0.9 },
    { religion: 'Hindu', pct: 0.6 },
    { religion: 'Other', pct: 0.6 },
    { religion: 'Folk', pct: 0.2 },
  ],
  religionStatsAlt: [
    { religion: 'Christian', pct: 78.3007843079025 },
    { religion: 'Unaffiliated', pct: 16.39975226849653 },
    { religion: 'Jewish', pct: 1.799802305332493 },
    { religion: 'Buddhist', pct: 1.1998700873301702 },
    { religion: 'Muslim', pct: 0.8999039783290091 },
    { religion: 'Other', pct: 0.5999661259551334 },
    { religion: 'Hindu', pct: 0.5999378693278477 },
    { religion: 'Folk', pct: 0.1999830573262992 },
  ],
}

Name Country code sample for javascript:

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

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

Body parameter:

{
  "personalNames": [
    {
      "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
      "firstName": "Keith",
      "lastName": "Haring"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
            "firstName": "Keith",
            "lastName": "Haring",
            "score": 1.0276301745383112,
            "country": "AU",
            "countryAlt": "GB",
            "region": "Oceania",
            "topRegion": "Oceania",
            "subRegion": "Australia and New Zealand",
            "countriesTop": ["AU", "GB", "US", "CA", "NZ", "TT", "SG", "JM", "IE", "DE"],
            "probabilityCalibrated": 0.2748899815464943,
            "probabilityAltCalibrated": 0.3641355716648853
        }
    ]
}

Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.

{
  religionStats: [
    { religion: 'Christian', pct: 78.3 },
    { religion: 'Unaffiliated', pct: 16.4 },
    { religion: 'Jewish', pct: 1.8 },
    { religion: 'Buddhist', pct: 1.2 },
    { religion: 'Muslim', pct: 0.9 },
    { religion: 'Hindu', pct: 0.6 },
    { religion: 'Other', pct: 0.6 },
    { religion: 'Folk', pct: 0.2 },
  ],
  religionStatsAlt: [
    { religion: 'Christian', pct: 78.3007843079025 },
    { religion: 'Unaffiliated', pct: 16.39975226849653 },
    { religion: 'Jewish', pct: 1.799802305332493 },
    { religion: 'Buddhist', pct: 1.1998700873301702 },
    { religion: 'Muslim', pct: 0.8999039783290091 },
    { religion: 'Other', pct: 0.5999661259551334 },
    { religion: 'Hindu', pct: 0.5999378693278477 },
    { religion: 'Folk', pct: 0.1999830573262992 },
  ],
}

Precision:
Cost: 10 credits per name.
Description: Returns the most likely country of residence from a first name and/or a last name.

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

GET

https://v2.namsor.com/NamSorAPIv2/api2/json/countryFnLn/{firstName}/{lastName}

Request header
Property	Values	Required	Description
`X-API-KEY`		Required	Your Namsor's services API key
`X-OPTION-RELIGION-STATS`	`True`	Optional	Returns religious statistics for estimated countries of residence. By default the feature is disabled. Add to the Header of the request the parameter `X-OPTION-RELIGION-STATS` on `True` to activate it.

To get an API key for free, please create an account.

Request parameters
Name	Type	Required	Description
`firstName`	String	Required	First name, given name, nickname.
`lastName`	String	Required	Last name, family name, surname.

Response
Name	Type	Description	Enumerators
`script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`id`	String	Provided unique identifier.
`firstName`	String	Submitted first name.
`lastName`	String	Submitted last name.
`score`	Number	Higher implies a more reliable result, score is not normalized.
`country`	String	Most likely country of residence, in ISO 3166-1 alpha-2 format.	Country of residence
`countryAlt`	String	Second most likely country of residence, in ISO 3166-1 alpha-2 format.	Country of residence
`region`	String	Most likely region of residence.	Regions of origin or residence
`topRegion`	String	Most likely region of residence (alternative classification).	Regions of origin or residence
`subRegion`	String	Most likely sub-region of residence.	Sub regions of origin or residence
`countriesTop`	Array	Top 10 most likely countries of residence, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely.
`probabilityCalibrated`	Number	The calibrated probability that country has been guessed correctly. -1 = still calibrating.
`probabilityAltCalibrated`	Number	The calibrated probability that country OR countryAlt have been guessed correctly. -1 = still calibrating.
`religion`	String	Religion in most likely country of residence (country).	Religions
`pct`	Number	Percentage of population practicing that religion in the country of most likely residence (country).
`religion`	String	Religion in second most likely country of residence (countryAlt).	Religions
`pct`	Number	Percentage of population practicing this religion in second most likely country of residence (countryAlt).

Code sample:

Name Country code sample for shell:

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

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
    "firstName": "Keith",
    "lastName": "Haring",
    "score": 1.0276301745383112,
    "country": "AU",
    "countryAlt": "GB",
    "region": "Oceania",
    "topRegion": "Oceania",
    "subRegion": "Australia and New Zealand",
    "countriesTop": ["AU", "GB", "US", "CA", "NZ", "TT", "SG", "JM", "IE", "DE"],
    "probabilityCalibrated": 0.2748899815464943,
    "probabilityAltCalibrated": 0.3641355716648853
}

Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.

{
  religionStats: [
    { religion: 'Christian', pct: 78.3 },
    { religion: 'Unaffiliated', pct: 16.4 },
    { religion: 'Jewish', pct: 1.8 },
    { religion: 'Buddhist', pct: 1.2 },
    { religion: 'Muslim', pct: 0.9 },
    { religion: 'Hindu', pct: 0.6 },
    { religion: 'Other', pct: 0.6 },
    { religion: 'Folk', pct: 0.2 },
  ],
  religionStatsAlt: [
    { religion: 'Christian', pct: 78.3007843079025 },
    { religion: 'Unaffiliated', pct: 16.39975226849653 },
    { religion: 'Jewish', pct: 1.799802305332493 },
    { religion: 'Buddhist', pct: 1.1998700873301702 },
    { religion: 'Muslim', pct: 0.8999039783290091 },
    { religion: 'Other', pct: 0.5999661259551334 },
    { religion: 'Hindu', pct: 0.5999378693278477 },
    { religion: 'Folk', pct: 0.1999830573262992 },
  ],
}

Name Country code sample for java:

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

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
    "firstName": "Keith",
    "lastName": "Haring",
    "score": 1.0276301745383112,
    "country": "AU",
    "countryAlt": "GB",
    "region": "Oceania",
    "topRegion": "Oceania",
    "subRegion": "Australia and New Zealand",
    "countriesTop": ["AU", "GB", "US", "CA", "NZ", "TT", "SG", "JM", "IE", "DE"],
    "probabilityCalibrated": 0.2748899815464943,
    "probabilityAltCalibrated": 0.3641355716648853
}

Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.

{
  religionStats: [
    { religion: 'Christian', pct: 78.3 },
    { religion: 'Unaffiliated', pct: 16.4 },
    { religion: 'Jewish', pct: 1.8 },
    { religion: 'Buddhist', pct: 1.2 },
    { religion: 'Muslim', pct: 0.9 },
    { religion: 'Hindu', pct: 0.6 },
    { religion: 'Other', pct: 0.6 },
    { religion: 'Folk', pct: 0.2 },
  ],
  religionStatsAlt: [
    { religion: 'Christian', pct: 78.3007843079025 },
    { religion: 'Unaffiliated', pct: 16.39975226849653 },
    { religion: 'Jewish', pct: 1.799802305332493 },
    { religion: 'Buddhist', pct: 1.1998700873301702 },
    { religion: 'Muslim', pct: 0.8999039783290091 },
    { religion: 'Other', pct: 0.5999661259551334 },
    { religion: 'Hindu', pct: 0.5999378693278477 },
    { religion: 'Folk', pct: 0.1999830573262992 },
  ],
}

Name Country code sample for python:

import requests

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

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

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

print(response.text)

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
    "firstName": "Keith",
    "lastName": "Haring",
    "score": 1.0276301745383112,
    "country": "AU",
    "countryAlt": "GB",
    "region": "Oceania",
    "topRegion": "Oceania",
    "subRegion": "Australia and New Zealand",
    "countriesTop": ["AU", "GB", "US", "CA", "NZ", "TT", "SG", "JM", "IE", "DE"],
    "probabilityCalibrated": 0.2748899815464943,
    "probabilityAltCalibrated": 0.3641355716648853
}

Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.

{
  religionStats: [
    { religion: 'Christian', pct: 78.3 },
    { religion: 'Unaffiliated', pct: 16.4 },
    { religion: 'Jewish', pct: 1.8 },
    { religion: 'Buddhist', pct: 1.2 },
    { religion: 'Muslim', pct: 0.9 },
    { religion: 'Hindu', pct: 0.6 },
    { religion: 'Other', pct: 0.6 },
    { religion: 'Folk', pct: 0.2 },
  ],
  religionStatsAlt: [
    { religion: 'Christian', pct: 78.3007843079025 },
    { religion: 'Unaffiliated', pct: 16.39975226849653 },
    { religion: 'Jewish', pct: 1.799802305332493 },
    { religion: 'Buddhist', pct: 1.1998700873301702 },
    { religion: 'Muslim', pct: 0.8999039783290091 },
    { religion: 'Other', pct: 0.5999661259551334 },
    { religion: 'Hindu', pct: 0.5999378693278477 },
    { religion: 'Folk', pct: 0.1999830573262992 },
  ],
}

Name Country code sample for javascript:

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

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

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
    "firstName": "Keith",
    "lastName": "Haring",
    "score": 1.0276301745383112,
    "country": "AU",
    "countryAlt": "GB",
    "region": "Oceania",
    "topRegion": "Oceania",
    "subRegion": "Australia and New Zealand",
    "countriesTop": ["AU", "GB", "US", "CA", "NZ", "TT", "SG", "JM", "IE", "DE"],
    "probabilityCalibrated": 0.2748899815464943,
    "probabilityAltCalibrated": 0.3641355716648853
}

Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.

{
  religionStats: [
    { religion: 'Christian', pct: 78.3 },
    { religion: 'Unaffiliated', pct: 16.4 },
    { religion: 'Jewish', pct: 1.8 },
    { religion: 'Buddhist', pct: 1.2 },
    { religion: 'Muslim', pct: 0.9 },
    { religion: 'Hindu', pct: 0.6 },
    { religion: 'Other', pct: 0.6 },
    { religion: 'Folk', pct: 0.2 },
  ],
  religionStatsAlt: [
    { religion: 'Christian', pct: 78.3007843079025 },
    { religion: 'Unaffiliated', pct: 16.39975226849653 },
    { religion: 'Jewish', pct: 1.799802305332493 },
    { religion: 'Buddhist', pct: 1.1998700873301702 },
    { religion: 'Muslim', pct: 0.8999039783290091 },
    { religion: 'Other', pct: 0.5999661259551334 },
    { religion: 'Hindu', pct: 0.5999378693278477 },
    { religion: 'Folk', pct: 0.1999830573262992 },
  ],
}

Full Name Country

Country of residence from full name .

{
    "script": "LATIN",
    "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
    "name": "Keith Haring",
    "score": 2.051795198803658,
    "country": "GB",
    "countryAlt": "NZ",
    "region": "Europe",
    "topRegion": "Europe",
    "subRegion": "Northern Europe",
    "countriesTop": [
        "GB", "NZ", "US", "AU", "IE", "CA", "JM", "TT", "SG", "DE"
    ],
    "probabilityCalibrated": 0.22823337808846267,
    "probabilityAltCalibrated": 0.24281407862260063
}

Full Name Country analyzes an unsplit full name (first and last name combined) to identify the most likely country of residence. The response includes the region of residence, the most likely country of residence, and a ranked list of the top 10 countries, each accompanied by a calibrated probability.

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

Precision:
Cost: 10 credits per name.
Description: Returns the most likely country of residence of up to 100 unsplit full names.
More about: Full Name Country

HTTP request

POST

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

Request header
Property	Values	Required	Description
`X-API-KEY`		Required	Your Namsor's services API key
`X-OPTION-RELIGION-STATS`	`True`	Optional	Returns religious statistics for estimated countries of residence. By default the feature is disabled. Add to the Header of the request the parameter `X-OPTION-RELIGION-STATS` on `True` to activate it.

To get an API key for free, please create an account.

Request body
Name	Type	Required	Description
`personalNames`	Array of objects	Required	A list of personal names.
`[{...}].id`	String	Optional	Unique identifier.
`[{...}].name`	String	Required	Unsplit full name (first name and last name).

Response
Name	Type	Description	Enumerators
`personalNames`	Array of objects	List of submitted full names with their countries of residence.
`[{...}].script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`[{...}].id`	String	Provided unique identifier.
`[{...}].name`	String	Submitted full name.
`[{...}].score`	Number	Higher implies a more reliable result, score is not normalized.
`[{...}].country`	String	Most likely country of residence, in ISO 3166-1 alpha-2 format.	Country of residence
`[{...}].countryAlt`	String	Second most likely country of residence, in ISO 3166-1 alpha-2 format.	Country of residence
`[{...}].region`	String	Most likely region of residence.	Regions of origin or residence
`[{...}].topRegion`	String	Most likely region of residence (alternative classification).	Regions of origin or residence
`[{...}].subRegion`	String	Most likely sub-region of residence.	Sub regions of origin or residence
`[{...}].countriesTop`	Array	Top 10 most likely countries of residence, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely.
`[{...}].probabilityCalibrated`	Number	The calibrated probability that country has been guessed correctly. -1 = still calibrating.
`[{...}].probabilityAltCalibrated`	Number	The calibrated probability that country OR countryAlt have been guessed correctly. -1 = still calibrating.
			Optional: `X-OPTION-RELIGION-STATS = True`
`[{...}].religionStats`	Array of objects	Religious statistics for the most likely country of residence. Returned only if the religious statistics option is enabled (X-OPTION-RELIGION-STATS: True).
`[{...}].religion`	String	Religion in most likely country of residence (country).	Religions
`[{...}].pct`	Number	Percentage of population practicing that religion in the country of most likely residence (country).
`[{...}].religionStatsAlt`	Array of objects	Religious statistics for the second most likely country of residence. Returned only if the religious statistics option is enabled (X-OPTION-RELIGION-STATS: True).
`[{...}].religion`	String	Religion in second most likely country of residence (countryAlt).	Religions
`[{...}].pct`	Number	Percentage of population practicing this religion in second most likely country of residence (countryAlt).

Code sample:

Full Name Country code sample for shell:

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/countryBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4","name":"Keith Haring"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
      "name": "Keith Haring"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
            "name": "Keith Haring",
            "score": 2.051795198803658,
            "country": "GB",
            "countryAlt": "NZ",
            "region": "Europe",
            "topRegion": "Europe",
            "subRegion": "Northern Europe",
            "countriesTop": ["GB", "NZ", "US", "AU", "IE", "CA", "JM", "TT", "SG", "DE"],
            "probabilityCalibrated": 0.22823337808846267,
            "probabilityAltCalibrated": 0.24281407862260063
        }
    ]
}

Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.

{
  religionStats: [
    { religion: 'Christian', pct: 78.3 },
    { religion: 'Unaffiliated', pct: 16.4 },
    { religion: 'Jewish', pct: 1.8 },
    { religion: 'Buddhist', pct: 1.2 },
    { religion: 'Muslim', pct: 0.9 },
    { religion: 'Hindu', pct: 0.6 },
    { religion: 'Other', pct: 0.6 },
    { religion: 'Folk', pct: 0.2 },
  ],
  religionStatsAlt: [
    { religion: 'Christian', pct: 78.3007843079025 },
    { religion: 'Unaffiliated', pct: 16.39975226849653 },
    { religion: 'Jewish', pct: 1.799802305332493 },
    { religion: 'Buddhist', pct: 1.1998700873301702 },
    { religion: 'Muslim', pct: 0.8999039783290091 },
    { religion: 'Other', pct: 0.5999661259551334 },
    { religion: 'Hindu', pct: 0.5999378693278477 },
    { religion: 'Folk', pct: 0.1999830573262992 },
  ],
}

Full Name Country code sample for java:

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

Body parameter:

{
  "personalNames": [
    {
      "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
      "name": "Keith Haring"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
            "name": "Keith Haring",
            "score": 2.051795198803658,
            "country": "GB",
            "countryAlt": "NZ",
            "region": "Europe",
            "topRegion": "Europe",
            "subRegion": "Northern Europe",
            "countriesTop": ["GB", "NZ", "US", "AU", "IE", "CA", "JM", "TT", "SG", "DE"],
            "probabilityCalibrated": 0.22823337808846267,
            "probabilityAltCalibrated": 0.24281407862260063
        }
    ]
}

Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.

{
  religionStats: [
    { religion: 'Christian', pct: 78.3 },
    { religion: 'Unaffiliated', pct: 16.4 },
    { religion: 'Jewish', pct: 1.8 },
    { religion: 'Buddhist', pct: 1.2 },
    { religion: 'Muslim', pct: 0.9 },
    { religion: 'Hindu', pct: 0.6 },
    { religion: 'Other', pct: 0.6 },
    { religion: 'Folk', pct: 0.2 },
  ],
  religionStatsAlt: [
    { religion: 'Christian', pct: 78.3007843079025 },
    { religion: 'Unaffiliated', pct: 16.39975226849653 },
    { religion: 'Jewish', pct: 1.799802305332493 },
    { religion: 'Buddhist', pct: 1.1998700873301702 },
    { religion: 'Muslim', pct: 0.8999039783290091 },
    { religion: 'Other', pct: 0.5999661259551334 },
    { religion: 'Hindu', pct: 0.5999378693278477 },
    { religion: 'Folk', pct: 0.1999830573262992 },
  ],
}

Full Name Country code sample for python:

import requests

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

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

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

print(response.text)

Body parameter:

{
  "personalNames": [
    {
      "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
      "name": "Keith Haring"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
            "name": "Keith Haring",
            "score": 2.051795198803658,
            "country": "GB",
            "countryAlt": "NZ",
            "region": "Europe",
            "topRegion": "Europe",
            "subRegion": "Northern Europe",
            "countriesTop": ["GB", "NZ", "US", "AU", "IE", "CA", "JM", "TT", "SG", "DE"],
            "probabilityCalibrated": 0.22823337808846267,
            "probabilityAltCalibrated": 0.24281407862260063
        }
    ]
}

Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.

{
  religionStats: [
    { religion: 'Christian', pct: 78.3 },
    { religion: 'Unaffiliated', pct: 16.4 },
    { religion: 'Jewish', pct: 1.8 },
    { religion: 'Buddhist', pct: 1.2 },
    { religion: 'Muslim', pct: 0.9 },
    { religion: 'Hindu', pct: 0.6 },
    { religion: 'Other', pct: 0.6 },
    { religion: 'Folk', pct: 0.2 },
  ],
  religionStatsAlt: [
    { religion: 'Christian', pct: 78.3007843079025 },
    { religion: 'Unaffiliated', pct: 16.39975226849653 },
    { religion: 'Jewish', pct: 1.799802305332493 },
    { religion: 'Buddhist', pct: 1.1998700873301702 },
    { religion: 'Muslim', pct: 0.8999039783290091 },
    { religion: 'Other', pct: 0.5999661259551334 },
    { religion: 'Hindu', pct: 0.5999378693278477 },
    { religion: 'Folk', pct: 0.1999830573262992 },
  ],
}

Full Name Country code sample for javascript:

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

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

Body parameter:

{
  "personalNames": [
    {
      "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
      "name": "Keith Haring"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
            "name": "Keith Haring",
            "score": 2.051795198803658,
            "country": "GB",
            "countryAlt": "NZ",
            "region": "Europe",
            "topRegion": "Europe",
            "subRegion": "Northern Europe",
            "countriesTop": ["GB", "NZ", "US", "AU", "IE", "CA", "JM", "TT", "SG", "DE"],
            "probabilityCalibrated": 0.22823337808846267,
            "probabilityAltCalibrated": 0.24281407862260063
        }
    ]
}

Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.

{
  religionStats: [
    { religion: 'Christian', pct: 78.3 },
    { religion: 'Unaffiliated', pct: 16.4 },
    { religion: 'Jewish', pct: 1.8 },
    { religion: 'Buddhist', pct: 1.2 },
    { religion: 'Muslim', pct: 0.9 },
    { religion: 'Hindu', pct: 0.6 },
    { religion: 'Other', pct: 0.6 },
    { religion: 'Folk', pct: 0.2 },
  ],
  religionStatsAlt: [
    { religion: 'Christian', pct: 78.3007843079025 },
    { religion: 'Unaffiliated', pct: 16.39975226849653 },
    { religion: 'Jewish', pct: 1.799802305332493 },
    { religion: 'Buddhist', pct: 1.1998700873301702 },
    { religion: 'Muslim', pct: 0.8999039783290091 },
    { religion: 'Other', pct: 0.5999661259551334 },
    { religion: 'Hindu', pct: 0.5999378693278477 },
    { religion: 'Folk', pct: 0.1999830573262992 },
  ],
}

Precision:
Cost: 10 credits per name.
Description: Returns the most likely country of residence from an unsplit full name.

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

GET

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

Request header
Property	Values	Required	Description
`X-API-KEY`		Required	Your Namsor's services API key
`X-OPTION-RELIGION-STATS`	`True`	Optional	Returns religious statistics for estimated countries of residence. By default the feature is disabled. Add to the Header of the request the parameter `X-OPTION-RELIGION-STATS` on `True` to activate it.

To get an API key for free, please create an account.

Request parameters
Name	Type	Required	Description
`name`	String	Required	Unsplit full name (first name and last name).

Response
Name	Type	Description	Enumerators
`script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`id`	String	Provided unique identifier.
`name`	String	Submitted full name.
`score`	Number	Higher implies a more reliable result, score is not normalized.
`country`	String	Most likely country of residence, in ISO 3166-1 alpha-2 format.	Country of residence
`countryAlt`	String	Second most likely country of residence, in ISO 3166-1 alpha-2 format.	Country of residence
`region`	String	Most likely region of residence.	Regions of origin or residence
`topRegion`	String	Most likely region of residence (alternative classification).	Regions of origin or residence
`subRegion`	String	Most likely sub-region of residence.	Sub regions of origin or residence
`countriesTop`	Array	Top 10 most likely countries of residence, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely.
`probabilityCalibrated`	Number	The calibrated probability that country has been guessed correctly. -1 = still calibrating.
`probabilityAltCalibrated`	Number	The calibrated probability that country OR countryAlt have been guessed correctly. -1 = still calibrating.
`religion`	String	Religion in most likely country of residence (country).	Religions
`pct`	Number	Percentage of population practicing that religion in the country of most likely residence (country).
`religion`	String	Religion in second most likely country of residence (countryAlt).	Religions
`pct`	Number	Percentage of population practicing this religion in second most likely country of residence (countryAlt).

Code sample:

Full Name Country code sample for shell:

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

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
    "name": "Keith Haring",
    "score": 2.051795198803658,
    "country": "GB",
    "countryAlt": "NZ",
    "region": "Europe",
    "topRegion": "Europe",
    "subRegion": "Northern Europe",
    "countriesTop": ["GB", "NZ", "US", "AU", "IE", "CA", "JM", "TT", "SG", "DE"],
    "probabilityCalibrated": 0.22823337808846267,
    "probabilityAltCalibrated": 0.24281407862260063
}

Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.

{
  religionStats: [
    { religion: 'Christian', pct: 78.3 },
    { religion: 'Unaffiliated', pct: 16.4 },
    { religion: 'Jewish', pct: 1.8 },
    { religion: 'Buddhist', pct: 1.2 },
    { religion: 'Muslim', pct: 0.9 },
    { religion: 'Hindu', pct: 0.6 },
    { religion: 'Other', pct: 0.6 },
    { religion: 'Folk', pct: 0.2 },
  ],
  religionStatsAlt: [
    { religion: 'Christian', pct: 78.3007843079025 },
    { religion: 'Unaffiliated', pct: 16.39975226849653 },
    { religion: 'Jewish', pct: 1.799802305332493 },
    { religion: 'Buddhist', pct: 1.1998700873301702 },
    { religion: 'Muslim', pct: 0.8999039783290091 },
    { religion: 'Other', pct: 0.5999661259551334 },
    { religion: 'Hindu', pct: 0.5999378693278477 },
    { religion: 'Folk', pct: 0.1999830573262992 },
  ],
}

Full Name Country code sample for java:

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

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
    "name": "Keith Haring",
    "score": 2.051795198803658,
    "country": "GB",
    "countryAlt": "NZ",
    "region": "Europe",
    "topRegion": "Europe",
    "subRegion": "Northern Europe",
    "countriesTop": ["GB", "NZ", "US", "AU", "IE", "CA", "JM", "TT", "SG", "DE"],
    "probabilityCalibrated": 0.22823337808846267,
    "probabilityAltCalibrated": 0.24281407862260063
}

Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.

{
  religionStats: [
    { religion: 'Christian', pct: 78.3 },
    { religion: 'Unaffiliated', pct: 16.4 },
    { religion: 'Jewish', pct: 1.8 },
    { religion: 'Buddhist', pct: 1.2 },
    { religion: 'Muslim', pct: 0.9 },
    { religion: 'Hindu', pct: 0.6 },
    { religion: 'Other', pct: 0.6 },
    { religion: 'Folk', pct: 0.2 },
  ],
  religionStatsAlt: [
    { religion: 'Christian', pct: 78.3007843079025 },
    { religion: 'Unaffiliated', pct: 16.39975226849653 },
    { religion: 'Jewish', pct: 1.799802305332493 },
    { religion: 'Buddhist', pct: 1.1998700873301702 },
    { religion: 'Muslim', pct: 0.8999039783290091 },
    { religion: 'Other', pct: 0.5999661259551334 },
    { religion: 'Hindu', pct: 0.5999378693278477 },
    { religion: 'Folk', pct: 0.1999830573262992 },
  ],
}

Full Name Country code sample for python:

import requests

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

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

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

print(response.text)

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
    "name": "Keith Haring",
    "score": 2.051795198803658,
    "country": "GB",
    "countryAlt": "NZ",
    "region": "Europe",
    "topRegion": "Europe",
    "subRegion": "Northern Europe",
    "countriesTop": ["GB", "NZ", "US", "AU", "IE", "CA", "JM", "TT", "SG", "DE"],
    "probabilityCalibrated": 0.22823337808846267,
    "probabilityAltCalibrated": 0.24281407862260063
}

Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.

{
  religionStats: [
    { religion: 'Christian', pct: 78.3 },
    { religion: 'Unaffiliated', pct: 16.4 },
    { religion: 'Jewish', pct: 1.8 },
    { religion: 'Buddhist', pct: 1.2 },
    { religion: 'Muslim', pct: 0.9 },
    { religion: 'Hindu', pct: 0.6 },
    { religion: 'Other', pct: 0.6 },
    { religion: 'Folk', pct: 0.2 },
  ],
  religionStatsAlt: [
    { religion: 'Christian', pct: 78.3007843079025 },
    { religion: 'Unaffiliated', pct: 16.39975226849653 },
    { religion: 'Jewish', pct: 1.799802305332493 },
    { religion: 'Buddhist', pct: 1.1998700873301702 },
    { religion: 'Muslim', pct: 0.8999039783290091 },
    { religion: 'Other', pct: 0.5999661259551334 },
    { religion: 'Hindu', pct: 0.5999378693278477 },
    { religion: 'Folk', pct: 0.1999830573262992 },
  ],
}

Full Name Country code sample for javascript:

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

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

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "9a3283bd-4efb-4b7b-906c-e3f3c03ea6a4",
    "name": "Keith Haring",
    "score": 2.051795198803658,
    "country": "GB",
    "countryAlt": "NZ",
    "region": "Europe",
    "topRegion": "Europe",
    "subRegion": "Northern Europe",
    "countriesTop": ["GB", "NZ", "US", "AU", "IE", "CA", "JM", "TT", "SG", "DE"],
    "probabilityCalibrated": 0.22823337808846267,
    "probabilityAltCalibrated": 0.24281407862260063
}

Values returned only if the religious statistics option is enabled X-OPTION-RELIGION-STATS: True.

{
  religionStats: [
    { religion: 'Christian', pct: 78.3 },
    { religion: 'Unaffiliated', pct: 16.4 },
    { religion: 'Jewish', pct: 1.8 },
    { religion: 'Buddhist', pct: 1.2 },
    { religion: 'Muslim', pct: 0.9 },
    { religion: 'Hindu', pct: 0.6 },
    { religion: 'Other', pct: 0.6 },
    { religion: 'Folk', pct: 0.2 },
  ],
  religionStatsAlt: [
    { religion: 'Christian', pct: 78.3007843079025 },
    { religion: 'Unaffiliated', pct: 16.39975226849653 },
    { religion: 'Jewish', pct: 1.799802305332493 },
    { religion: 'Buddhist', pct: 1.1998700873301702 },
    { religion: 'Muslim', pct: 0.8999039783290091 },
    { religion: 'Other', pct: 0.5999661259551334 },
    { religion: 'Hindu', pct: 0.5999378693278477 },
    { religion: 'Folk', pct: 0.1999830573262992 },
  ],
}

Names Corridor

Interaction from first name , last name , country code , first name , last name , country code .

Name Corridor feature analyzes two person's first name, last name, and country of residence to return a comprehensive report of the interaction.

Cost: 50 credits per name.
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).
More about: Names Corridor

HTTP request

POST

https://v2.namsor.com/NamSorAPIv2/api2/json/corridorBatch

Request header
Property	Required	Description
`X-API-KEY`	Required	Your Namsor's services API key

To get an API key for free, please create an account.

Request body
Name	Type	Required	Description
`corridorFromTo`	Array of objects	Required	A list of name pairs, with country code (nameFrom -> nameTo)..
`[{...}].id`	String	Optional	Unique identifier.
`[{...}].firstLastNameGeoFrom`	Object	Required	.
`{...}.id`	String	Optional	Unique identifier.
`{...}.firstName`	String	Required	First name (or given name) of the sender.
`{...}.lastName`	String	Required	Last name (or family name) of the sender.
`{...}.countryIso2`	String	Required	Country of origin of the sender, in ISO 3166-1 alpha-2 format.
`[{...}].firstLastNameGeoTo`	Object	Required	.
`{...}.id`	String	Optional	Unique identifier.
`{...}.firstName`	String	Required	First name (or given name) of the receiver.
`{...}.lastName`	String	Required	Last name (or family name) of the receiver.
`{...}.countryIso2`	String	Required	Country of origin of the receiver, in ISO 3166-1 alpha-2 format.

Response
Name	Type	Description	Enumerators
`corridorFromTo`	Array of objects	A list of classified name pairs..
`[{...}].id`	String	Unique identifier.
`[{...}].firstLastNameGeoFromGender`	Object	Gender data for the sender name.
`{...}.script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`{...}.id`	String	Unique identifier.
`{...}.firstName`	String	Submitted first name (or given name) of the sender.
`{...}.lastName`	String	Submitted last name (or family name) of the sender.
`{...}.likelyGender`	String	Most likely gender.	Genders
`{...}.genderScale`	Number	Gender scale ranging from -1 (male) to +1 (female).
`{...}.score`	Number	Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
`{...}.probabilityCalibrated`	Number	Higher implies a more reliable result, ranges from 0 to 1.
`[{...}].firstLastNameGeoToGender`	Object	Gender data for the receiver name.
`{...}.script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`{...}.id`	String	Unique identifier.
`{...}.firstName`	String	Submitted first name (or given name) of the receiver.
`{...}.lastName`	String	Submitted last name (or family name) of the receiver.
`{...}.likelyGender`	String	Most likely gender.	Genders
`{...}.genderScale`	Number	Gender scale ranging from -1 (male) to +1 (female).
`{...}.score`	Number	Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
`{...}.probabilityCalibrated`	Number	Higher implies a more reliable result, ranges from 0 to 1.
`[{...}].firstLastNameGeoFromOrigin`	Object	Origin data for the sender name.
`{...}.script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`{...}.id`	String	Unique identifier.
`{...}.firstName`	String	Submitted first name (or given name) of the sender.
`{...}.lastName`	String	Submitted last name (or family name) of the sender.
`{...}.countryOrigin`	String	Most likely country of origin of the sender, in ISO 3166-1 alpha-2 format.	Country of origin
`{...}.countryOriginAlt`	String	Second most likely country of origin of the sender, in ISO 3166-1 alpha-2 format.	Country of origin
`{...}.countriesOriginTop`	Array	Top 10 most likely countries of origin of the sender, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely.	Country of origin
`{...}.score`	Number	Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
`{...}.regionOrigin`	String	Most likely region of origin of the sender.	Regions of origin or residence
`{...}.topRegionOrigin`	String	Most likely region of origin of the sender (alternative classification).	Regions of origin or residence
`{...}.subRegionOrigin`	String	Most likely sub-region of origin of the sender.	Sub regions of origin or residence
`{...}.probabilityCalibrated`	Number	The calibrated probability for countryOrigin to have been guessed correctly. -1 = still calibrating.
`{...}.probabilityAltCalibrated`	Number	The calibrated probability for countryOrigin OR countryOriginAlt to have been guessed correctly. -1 = still calibrating.
`[{...}].firstLastNameGeoToOrigin`	Object	Origin data for the receiver name.
`{...}.script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`{...}.id`	String	Unique identifier.
`{...}.firstName`	String	Submitted first name (or given name) of the receiver.
`{...}.lastName`	String	Submitted last name (or family name) of the receiver.
`{...}.countryOrigin`	String	Most likely country of origin of the receiver, in ISO 3166-1 alpha-2 format.	Country of origin
`{...}.countryOriginAlt`	String	Second most likely country of origin of the receiver, in ISO 3166-1 alpha-2 format.	Country of origin
`{...}.countriesOriginTop`	Array	Top 10 most likely countries of origin of the receiver, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely.	Country of origin
`{...}.score`	Number	Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
`{...}.regionOrigin`	String	Most likely region of origin.	Regions of origin or residence
`{...}.topRegionOrigin`	String	Most likely region of origin of the receiver (alternative classification).	Regions of origin or residence
`{...}.subRegionOrigin`	String	Most likely sub-region of origin of the receiver.	Sub regions of origin or residence
`{...}.probabilityCalibrated`	Number	The calibrated probability for countryOrigin to have been guessed correctly. -1 = still calibrating.
`{...}.probabilityAltCalibrated`	Number	The calibrated probability for countryOrigin OR countryOriginAlt to have been guessed correctly. -1 = still calibrating.
`[{...}].firstLastNameGeoFromDiaspora`	Object	Diaspora data for the sender name.
`{...}.script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`{...}.id`	String	Unique identifier.
`{...}.firstName`	String	Submitted first name (or given name) of the sender.
`{...}.lastName`	String	Submitted last name (or family name) of the sender.
`{...}.score`	Number	Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
`{...}.ethnicityAlt`	String	Second most likely ethnicity of the sender.	Ethnicities or diasporas
`{...}.ethnicity`	String	Most likely ethnicity of the sender.	Ethnicities or diasporas
`{...}.lifted`	Boolean	Indicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule.
`{...}.countryIso2`	String	Submitted country of origin of the sender, in ISO 3166-1 alpha-2 format.	Country of residence
`{...}.ethnicitiesTop`	Array	Top 10 most likely ethnicities of the sender, ordered from most likely to least likely.	Ethnicities or diasporas
`[{...}].firstLastNameGeoToDiaspora`	Object	Diaspora data for the receiver name.
`{...}.script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`{...}.id`	String	Unique identifier.
`{...}.firstName`	String	Submitted first name (or given name) of the receiver.
`{...}.lastName`	String	Submitted last name (or family name) of the receiver.
`{...}.score`	Number	Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
`{...}.ethnicityAlt`	String	Second most likely ethnicity of the receiver.	Ethnicities or diasporas
`{...}.ethnicity`	String	Most likely ethnicity of the receiver.	Ethnicities or diasporas
`{...}.lifted`	Boolean	Indicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule.
`{...}.countryIso2`	String	Submitted country of origin of the receiver, in ISO 3166-1 alpha-2 format.	Country of residence
`{...}.ethnicitiesTop`	Array	Top 10 most likely ethnicities of the receiver, ordered from most likely to least likely.	Ethnicities or diasporas

Code sample:

Names Corridor code sample for shell:

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/corridorBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"corridorFromTo":[{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstLastNameGeoFrom":{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Ada","lastName":"Lovelace","countryIso2":"GB"},"firstLastNameGeoTo":{"id":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Nicolas","lastName":"Tesla","countryIso2":"US"}}]}'

Body parameter:

{
  "corridorFromTo": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstLastNameGeoFrom": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "countryIso2": "GB"
      },
      "firstLastNameGeoTo": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
        "firstName": "Nicolas",
        "lastName": "Tesla",
        "countryIso2": "US"
      }
    }
  ]
}

The above command returns JSON structured like this:

{
    "corridorFromTo": [
        {
            "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
            "firstLastNameGeoFromGender": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
                "firstName": "Ada",
                "lastName": "Lovelace",
                "likelyGender": "female",
                "genderScale": 0.9667738179638148,
                "score": 20.98847600479561,
                "probabilityCalibrated": 0.9833869089819074
            },
            "firstLastNameGeoToGender": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
                "firstName": "Nicolas",
                "lastName": "Tesla",
                "likelyGender": "male",
                "genderScale": -0.9915797101926913,
                "score": 30.224379416275056,
                "probabilityCalibrated": 0.9957898550963457
            },
            "firstLastNameGeoFromOrigin": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
                "firstName": "Ada",
                "lastName": "Lovelace",
                "countryOrigin": "IE",
                "countryOriginAlt": "GB",
                "countriesOriginTop": ["IE", "GB"],
                "score": 2.568304424015469,
                "regionOrigin": "Europe",
                "topRegionOrigin": "Europe",
                "subRegionOrigin": "Northern Europe",
                "probabilityCalibrated": 0.45562779224760414,
                "probabilityAltCalibrated": 0.6327518248452595
            },
            "firstLastNameGeoToOrigin": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
                "firstName": "Nicolas",
                "lastName": "Tesla",
                "countryOrigin": "FR",
                "countryOriginAlt": "GR",
                "countriesOriginTop": ["FR", "GR"],
                "score": 1.454789764445522,
                "regionOrigin": "Europe",
                "topRegionOrigin": "Europe",
                "subRegionOrigin": "Western Europe",
                "probabilityCalibrated": 0.44774495967210787,
                "probabilityAltCalibrated": 0.4771001024099368
            },
            "firstLastNameGeoFromDiaspora": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
                "firstName": "Ada",
                "lastName": "Lovelace",
                "score": 32.41686703300403,
                "ethnicityAlt": "TrinidadTobago",
                "ethnicity": "British",
                "lifted": false,
                "countryIso2": "GB",
                "ethnicitiesTop": ["British", "TrinidadTobago"]
            },
            "firstLastNameGeoToDiaspora": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
                "firstName": "Nicolas",
                "lastName": "Tesla",
                "score": 1.1421954239282939,
                "ethnicityAlt": "Jewish",
                "ethnicity": "Italian",
                "lifted": false,
                "countryIso2": "US",
                "ethnicitiesTop": ["Italian", "Jewish"]
            }
        }
    ]
}

Names Corridor code sample for java:

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

Body parameter:

{
  "corridorFromTo": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstLastNameGeoFrom": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "countryIso2": "GB"
      },
      "firstLastNameGeoTo": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
        "firstName": "Nicolas",
        "lastName": "Tesla",
        "countryIso2": "US"
      }
    }
  ]
}

The above command returns JSON structured like this:

{
    "corridorFromTo": [
        {
            "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
            "firstLastNameGeoFromGender": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
                "firstName": "Ada",
                "lastName": "Lovelace",
                "likelyGender": "female",
                "genderScale": 0.9667738179638148,
                "score": 20.98847600479561,
                "probabilityCalibrated": 0.9833869089819074
            },
            "firstLastNameGeoToGender": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
                "firstName": "Nicolas",
                "lastName": "Tesla",
                "likelyGender": "male",
                "genderScale": -0.9915797101926913,
                "score": 30.224379416275056,
                "probabilityCalibrated": 0.9957898550963457
            },
            "firstLastNameGeoFromOrigin": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
                "firstName": "Ada",
                "lastName": "Lovelace",
                "countryOrigin": "IE",
                "countryOriginAlt": "GB",
                "countriesOriginTop": ["IE", "GB"],
                "score": 2.568304424015469,
                "regionOrigin": "Europe",
                "topRegionOrigin": "Europe",
                "subRegionOrigin": "Northern Europe",
                "probabilityCalibrated": 0.45562779224760414,
                "probabilityAltCalibrated": 0.6327518248452595
            },
            "firstLastNameGeoToOrigin": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
                "firstName": "Nicolas",
                "lastName": "Tesla",
                "countryOrigin": "FR",
                "countryOriginAlt": "GR",
                "countriesOriginTop": ["FR", "GR"],
                "score": 1.454789764445522,
                "regionOrigin": "Europe",
                "topRegionOrigin": "Europe",
                "subRegionOrigin": "Western Europe",
                "probabilityCalibrated": 0.44774495967210787,
                "probabilityAltCalibrated": 0.4771001024099368
            },
            "firstLastNameGeoFromDiaspora": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
                "firstName": "Ada",
                "lastName": "Lovelace",
                "score": 32.41686703300403,
                "ethnicityAlt": "TrinidadTobago",
                "ethnicity": "British",
                "lifted": false,
                "countryIso2": "GB",
                "ethnicitiesTop": ["British", "TrinidadTobago"]
            },
            "firstLastNameGeoToDiaspora": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
                "firstName": "Nicolas",
                "lastName": "Tesla",
                "score": 1.1421954239282939,
                "ethnicityAlt": "Jewish",
                "ethnicity": "Italian",
                "lifted": false,
                "countryIso2": "US",
                "ethnicitiesTop": ["Italian", "Jewish"]
            }
        }
    ]
}

Names Corridor code sample for python:

import requests

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

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

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

print(response.text)

Body parameter:

{
  "corridorFromTo": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstLastNameGeoFrom": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "countryIso2": "GB"
      },
      "firstLastNameGeoTo": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
        "firstName": "Nicolas",
        "lastName": "Tesla",
        "countryIso2": "US"
      }
    }
  ]
}

The above command returns JSON structured like this:

{
    "corridorFromTo": [
        {
            "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
            "firstLastNameGeoFromGender": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
                "firstName": "Ada",
                "lastName": "Lovelace",
                "likelyGender": "female",
                "genderScale": 0.9667738179638148,
                "score": 20.98847600479561,
                "probabilityCalibrated": 0.9833869089819074
            },
            "firstLastNameGeoToGender": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
                "firstName": "Nicolas",
                "lastName": "Tesla",
                "likelyGender": "male",
                "genderScale": -0.9915797101926913,
                "score": 30.224379416275056,
                "probabilityCalibrated": 0.9957898550963457
            },
            "firstLastNameGeoFromOrigin": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
                "firstName": "Ada",
                "lastName": "Lovelace",
                "countryOrigin": "IE",
                "countryOriginAlt": "GB",
                "countriesOriginTop": ["IE", "GB"],
                "score": 2.568304424015469,
                "regionOrigin": "Europe",
                "topRegionOrigin": "Europe",
                "subRegionOrigin": "Northern Europe",
                "probabilityCalibrated": 0.45562779224760414,
                "probabilityAltCalibrated": 0.6327518248452595
            },
            "firstLastNameGeoToOrigin": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
                "firstName": "Nicolas",
                "lastName": "Tesla",
                "countryOrigin": "FR",
                "countryOriginAlt": "GR",
                "countriesOriginTop": ["FR", "GR"],
                "score": 1.454789764445522,
                "regionOrigin": "Europe",
                "topRegionOrigin": "Europe",
                "subRegionOrigin": "Western Europe",
                "probabilityCalibrated": 0.44774495967210787,
                "probabilityAltCalibrated": 0.4771001024099368
            },
            "firstLastNameGeoFromDiaspora": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
                "firstName": "Ada",
                "lastName": "Lovelace",
                "score": 32.41686703300403,
                "ethnicityAlt": "TrinidadTobago",
                "ethnicity": "British",
                "lifted": false,
                "countryIso2": "GB",
                "ethnicitiesTop": ["British", "TrinidadTobago"]
            },
            "firstLastNameGeoToDiaspora": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
                "firstName": "Nicolas",
                "lastName": "Tesla",
                "score": 1.1421954239282939,
                "ethnicityAlt": "Jewish",
                "ethnicity": "Italian",
                "lifted": false,
                "countryIso2": "US",
                "ethnicitiesTop": ["Italian", "Jewish"]
            }
        }
    ]
}

Names Corridor code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/corridorBatch", {
  "method": "POST",
  "headers": {
    "X-API-KEY": "your-api-key",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "body": JSON.stringify({
  "corridorFromTo": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstLastNameGeoFrom": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "countryIso2": "GB"
      },
      "firstLastNameGeoTo": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
        "firstName": "Nicolas",
        "lastName": "Tesla",
        "countryIso2": "US"
      }
    }
  ]
})
});

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

Body parameter:

{
  "corridorFromTo": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstLastNameGeoFrom": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "countryIso2": "GB"
      },
      "firstLastNameGeoTo": {
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
        "firstName": "Nicolas",
        "lastName": "Tesla",
        "countryIso2": "US"
      }
    }
  ]
}

The above command returns JSON structured like this:

{
    "corridorFromTo": [
        {
            "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
            "firstLastNameGeoFromGender": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
                "firstName": "Ada",
                "lastName": "Lovelace",
                "likelyGender": "female",
                "genderScale": 0.9667738179638148,
                "score": 20.98847600479561,
                "probabilityCalibrated": 0.9833869089819074
            },
            "firstLastNameGeoToGender": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
                "firstName": "Nicolas",
                "lastName": "Tesla",
                "likelyGender": "male",
                "genderScale": -0.9915797101926913,
                "score": 30.224379416275056,
                "probabilityCalibrated": 0.9957898550963457
            },
            "firstLastNameGeoFromOrigin": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
                "firstName": "Ada",
                "lastName": "Lovelace",
                "countryOrigin": "IE",
                "countryOriginAlt": "GB",
                "countriesOriginTop": ["IE", "GB"],
                "score": 2.568304424015469,
                "regionOrigin": "Europe",
                "topRegionOrigin": "Europe",
                "subRegionOrigin": "Northern Europe",
                "probabilityCalibrated": 0.45562779224760414,
                "probabilityAltCalibrated": 0.6327518248452595
            },
            "firstLastNameGeoToOrigin": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
                "firstName": "Nicolas",
                "lastName": "Tesla",
                "countryOrigin": "FR",
                "countryOriginAlt": "GR",
                "countriesOriginTop": ["FR", "GR"],
                "score": 1.454789764445522,
                "regionOrigin": "Europe",
                "topRegionOrigin": "Europe",
                "subRegionOrigin": "Western Europe",
                "probabilityCalibrated": 0.44774495967210787,
                "probabilityAltCalibrated": 0.4771001024099368
            },
            "firstLastNameGeoFromDiaspora": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
                "firstName": "Ada",
                "lastName": "Lovelace",
                "score": 32.41686703300403,
                "ethnicityAlt": "TrinidadTobago",
                "ethnicity": "British",
                "lifted": false,
                "countryIso2": "GB",
                "ethnicitiesTop": ["British", "TrinidadTobago"]
            },
            "firstLastNameGeoToDiaspora": {
                "script": "LATIN",
                "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
                "firstName": "Nicolas",
                "lastName": "Tesla",
                "score": 1.1421954239282939,
                "ethnicityAlt": "Jewish",
                "ethnicity": "Italian",
                "lifted": false,
                "countryIso2": "US",
                "ethnicitiesTop": ["Italian", "Jewish"]
            }
        }
    ]
}

Cost: 50 credits per name.
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).

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

GET

https://v2.namsor.com/NamSorAPIv2/api2/json/corridor/{countryIso2}/{firstName}/{lastName}/{countryIso2}/{firstName}/{lastName}

Request header
Property	Required	Description
`X-API-KEY`	Required	Your Namsor's services API key

To get an API key for free, please create an account.

Request parameters
Name	Type	Required	Description
`firstName`	String	Required	First name (or given name) of the sender.
`lastName`	String	Required	Last name (or family name) of the sender.
`countryIso2`	String	Required	Country of origin of the sender, in ISO 3166-1 alpha-2 format.
`firstName`	String	Required	First name (or given name) of the receiver.
`lastName`	String	Required	Last name (or family name) of the receiver.
`countryIso2`	String	Required	Country of origin of the receiver, in ISO 3166-1 alpha-2 format.

Response
Name	Type	Description	Enumerators
`id`	String	Unique identifier.
`firstLastNameGeoFromGender`	Object	Gender data for the sender name.
`script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`id`	String	Unique identifier.
`firstName`	String	Submitted first name (or given name) of the sender.
`lastName`	String	Submitted last name (or family name) of the sender.
`likelyGender`	String	Most likely gender.	Genders
`genderScale`	Number	Gender scale ranging from -1 (male) to +1 (female).
`score`	Number	Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
`probabilityCalibrated`	Number	Higher implies a more reliable result, ranges from 0 to 1.
`firstLastNameGeoToGender`	Object	Gender data for the receiver name.
`script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`id`	String	Unique identifier.
`firstName`	String	Submitted first name (or given name) of the receiver.
`lastName`	String	Submitted last name (or family name) of the receiver.
`likelyGender`	String	Most likely gender.	Genders
`genderScale`	Number	Gender scale ranging from -1 (male) to +1 (female).
`score`	Number	Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
`probabilityCalibrated`	Number	Higher implies a more reliable result, ranges from 0 to 1.
`firstLastNameGeoFromOrigin`	Object	Origin data for the sender name.
`script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`id`	String	Unique identifier.
`firstName`	String	Submitted first name (or given name) of the sender.
`lastName`	String	Submitted last name (or family name) of the sender.
`countryOrigin`	String	Most likely country of origin of the sender, in ISO 3166-1 alpha-2 format.	Country of origin
`countryOriginAlt`	String	Second most likely country of origin of the sender, in ISO 3166-1 alpha-2 format.	Country of origin
`countriesOriginTop`	Array	Top 10 most likely countries of origin of the sender, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely.	Country of origin
`score`	Number	Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
`regionOrigin`	String	Most likely region of origin of the sender.	Regions of origin or residence
`topRegionOrigin`	String	Most likely region of origin of the sender (alternative classification).	Regions of origin or residence
`subRegionOrigin`	String	Most likely sub-region of origin of the sender.	Sub regions of origin or residence
`probabilityCalibrated`	Number	The calibrated probability for countryOrigin to have been guessed correctly. -1 = still calibrating.
`probabilityAltCalibrated`	Number	The calibrated probability for countryOrigin OR countryOriginAlt to have been guessed correctly. -1 = still calibrating.
`firstLastNameGeoToOrigin`	Object	Origin data for the receiver name.
`script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`id`	String	Unique identifier.
`firstName`	String	Submitted first name (or given name) of the receiver.
`lastName`	String	Submitted last name (or family name) of the receiver.
`countryOrigin`	String	Most likely country of origin of the receiver, in ISO 3166-1 alpha-2 format.	Country of origin
`countryOriginAlt`	String	Second most likely country of origin of the receiver, in ISO 3166-1 alpha-2 format.	Country of origin
`countriesOriginTop`	Array	Top 10 most likely countries of origin of the receiver, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely.	Country of origin
`score`	Number	Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
`regionOrigin`	String	Most likely region of origin.	Regions of origin or residence
`topRegionOrigin`	String	Most likely region of origin of the receiver (alternative classification).	Regions of origin or residence
`subRegionOrigin`	String	Most likely sub-region of origin of the receiver.	Sub regions of origin or residence
`probabilityCalibrated`	Number	The calibrated probability for countryOrigin to have been guessed correctly. -1 = still calibrating.
`probabilityAltCalibrated`	Number	The calibrated probability for countryOrigin OR countryOriginAlt to have been guessed correctly. -1 = still calibrating.
`firstLastNameGeoFromDiaspora`	Object	Diaspora data for the sender name.
`script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`id`	String	Unique identifier.
`firstName`	String	Submitted first name (or given name) of the sender.
`lastName`	String	Submitted last name (or family name) of the sender.
`score`	Number	Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
`ethnicityAlt`	String	Second most likely ethnicity of the sender.	Ethnicities or diasporas
`ethnicity`	String	Most likely ethnicity of the sender.	Ethnicities or diasporas
`lifted`	Boolean	Indicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule.
`countryIso2`	String	Submitted country of origin of the sender, in ISO 3166-1 alpha-2 format.	Country of residence
`ethnicitiesTop`	Array	Top 10 most likely ethnicities of the sender, ordered from most likely to least likely.	Ethnicities or diasporas
`firstLastNameGeoToDiaspora`	Object	Diaspora data for the receiver name.
`script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`id`	String	Unique identifier.
`firstName`	String	Submitted first name (or given name) of the receiver.
`lastName`	String	Submitted last name (or family name) of the receiver.
`score`	Number	Higher implies a more reliable result, but score is not normalized. Use probabilityCalibrated if available.
`ethnicityAlt`	String	Second most likely ethnicity of the receiver.	Ethnicities or diasporas
`ethnicity`	String	Most likely ethnicity of the receiver.	Ethnicities or diasporas
`lifted`	Boolean	Indicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule.
`countryIso2`	String	Submitted country of origin of the receiver, in ISO 3166-1 alpha-2 format.	Country of residence
`ethnicitiesTop`	Array	Top 10 most likely ethnicities of the receiver, ordered from most likely to least likely.	Ethnicities or diasporas

Code sample:

Names Corridor code sample for shell:

curl --request 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": "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.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": "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/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": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
    "firstLastNameGeoFromGender": {
        "script": "LATIN",
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "likelyGender": "female",
        "genderScale": 0.9667738179638148,
        "score": 20.98847600479561,
        "probabilityCalibrated": 0.9833869089819074
    },
    "firstLastNameGeoToGender": {
        "script": "LATIN",
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
        "firstName": "Nicolas",
        "lastName": "Tesla",
        "likelyGender": "male",
        "genderScale": -0.9915797101926913,
        "score": 30.224379416275056,
        "probabilityCalibrated": 0.9957898550963457
    },
    "firstLastNameGeoFromOrigin": {
        "script": "LATIN",
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "countryOrigin": "IE",
        "countryOriginAlt": "GB",
        "countriesOriginTop": ["IE", "GB"],
        "score": 2.568304424015469,
        "regionOrigin": "Europe",
        "topRegionOrigin": "Europe",
        "subRegionOrigin": "Northern Europe",
        "probabilityCalibrated": 0.45562779224760414,
        "probabilityAltCalibrated": 0.6327518248452595
    },
    "firstLastNameGeoToOrigin": {
        "script": "LATIN",
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
        "firstName": "Nicolas",
        "lastName": "Tesla",
        "countryOrigin": "FR",
        "countryOriginAlt": "GR",
        "countriesOriginTop": ["FR", "GR"],
        "score": 1.454789764445522,
        "regionOrigin": "Europe",
        "topRegionOrigin": "Europe",
        "subRegionOrigin": "Western Europe",
        "probabilityCalibrated": 0.44774495967210787,
        "probabilityAltCalibrated": 0.4771001024099368
    },
    "firstLastNameGeoFromDiaspora": {
        "script": "LATIN",
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c43",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "score": 32.41686703300403,
        "ethnicityAlt": "TrinidadTobago",
        "ethnicity": "British",
        "lifted": false,
        "countryIso2": "GB",
        "ethnicitiesTop": ["British", "TrinidadTobago"]
    },
    "firstLastNameGeoToDiaspora": {
        "script": "LATIN",
        "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c41",
        "firstName": "Nicolas",
        "lastName": "Tesla",
        "score": 1.1421954239282939,
        "ethnicityAlt": "Jewish",
        "ethnicity": "Italian",
        "lifted": false,
        "countryIso2": "US",
        "ethnicitiesTop": ["Italian", "Jewish"]
    }
}

Names Corridor code sample for javascript:

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

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

The above command returns JSON structured like this:

{
    "id": "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"]
    }
}