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

U.S. race ethnicity API – Classify names according to the US Census taxonomy

Namsor's US Race Ethnicity API predicts the most likely race and ethnicity classification of a person according to the standards set by the United States Census taxonomy. You can submit a name as either a full string or in the form of first and last name. Our system handles both formats with ease, making integration simple and flexible.

This API is particularly valuable for organizations working on diversity analytics, public policy, compliance, and research projects in the United States. It maps names to official demographic categories such as White, Black or African American, Asian, Hispanic or Latino, American Indian or Alaska Native, and others. Powered by extensive U.S. datasets and advanced name recognition algorithms, Namsor delivers accurate and ethical ethnicity classification while maintaining strict privacy standards.

600+Research contributions

99.99%Names availability

11B billionsNames processed

Name US Race

US race from first name (optional), last name (optional), country code (optional).

Select a taxonomy :

4 classes6 classes

For international names (non US resident) please choose 4 classes. Enumerators for the returned 'race' ethnicity. US race enumerators.

First name (Optional)

Last name (Optional)

Country code (Optional)

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

Name US Race analyzes a first name and/or last name to determine the most likely US race, with slightly higher accuracy than the Full Name US Race feature. Providing both a full name and a country of residence enhances accuracy. US race ethnicity refers to classifications defined by the United States Census Taxonomy.

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

HTTP request

POST

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

Request header
Property	Values	Required	Description
`X-API-KEY`		Required	Your Namsor's services API key
`X-OPTION-USRACEETHNICITY-TAXONOMY`	`USRACEETHNICITY-6CLASSES`	Optional	Enumerators for the returned 'race' ethnicity. Do not specify the property of the http request to obtain 4 classes W_NL, HL, A, B_NL. `USRACEETHNICITY-6CLASSES` will return 6 classes W_NL, HL, A, B_NL, AI_AN, PI. For international names (non US resident) please choose 4 classes.

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 with their country of residence.
`[{...}].id`	String	Optional	Unique identifier.
`[{...}].firstName`	String	Optional	First name, given name, nickname.
`[{...}].lastName`	String	Optional	Last name, family name, surname.
`[{...}].countryIso2`	String	Optional	Country of residence, in ISO 3166-1 alpha-2 format.

Response
Name	Type	Description	Enumerators
`personalNames`	Array of objects	List of submitted names with their race.
`[{...}].script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`[{...}].id`	String	Provided unique identifier.
`[{...}].firstName`	String	Submitted first name.
`[{...}].lastName`	String	Submitted last name.
`[{...}].raceEthnicityAlt`	String	Second most likely race (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`[{...}].raceEthnicity`	String	Most likely race (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`[{...}].score`	Number	Higher implies a more reliable result, score is not normalized.
`[{...}].raceEthnicitiesTop`	Array	Most likely race, sorted from most likely to least likely (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`[{...}].probabilityCalibrated`	Number	The calibrated probability that raceEthnicity has been guessed correctly. -1 = still calibrating.
`[{...}].probabilityAltCalibrated`	Number	The calibrated probability that raceEthnicity OR raceEthnicityAlt have been guessed correctly. -1 = still calibrating.

Code sample:

Name US Race code sample for shell:

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"85dd5f48-b9e1-4019-88ce-ccc7e56b763f","firstName":"Keith","lastName":"Haring","countryIso2":"US"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
            "firstName": "Keith",
            "lastName": "Haring",
            "raceEthnicityAlt": "B_NL",
            "raceEthnicity": "W_NL",
            "score": 3.9546190943560813,
            "raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
            "probabilityCalibrated": 0.619185913005526,
            "probabilityAltCalibrated": 0.7534347105665851
        }
    ]
}

Name US Race code sample for java:

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

Body parameter:

{
  "personalNames": [
    {
      "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
            "firstName": "Keith",
            "lastName": "Haring",
            "raceEthnicityAlt": "B_NL",
            "raceEthnicity": "W_NL",
            "score": 3.9546190943560813,
            "raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
            "probabilityCalibrated": 0.619185913005526,
            "probabilityAltCalibrated": 0.7534347105665851
        }
    ]
}

Name US Race code sample for python:

import requests

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

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

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

print(response.text)

Body parameter:

{
  "personalNames": [
    {
      "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
            "firstName": "Keith",
            "lastName": "Haring",
            "raceEthnicityAlt": "B_NL",
            "raceEthnicity": "W_NL",
            "score": 3.9546190943560813,
            "raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
            "probabilityCalibrated": 0.619185913005526,
            "probabilityAltCalibrated": 0.7534347105665851
        }
    ]
}

Name US Race code sample for javascript:

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

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

Body parameter:

{
  "personalNames": [
    {
      "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
            "firstName": "Keith",
            "lastName": "Haring",
            "raceEthnicityAlt": "B_NL",
            "raceEthnicity": "W_NL",
            "score": 3.9546190943560813,
            "raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
            "probabilityCalibrated": 0.619185913005526,
            "probabilityAltCalibrated": 0.7534347105665851
        }
    ]
}

Precision:
Cost: 10 credits per name.
Description: Returns the most likely US race 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/usRaceEthnicity/{firstName}/{lastName}

Request header
Property	Values	Required	Description
`X-API-KEY`		Required	Your Namsor's services API key
`X-OPTION-USRACEETHNICITY-TAXONOMY`	`USRACEETHNICITY-6CLASSES`	Optional	Enumerators for the returned 'race' ethnicity. Do not specify the property of the http request to obtain 4 classes W_NL, HL, A, B_NL. `USRACEETHNICITY-6CLASSES` will return 6 classes W_NL, HL, A, B_NL, AI_AN, PI. For international names (non US resident) please choose 4 classes.

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.
`countryIso2`	String	Required	Country of residence, in ISO 3166-1 alpha-2 format.

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.
`raceEthnicityAlt`	String	Second most likely race (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`raceEthnicity`	String	Most likely race (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`score`	Number	Higher implies a more reliable result, score is not normalized.
`raceEthnicitiesTop`	Array	Most likely race, sorted from most likely to least likely (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`probabilityCalibrated`	Number	The calibrated probability that raceEthnicity has been guessed correctly. -1 = still calibrating.
`probabilityAltCalibrated`	Number	The calibrated probability that raceEthnicity OR raceEthnicityAlt have been guessed correctly. -1 = still calibrating.

Code sample:

Name US Race code sample for shell:

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

The above command returns JSON structured like this:

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

Name US Race code sample for java:

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

The above command returns JSON structured like this:

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

Name US Race code sample for python:

import requests

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

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

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

print(response.text)

The above command returns JSON structured like this:

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

Name US Race code sample for javascript:

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

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

The above command returns JSON structured like this:

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

Full Name US Race

US race from full name , country code (optional).

Select a taxonomy :

4 classes6 classes

For international names (non US resident) please choose 4 classes. Enumerators for the returned 'race' ethnicity. US race enumerators.

Full name

Country code (Optional)

{
    "script": "LATIN",
    "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
    "name": "Keith Haring",
    "raceEthnicityAlt": "B_NL",
    "raceEthnicity": "W_NL",
    "score": 6.493299531249249,
    "raceEthnicitiesTop": [
        "W_NL", "B_NL", "A", "HL"
    ],
    "probabilityCalibrated": 0.7239234645232184,
    "probabilityAltCalibrated": 0.8814496032861949
}

Name US Race ZIP builds upon the basic Name US Race feature by incorporating ZIP code data to improve accuracy. It analyzes a first name and/or last name—optionally with a country of residence—to identify the most likely US race ethnicity. US race ethnicity refers to classifications defined by the United States Census Taxonomy.

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

HTTP request

POST

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

Request header
Property	Values	Required	Description
`X-API-KEY`		Required	Your Namsor's services API key
`X-OPTION-USRACEETHNICITY-TAXONOMY`	`USRACEETHNICITY-6CLASSES`	Optional	Enumerators for the returned 'race' ethnicity. Do not specify the property of the http request to obtain 4 classes W_NL, HL, A, B_NL. `USRACEETHNICITY-6CLASSES` will return 6 classes W_NL, HL, A, B_NL, AI_AN, PI. For international names (non US resident) please choose 4 classes.

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 full names with their country of residence.
`[{...}].id`	String	Optional	Unique identifier.
`[{...}].name`	String	Required	Unsplit full name (first name and last name).
`[{...}].countryIso2`	String	Optional	Country of residence, in ISO 3166-1 alpha-2 format.

Response
Name	Type	Description	Enumerators
`personalNames`	Array of objects	List of submitted full names with their race.
`[{...}].script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`[{...}].id`	String	Provided unique identifier.
`[{...}].name`	String	Submitted full name.
`[{...}].raceEthnicityAlt`	String	Second most likely race (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`[{...}].raceEthnicity`	String	Most likely race (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`[{...}].score`	Number	Higher implies a more reliable result, score is not normalized.
`[{...}].raceEthnicitiesTop`	Array	Most likely race, sorted from most likely to least likely (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`[{...}].probabilityCalibrated`	Number	The calibrated probability that raceEthnicity has been guessed correctly. -1 = still calibrating.
`[{...}].probabilityAltCalibrated`	Number	The calibrated probability that raceEthnicity OR raceEthnicityAlt have been guessed correctly. -1 = still calibrating.

Code sample:

Full Name US Race code sample for shell:

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/usRaceEthnicityFullBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"85dd5f48-b9e1-4019-88ce-ccc7e56b763f","name":"Keith Haring","countryIso2":"US"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
      "name": "Keith Haring",
      "countryIso2": "US"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
            "name": "Keith Haring",
            "raceEthnicityAlt": "B_NL",
            "raceEthnicity": "W_NL",
            "score": 6.493299531249249,
            "raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
            "probabilityCalibrated": 0.7239234645232184,
            "probabilityAltCalibrated": 0.8814496032861949
        }
    ]
}

Full Name US Race code sample for java:

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

Body parameter:

{
  "personalNames": [
    {
      "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
      "name": "Keith Haring",
      "countryIso2": "US"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
            "name": "Keith Haring",
            "raceEthnicityAlt": "B_NL",
            "raceEthnicity": "W_NL",
            "score": 6.493299531249249,
            "raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
            "probabilityCalibrated": 0.7239234645232184,
            "probabilityAltCalibrated": 0.8814496032861949
        }
    ]
}

Full Name US Race code sample for python:

import requests

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

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

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

print(response.text)

Body parameter:

{
  "personalNames": [
    {
      "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
      "name": "Keith Haring",
      "countryIso2": "US"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
            "name": "Keith Haring",
            "raceEthnicityAlt": "B_NL",
            "raceEthnicity": "W_NL",
            "score": 6.493299531249249,
            "raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
            "probabilityCalibrated": 0.7239234645232184,
            "probabilityAltCalibrated": 0.8814496032861949
        }
    ]
}

Full Name US Race code sample for javascript:

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

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

Body parameter:

{
  "personalNames": [
    {
      "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
      "name": "Keith Haring",
      "countryIso2": "US"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
            "name": "Keith Haring",
            "raceEthnicityAlt": "B_NL",
            "raceEthnicity": "W_NL",
            "score": 6.493299531249249,
            "raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
            "probabilityCalibrated": 0.7239234645232184,
            "probabilityAltCalibrated": 0.8814496032861949
        }
    ]
}

Precision:
Cost: 10 credits per name.
Description: Returns the most likely US race 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/usRaceEthnicityFull/{name}

Request header
Property	Values	Required	Description
`X-API-KEY`		Required	Your Namsor's services API key
`X-OPTION-USRACEETHNICITY-TAXONOMY`	`USRACEETHNICITY-6CLASSES`	Optional	Enumerators for the returned 'race' ethnicity. Do not specify the property of the http request to obtain 4 classes W_NL, HL, A, B_NL. `USRACEETHNICITY-6CLASSES` will return 6 classes W_NL, HL, A, B_NL, AI_AN, PI. For international names (non US resident) please choose 4 classes.

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).
`countryIso2`	String	Required	Country of residence, in ISO 3166-1 alpha-2 format.

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.
`raceEthnicityAlt`	String	Second most likely race (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`raceEthnicity`	String	Most likely race (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`score`	Number	Higher implies a more reliable result, score is not normalized.
`raceEthnicitiesTop`	Array	Most likely race, sorted from most likely to least likely (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`probabilityCalibrated`	Number	The calibrated probability that raceEthnicity has been guessed correctly. -1 = still calibrating.
`probabilityAltCalibrated`	Number	The calibrated probability that raceEthnicity OR raceEthnicityAlt have been guessed correctly. -1 = still calibrating.

Code sample:

Full Name US Race code sample for shell:

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

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
    "name": "Keith Haring",
    "raceEthnicityAlt": "B_NL",
    "raceEthnicity": "W_NL",
    "score": 6.493299531249249,
    "raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
    "probabilityCalibrated": 0.7239234645232184,
    "probabilityAltCalibrated": 0.8814496032861949
}

Full Name US Race code sample for java:

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

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
    "name": "Keith Haring",
    "raceEthnicityAlt": "B_NL",
    "raceEthnicity": "W_NL",
    "score": 6.493299531249249,
    "raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
    "probabilityCalibrated": 0.7239234645232184,
    "probabilityAltCalibrated": 0.8814496032861949
}

Full Name US Race code sample for python:

import requests

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

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

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

print(response.text)

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
    "name": "Keith Haring",
    "raceEthnicityAlt": "B_NL",
    "raceEthnicity": "W_NL",
    "score": 6.493299531249249,
    "raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
    "probabilityCalibrated": 0.7239234645232184,
    "probabilityAltCalibrated": 0.8814496032861949
}

Full Name US Race code sample for javascript:

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

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

The above command returns JSON structured like this:

{
    "script": "LATIN",
    "id": "85dd5f48-b9e1-4019-88ce-ccc7e56b763f",
    "name": "Keith Haring",
    "raceEthnicityAlt": "B_NL",
    "raceEthnicity": "W_NL",
    "score": 6.493299531249249,
    "raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
    "probabilityCalibrated": 0.7239234645232184,
    "probabilityAltCalibrated": 0.8814496032861949
}

Name US Race ZIP

US race from first name (optional), last name (optional), country code (optional), 5 digit zip code .

Select a taxonomy :

4 classes6 classes

For international names (non US resident) please choose 4 classes. Enumerators for the returned 'race' ethnicity. US race enumerators.

First name (Optional)

Last name (Optional)

Country code (Optional)

5 digit zip code

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

Full Name US Race analyzes an unsplit full name (first and last name combined) to determine the most likely US race ethnicity. US race ethnicity refers to classifications defined by the United States Census Taxonomy.

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

Precision:
Cost: 10 credits per name.
Description: Returns the most likely US race of up to 100 first names and/or last names using their ZIP code.
More about: Name US Race ZIP

HTTP request

POST

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

Request header
Property	Values	Required	Description
`X-API-KEY`		Required	Your Namsor's services API key
`X-OPTION-USRACEETHNICITY-TAXONOMY`	`USRACEETHNICITY-6CLASSES`	Optional	Enumerators for the returned 'race' ethnicity. Do not specify the property of the http request to obtain 4 classes W_NL, HL, A, B_NL. `USRACEETHNICITY-6CLASSES` will return 6 classes W_NL, HL, A, B_NL, AI_AN, PI. For international names (non US resident) please choose 4 classes.

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 with their country of residence and postal code.
`[{...}].id`	String	Optional	Unique identifier.
`[{...}].firstName`	String	Optional	First name, given name, nickname.
`[{...}].lastName`	String	Optional	Last name, family name, surname.
`[{...}].countryIso2`	String	Optional	Country of residence, in ISO 3166-1 alpha-2 format.
`[{...}].zipCode`	String	Required	Postal code (5-digit) of residence used by the United States Postal Service (USPS).

Response
Name	Type	Description	Enumerators
`personalNames`	Array of objects	List of submitted names with their race.
`[{...}].script`	String	Name of the script used for the name, in ISO 15924 format.	Script
`[{...}].id`	String	Provided unique identifier.
`[{...}].firstName`	String	Submitted first name.
`[{...}].lastName`	String	Submitted last name.
`[{...}].raceEthnicityAlt`	String	Second most likely race (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`[{...}].raceEthnicity`	String	Most likely race (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`[{...}].score`	Number	Higher implies a more reliable result, score is not normalized.
`[{...}].raceEthnicitiesTop`	Array	Most likely race, sorted from most likely to least likely (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`[{...}].probabilityCalibrated`	Number	The calibrated probability that raceEthnicity has been guessed correctly. -1 = still calibrating.
`[{...}].probabilityAltCalibrated`	Number	The calibrated probability that raceEthnicity OR raceEthnicityAlt have been guessed correctly. -1 = still calibrating.

Code sample:

Name US Race ZIP code sample for shell:

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/usZipRaceEthnicityBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"728767f9-c5b2-4ed3-a071-828077f16552","firstName":"Keith","lastName":"Haring","countryIso2":"US","zipCode":"10019"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "728767f9-c5b2-4ed3-a071-828077f16552",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US",
      "zipCode": "10019"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "728767f9-c5b2-4ed3-a071-828077f16552",
            "firstName": "Keith",
            "lastName": "Haring",
            "raceEthnicityAlt": "B_NL",
            "raceEthnicity": "W_NL",
            "score": 3.9546190943560813,
            "raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
            "probabilityCalibrated": 0.619185913005526,
            "probabilityAltCalibrated": 0.7534347105665851
        }
    ]
}

Name US Race ZIP code sample for java:

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

Body parameter:

{
  "personalNames": [
    {
      "id": "728767f9-c5b2-4ed3-a071-828077f16552",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US",
      "zipCode": "10019"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "728767f9-c5b2-4ed3-a071-828077f16552",
            "firstName": "Keith",
            "lastName": "Haring",
            "raceEthnicityAlt": "B_NL",
            "raceEthnicity": "W_NL",
            "score": 3.9546190943560813,
            "raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
            "probabilityCalibrated": 0.619185913005526,
            "probabilityAltCalibrated": 0.7534347105665851
        }
    ]
}

Name US Race ZIP code sample for python:

import requests

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

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

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

print(response.text)

Body parameter:

{
  "personalNames": [
    {
      "id": "728767f9-c5b2-4ed3-a071-828077f16552",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US",
      "zipCode": "10019"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "728767f9-c5b2-4ed3-a071-828077f16552",
            "firstName": "Keith",
            "lastName": "Haring",
            "raceEthnicityAlt": "B_NL",
            "raceEthnicity": "W_NL",
            "score": 3.9546190943560813,
            "raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
            "probabilityCalibrated": 0.619185913005526,
            "probabilityAltCalibrated": 0.7534347105665851
        }
    ]
}

Name US Race ZIP code sample for javascript:

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

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

Body parameter:

{
  "personalNames": [
    {
      "id": "728767f9-c5b2-4ed3-a071-828077f16552",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US",
      "zipCode": "10019"
    }
  ]
}

The above command returns JSON structured like this:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "728767f9-c5b2-4ed3-a071-828077f16552",
            "firstName": "Keith",
            "lastName": "Haring",
            "raceEthnicityAlt": "B_NL",
            "raceEthnicity": "W_NL",
            "score": 3.9546190943560813,
            "raceEthnicitiesTop": ["W_NL", "B_NL", "A", "HL"],
            "probabilityCalibrated": 0.619185913005526,
            "probabilityAltCalibrated": 0.7534347105665851
        }
    ]
}

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

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/usRaceEthnicityZIP5/{firstName}/{lastName}/{zipCode}

Request header
Property	Values	Required	Description
`X-API-KEY`		Required	Your Namsor's services API key
`X-OPTION-USRACEETHNICITY-TAXONOMY`	`USRACEETHNICITY-6CLASSES`	Optional	Enumerators for the returned 'race' ethnicity. Do not specify the property of the http request to obtain 4 classes W_NL, HL, A, B_NL. `USRACEETHNICITY-6CLASSES` will return 6 classes W_NL, HL, A, B_NL, AI_AN, PI. For international names (non US resident) please choose 4 classes.

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.
`countryIso2`	String	Required	Country of residence, in ISO 3166-1 alpha-2 format.
`zipCode`	String	Required	Postal code (5-digit) of residence used by the United States Postal Service (USPS).

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.
`raceEthnicityAlt`	String	Second most likely race (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`raceEthnicity`	String	Most likely race (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`score`	Number	Higher implies a more reliable result, score is not normalized.
`raceEthnicitiesTop`	Array	Most likely race, sorted from most likely to least likely (US race categorization from US Census Taxonomy).	U.S. race ethnicities
`probabilityCalibrated`	Number	The calibrated probability that raceEthnicity has been guessed correctly. -1 = still calibrating.
`probabilityAltCalibrated`	Number	The calibrated probability that raceEthnicity OR raceEthnicityAlt have been guessed correctly. -1 = still calibrating.

Code sample:

Name US Race ZIP code sample for shell:

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

The above command returns JSON structured like this:

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

Name US Race ZIP code sample for java:

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

The above command returns JSON structured like this:

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

Name US Race ZIP code sample for python:

import requests

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

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

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

print(response.text)

The above command returns JSON structured like this:

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

Name US Race ZIP code sample for javascript:

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

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

The above command returns JSON structured like this:

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