API version:

API key:

API documentation

Introduction

Origin from a name

Name origin
Origin from first names (optional), last names (optional).

Ethnicity from a name

Name diaspora
Diaspora from first names (optional), last names (optional), country codes (optional).
Name US race
US race ethnicity from first names (optional), last names (optional), country codes (optional).
Name US race ZIP
US race ethnicity from first names (optional), last names (optional), country codes (optional), 5 digit zip codes .

Country of residence from a name

Name country
Residence country from names .

Gender from a name

Name gender
Gender from first names , last names (optional).
Name gender ISO
Gender from first names , last names (optional), country codes .

Admin

API documentation

Ethnicity Estimate is powered by Namsor. Namsor has developed a name checking technology, able to create comprehensive analysis through multiple processing. Our API can classify names by origin, by ethnicity, by residence country, by gender, and supports many alphabets*.

Introduction

About

The base endpoint URL is: https://v2.namsor.com/NamSorAPIv2
All endpoints require an API Key.
Never share your API key to ANYONE.

API Requests and Responses

All endpoints return JSON containing either an object or a nested array of objects.
Currently certain NamSor API endpoints use nested object structures in their query body and / or responses, please refer yourself to the corresponding code example.
Be aware that data in the code examples have been URL encoded into the corresponding ASCII code characters when necessary, for example 谢晓亮 is replaced by %E8%B0%A2%E6%99%93%E4%BA%AE. URLs cannot contain spaces or non-ASCII characters. When making GET requests to the API use URL encoding to convert non-ASCII characters into a format that can be transmitted over the internet.

Data Privacy

By default Namsor’s machine learning algorithm may improve data evaluation based on the data inputs and does store logs of submitted request. You may change these setting either in your user account or by calling the dedicated API endpoints. All data logs are secured using AES encryption before being stored.

If you wish to disable machine learning based on your submissions, please set learnable to false by using the corresponding Admin route. When set to false for an API key, the data processed using that key will not feed the machine learning algorithm.

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

Authentication

API Key Creation

Customer accounts are common to all Namsor group websites. To create an API key visit Ethnicity Estimate or another site of the Namsor group and create an account. Navigate to the account information page to retrieve your API key. Your newly created account comes with 500 free credits that you may use immediately with any of Ethnicity Estimate's tools: API, CSV and Excel file processor or Developer tools.

API Key Installation

Your API key must be set in the header of your request using the X-API-KEY property. Please refer yourself to the provided code samples for correct key installation.

You must replace your-api-key with your Namsor API key.

Credits

What are Credits

We use a credit system to track usage. Each plan comes with a monthly quantity of credits and a price for request that exceed your monthly allowance. The free Basic subscription plan grants you 500 credits but other plans are available in case you have higher requirements. As an example, with 500 credits you can either :

Process 50 names to determine their origins.
Process 25 names to determine their ethnicities.
Process 50 names to determine their U.S. race ethncities.
Process 50 names to determine their countries of residence.
Process 500 names to determine their genders.

Admin routes are free.

Repeated Operations Tolerance

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

Soft Limit vs Hard Limit

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

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

Track Usage

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

Errors

The NamSor API uses the following error codes:

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

Country of origin from a name

Our artificial intelligence is based on the morphology of names to determine their origins. This is why we can identify a first name origin, a last name origin, a full name origin and even the country of origin of a nickname or an invented name. Finally our functionality supports 22 alphabets and 192 countries of origin.

Name origin

POST

Description: Returns the most likely country of origin of up to 100 first names and/or last names. Note that the "Diaspora" endpoint may be better suited for countries like U.S.A, Canada, Australia, New-Zealand and other melting-pots.
Cost: 10 credits per name.
Test: name origin feature.

HTTP request

POST

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

Request header

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

Request body

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

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

Response

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

Name	Type	Description	Enumerators
personalNames	Array of objects	List of submitted names with their countries of origin
[{...}].script	String	Character set used for analysis	Alphabets
[{...}].id	String	Provided unique identifier
[{...}].firstName	String	Submitted first name, given name or nickname
[{...}].lastName	String	Submitted last name, family name or surname
[{...}].countryOrigin	String	Most likely country of origin, in ISO 3166-1 alpha-2 format	Country of origin
[{...}].countryOriginAlt	String	Second most likely country of origin, in ISO 3166-1 alpha-2 format	Country of origin
[{...}].countriesOriginTop	Array	Top 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely	Country of origin
[{...}].score	Number	Higher implies a more reliable result, score is not normalized
[{...}].regionOrigin	String	Most likely region of origin
[{...}].topRegionOrigin	String	Most likely region of origin (alternative classification)
[{...}].subRegionOrigin	String	Most likely subregion of origin
[{...}].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.

Code sample

name origin code sample for shell :

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

Body parameter:

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

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Zanele",
      "lastName": "Muholi",
      "countryOrigin": "ZA",
      "countryOriginAlt": "LS",
      "countriesOriginTop": [
        "ZA",
        "LS",
        "NA",
        "CD",
        "ZW",
        "TZ",
        "AL",
        "RW",
        "IT",
        "KE"
      ],
      "score": 14.109780317889099,
      "regionOrigin": "Africa",
      "topRegionOrigin": "Africa",
      "subRegionOrigin": "Southern Africa",
      "probabilityCalibrated": 0.7807734140304999,
      "probabilityAltCalibrated": 0.8559822288694453
    }
  ]
}

Ethnicity from a name

Our artificial intelligence is based on the morphology of names to determine their ethnicities. This is why we can identify a full name ethnicity, a first name ethnicity, a last name ethnicity and even the ethnicity of a nickname or an invented name. Finally our functionality supports 136 ethnicities and 22 alphabets.

Name diaspora

POST

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

HTTP request

POST

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

Request header

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

Request body

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

Name	Type	Required	Description
personalNames	Array of objects	Required	A list of personal names
[{...}].id	String	Optional	Unique identifier
[{...}].firstName	String	Optional	First name or given name or nickname
[{...}].lastName	String	Optional	Last name or family name or surname
[{...}].countryIso2	String	Optional	Country of residence, in ISO 3166-1 alpha-2 format

Response

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

Name	Type	Description	Enumerators
personalNames	Array of objects	List of submitted names with their ethnicities
[{...}].script	String	Character set used for analysis	Alphabets
[{...}].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
[{...}].probabilityAltCalibrated	Number	The calibrated probability for ethnicity OR ethnicityAlt to have been guessed correctly. -1 = still calibrating.
[{...}].probabilityCalibrated	Number	The calibrated probability for ethnicity to have been guessed correctly. -1 = still calibrating.
[{...}].ethnicityAlt	String	Second most likely ethnicity	Ethnicities or diasporas
[{...}].ethnicity	String	Most likely ethnicity	Ethnicities or diasporas
[{...}].lifted	Boolean	Indicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule
[{...}].countryIso2	String	Submitted country of residence, in ISO 3166-1 alpha-2 format	Country of residence
[{...}].ethnicitiesTop	Array	Top 10 most likely ethnicities, order from most likely to least likely	Ethnicities or diasporas

Code sample

name diaspora code sample for shell :

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

Body parameter:

{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Subrahmanyan",
      "lastName": "Chandrasekhar",
      "countryIso2": "US"
    }
  ]
}

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Subrahmanyan",
      "lastName": "Chandrasekhar",
      "score": 36.039400468550376,
      "probabilityAltCalibrated": 0.9722023169712171,
      "probabilityCalibrated": 0.9722023169712171,
      "ethnicityAlt": "Pakistanese",
      "ethnicity": "Indian",
      "lifted": false,
      "countryIso2": "US",
      "ethnicitiesTop": [
        "Indian",
        "Pakistanese",
        "Bangladeshi",
        "SriLankan",
        "Chinese",
        "Malays",
        "Cambodian",
        "TrinidadTobago",
        "Indonesian",
        "NativeHawaiian"
      ]
    }
  ]
}

Name US race

POST

Description: Returns the most likely U.S. race or ethnicity from up to 100 first names and/or last names.
Precision:
Cost: 10 credits per name.
Test: name US race feature.

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

Request body

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

Name	Type	Required	Description
personalNames	Array of objects	Required	A list of personal names
[{...}].id	String	Optional	Unique identifier
[{...}].firstName	String	Optional	First name or given name or nickname
[{...}].lastName	String	Optional	Last name or family name or surname
[{...}].countryIso2	String	Optional	Most likely country of residence, in ISO 3166-1 alpha-2 format

Response

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

Name	Type	Description	Enumerators
personalNames	Array of objects	List of submitted names with their race ethnicity
[{...}].script	String	Character set used for analysis	Alphabets
[{...}].id	String	Provided unique identifier
[{...}].firstName	String	Submitted first name
[{...}].lastName	String	Submitted last name
[{...}].raceEthnicityAlt	String	Second most likely ethnicity (U.S. race and ethnicity categorization from US Census Taxonomy)	U.S. race ethnicities
[{...}].raceEthnicity	String	Most likely ethnicity (U.S. race and ethnicity 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 ethnicity, sorted from most likely to least likely (U.S. race and ethnicity categorization from US Census Taxonomy)	U.S. race ethnicities
[{...}].probabilityCalibrated	Number	The calibrated probability for raceEthnicity to have been guessed correctly. -1 = still calibrating.
[{...}].probabilityAltCalibrated	Number	The calibrated probability for raceEthnicity OR raceEthnicityAlt to 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":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Keith","lastName":"Haring","countryIso2":"US"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Keith",
      "lastName": "Haring",
      "countryIso2": "US"
    }
  ]
}

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Keith",
      "lastName": "Haring",
      "raceEthnicityAlt": "B_NL",
      "raceEthnicity": "W_NL",
      "score": 14.124697493222158,
      "raceEthnicitiesTop": [
        "W_NL",
        "B_NL",
        "A",
        "HL"
      ],
      "probabilityCalibrated": 0.8284804986473213,
      "probabilityAltCalibrated": 0.8890718404096647
    }
  ]
}

Name US race ZIP

POST

Description: Returns the most likely U.S. race or ethnicity from up to 100 first names and/or last names using their ZIP code.
Precision:
Cost: 10 credits per name.
Test: name US race ZIP feature.

HTTP request

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

Request body

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

Name	Type	Required	Description
personalNames	Array of objects	Required	A list of personal names
[{...}].id	String	Optional	Unique identifier
[{...}].firstName	String	Optional	First name (or given name)
[{...}].lastName	String	Optional	Last name (or family name)
[{...}].countryIso2	String	Optional	Most likely 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

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

Name	Type	Description	Enumerators
personalNames	Array of objects	List of submitted names with their race ethnicity
[{...}].script	String	Character set used for analysis	Alphabets
[{...}].id	String	Provided unique identifier
[{...}].firstName	String	Submitted first name
[{...}].lastName	String	Submitted last name
[{...}].raceEthnicityAlt	String	Second most likely ethnicity (U.S. race and ethnicity categorization from US Census Taxonomy)	U.S. race ethnicities
[{...}].raceEthnicity	String	Most likely ethnicity (U.S. race and ethnicity 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 ethnicity, sorted from most likely to least likely (U.S. race and ethnicity categorization from US Census Taxonomy)	U.S. race ethnicities
[{...}].probabilityCalibrated	Number	The calibrated probability for raceEthnicity to have been guessed correctly. -1 = still calibrating.
[{...}].probabilityAltCalibrated	Number	The calibrated probability for raceEthnicity OR raceEthnicityAlt to 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":"e630dda5-13b3-42c5-8f1d-648aa8a21c42","firstName":"Makoto","lastName":"Iwamatsu","countryIso2":"JP","zipCode":"10019"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Makoto",
      "lastName": "Iwamatsu",
      "countryIso2": "JP",
      "zipCode": "10019"
    }
  ]
}

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Makoto",
      "lastName": "Iwamatsu",
      "raceEthnicityAlt": "HL",
      "raceEthnicity": "A",
      "score": 33.10409827435145,
      "raceEthnicitiesTop": [
        "A",
        "HL",
        "B_NL",
        "W_NL"
      ],
      "probabilityCalibrated": 0.943439227727173,
      "probabilityAltCalibrated": 0.9817007157185398
    }
  ]
}

Country of residence from a name

Our artificial intelligence is based on the morphology of names to determine their country of residence. This is why we can identify a first name country, a last name country, a full name country and even the country of residence of a nickname or an invented name. Finally our functionality supports 192 countries of residence and 22 alphabets.

Note that the Name Origin feature may be better to identify a country of origin.

Name country

POST

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

HTTP request

POST

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

Request header

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

Request body

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

Name	Type	Required	Description
personalNames	Array of objects	Required	A list of personal names
[{...}].id	String	Optional	Unique identifier
[{...}].name	String	Required	First name, or last name, or full name

Response

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

Name	Type	Description	Enumerators
personalNames	Array of objects	List of submitted names with their countries of residence
[{...}].script	String	Character set used for analysis	Alphabets
[{...}].id	String	Provided unique identifier
[{...}].name	String	Submitted 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
[{...}].topRegion	String	Most likely region of residence (alternative classification)
[{...}].subRegion	String	Most likely subregion of 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 for country to have been guessed correctly. -1 = still calibrating.
[{...}].probabilityAltCalibrated	Number	The calibrated probability for country OR countryAlt to have been guessed correctly. -1 = still calibrating.

Code sample

name country code sample for shell :

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

Body parameter:

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

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "345f20b8-6b93-46d7-a938-2158ae5094fd",
      "name": "Marie Curie",
      "score": 19.507131637203962,
      "country": "FR",
      "countryAlt": "IE",
      "region": "Europe",
      "topRegion": "Europe",
      "subRegion": "Western Europe",
      "countriesTop": [
        "FR",
        "IE",
        "BE",
        "NZ",
        "US",
        "CA",
        "HT",
        "AU",
        "LU",
        "CH"
      ],
      "probabilityCalibrated": 0.6817922272338365,
      "probabilityAltCalibrated": 0.6847166220432508
    }
  ]
}

Gender from a name

Our artificial intelligence is based on the morphology of names to identify the most likely gender of a name. We can identify the gender of a first name, the gender of a full name or the gender of a nickname. The gender determined from a full name will benefit from a more precise result than the gender determined from a first name. Our taxonomy includes two gender: male or female. A probability between 45% and 55% indicates that it is a unisex name with a male name or female name tendency.

Our website Gender Guesser offers extended functionality to identify the gender of a name.

Name gender

POST

Description: Returns the most likely gender of up to 100 first names and last names (optional).
Precision:
Cost: 1 credit per name.
Test: name gender feature.

HTTP request

POST

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

Request header

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

Request body

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

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

Response

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

Name	Type	Description	Enumerators
personalNames	Array of objects	A list of genderized names.
[{...}].script	String	Character set used for analysis	Alphabets
[{...}].id	String	Provided unique identifier
[{...}].firstName	String	Submitted first name
[{...}].lastName	String	Submitted last name
[{...}].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, score is not normalized
[{...}].probabilityCalibrated	Number	Higher implies a more reliable result, ranges from 0 to 1

Code sample

name gender code sample for shell :

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

Body parameter:

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

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Rosalind",
      "lastName": "Franklin",
      "likelyGender": "female",
      "genderScale": 0.9730217066962004,
      "score": 21.904701285428477,
      "probabilityCalibrated": 0.9865108533481002
    }
  ]
}

Name gender ISO

POST

Description: Returns the most likely gender of up to 100 first names and last names using their geographic context.
Precision:
Cost: 1 credit per name.
Test: name gender ISO feature.

HTTP request

POST

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

Request header

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

Request body

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

Name	Type	Required	Description
personalNames	Array of objects	Required	A list of names, with country code.
[{...}].id	String	Optional	Unique identifier
[{...}].firstName	String	Required	First name (or given name)
[{...}].lastName	String	Optional	Last name (or family name)
[{...}].countryIso2	String	Required	Most likely country of origin, in ISO 3166-1 alpha-2 format

Response

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

Name	Type	Description	Enumerators
personalNames	Array of objects	A list of genderized names.
[{...}].script	String	Character set used for analysis	Alphabets
[{...}].id	String	Provided unique identifier
[{...}].firstName	String	Submitted first name
[{...}].lastName	String	Submitted last name
[{...}].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, score is not normalized
[{...}].probabilityCalibrated	Number	Higher implies a more reliable result, ranges from 0 to 1

Code sample

name gender ISO code sample for shell :

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

Body parameter:

{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Sofia",
      "lastName": "Kovalevskaya",
      "countryIso2": "RU"
    }
  ]
}

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Sofia",
      "lastName": "Kovalevskaya",
      "likelyGender": "female",
      "genderScale": 0.9938175581348969,
      "score": 39.01304923594625,
      "probabilityCalibrated": 0.9969087790674485
    }
  ]
}

Admin request

The Admin endpoints allow you to access a wide range of administrative tools. Access your API usage history, check the status and availability of Ethnicity Estimate's endpoints or query the possible enumerators for a given classifier. Among other features you may also set your privacy options or disable your key.

Software Version

GET

Cost : Free

HTTP request

GET

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

Request header

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

Response

The HTTP response body is an object.

Name	Type	Description
softwareNameAndVersion	String	Name and version of the API
softwareVersion	Array	Software version, as an array (major, minor and patch)

Code sample

Software Version code sample for shell :

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

The above command returns JSON structured like this :

{
  "softwareNameAndVersion": "NamSorAPIv2.0.14B01",
  "softwareVersion": [
    2,
    0,
    14
  ]
}

Api Status

GET

Cost : Free

HTTP request

GET

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

Request header

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

Response

The HTTP response body is an object.

Name	Type	Description
softwareVersion	Object	Software version information
{...}.softwareNameAndVersion	String	Name and version of the API
{...}.softwareVersion	Array	Software version, as an array (major, minor and patch)
classifiers	Array of objects	List of available classifiers
[{...}].classifierName	String	Name of the classifier / service
[{...}].serving	Boolean	True if the classifier is serving requests (has reached minimal learning, is not shutting down)
[{...}].learning	Boolean	True if the classifier is learning
[{...}].shuttingDown	Boolean	True if the classifier is shutting down
[{...}].probabilityCalibrated	Boolean	True if the classifier has finished the initial learning and has calibrated probabilities (during initial learning, calibrated probabilities will be equal to -1)
[{...}].classifierName	String	Name of the classifier / service
[{...}].serving	Boolean	True if the classifier is serving requests (has reached minimal learning, is not shutting down)
[{...}].learning	Boolean	True if the classifier is learning
[{...}].shuttingDown	Boolean	True if the classifier is shutting down
[{...}].probabilityCalibrated	Boolean	True if the classifier has finished the initial learning and has calibrated probabilities (during initial learning, calibrated probabilities will be equal to -1)

Code sample

Api Status code sample for shell :

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

The above command returns JSON structured like this :

{
  "softwareVersion": {
    "softwareNameAndVersion": "NamSorAPIv2.0.14B01",
    "softwareVersion": [
      2,
      0,
      14
    ]
  },
  "classifiers": [
    {
      "classifierName": "name_category",
      "serving": true,
      "learning": true,
      "shuttingDown": false,
      "probabilityCalibrated": false
    },
    {
      "classifierName": "personalname_gender",
      "serving": true,
      "learning": true,
      "shuttingDown": false,
      "probabilityCalibrated": true
    }
  ]
}

Available Services

GET

Cost : Free

HTTP request

GET

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

Request header

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

Response

The HTTP response body is an object.

Name	Type	Description
apiServices	Array of objects	List of available API services
[{...}].serviceName	String	Name of the classifier / service
[{...}].serviceGroup	String	Group the classifier / service belong to
[{...}].costInUnits	Number	Usage cost of the service, in credits
[{...}].serviceName	String	Name of the classifier / service
[{...}].serviceGroup	String	Group the classifier / service belong to
[{...}].costInUnits	Number	Usage cost of the service, in credits

Code sample

Available Services code sample for shell :

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

The above command returns JSON structured like this :

{
  "apiServices": [
    {
      "serviceName": "name_category",
      "serviceGroup": "general",
      "costInUnits": 1
    },
    {
      "serviceName": "personalname_gender",
      "serviceGroup": "gender",
      "costInUnits": 1
    }
  ]
}

Taxonomy Classes

GET

Cost : Free

HTTP request

GET

https://v2.namsor.com/NamSorAPIv2/api2/json/taxonomyClasses/{classifierName}

Request header

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

Request parameters

Name	Type	Required	Description
classifierName	String	Required	Name of the classifier

Response

The HTTP response body is an object.

Name	Type	Description
classifierName	String	Name of the submitted classifier
taxonomyClasses	Array	Possible enumerators for this classifier

Code sample

Taxonomy Classes code sample for shell :

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

The above command returns JSON structured like this :

{
  "classifierName": "personalname_gender",
  "taxonomyClasses": [
    "female",
    "male"
  ]
}

Api Usage

GET

Cost : Free

HTTP request

GET

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

Request header

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

Response

The HTTP response body is an object.

Name	Type	Description
subscription	Object	Subscription information
{...}.apiKey	String	Your Namsor API key
{...}.planStarted	Number	Start date of the plan, in UNIX time format
{...}.priorPlanStarted	Number	Datetime when the user subscribed to the prior plan
{...}.planEnded	Number	End date of the plan, in UNIX time format
{...}.taxRate	Number	Applicable tax rate for the plan
{...}.planName	String	Name of the plan
{...}.planBaseFeesKey	String	Current plan key (as in Stripe product)
{...}.planStatus	String	Plan status
{...}.planQuota	Number	Total number of credits associated with this plan
{...}.priceUSD	Number	Price in U.S. dollars ($)
{...}.priceOverageUSD	Number	Overage price in U.S. dollars ($)
{...}.price	Number	Price in the user's preferred currency
{...}.priceOverage	Number	Overaged price in the user's preferred currency
{...}.currency	String	The user's preferred currency
{...}.currencyFactor	Number	For USD, GBP, EUR - the factor is 1
{...}.stripeCustomerId	Object	Unique Stripe Customer identifier
{...}.stripeStatus	Object	Stripe status
{...}.stripeSubscription	Object	Stripe subscription identifier
{...}.userId	String	Unique user identifier
billingPeriod	Object	Billing information
{...}.apiKey	String	Your Namsor API key
{...}.subscriptionStarted	Number	Subscription start date, in UNIX time format
{...}.periodStarted	Number	Subscription period start date, in UNIX time format
{...}.periodEnded	Number	Subscription end date, in UNIX time format
{...}.stripeCurrentPeriodEnd	Number	End of the current plan in Stripe
{...}.stripeCurrentPeriodStart	Number	Start of the current plan in Stripe
{...}.billingStatus	String	Status of the current period billing
{...}.usage	Number	Number of credits used so far
{...}.softLimit	Number	Current soft limit for the period
{...}.hardLimit	Number	Current hard limit for the period
overageExclTax	Number	Overage amount including any tax
overageInclTax	Number	Overage amount including tax (if applicable)
overageCurrency	Object	Currency of the overage amount
overageQuantity	Number	Quantity above monthly quota of the current subscritpion, in credits

Code sample

Api Usage code sample for shell :

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

The above command returns JSON structured like this :

{
  "subscription": {
    "apiKey": "77afd518a85798fa3723f5ec8120adb7",
    "planStarted": 1602705605199,
    "priorPlanStarted": 0,
    "planEnded": 0,
    "taxRate": 0,
    "planName": "BASIC",
    "planBaseFeesKey": "namsorapi_v2_BASIC_usd",
    "planStatus": "OPEN",
    "planQuota": 5000,
    "priceUSD": 0,
    "priceOverageUSD": 0.005,
    "price": 0,
    "priceOverage": 0.005,
    "currency": "usd",
    "currencyFactor": 1,
    "stripeCustomerId": null,
    "stripeStatus": null,
    "stripeSubscription": null,
    "userId": "lXVJ95AraqM9jrRns45ZfbE4qRgw"
  },
  "billingPeriod": {
    "apiKey": "77afd518a85798fa3723f5ec8120adb7",
    "subscriptionStarted": 1602705635199,
    "periodStarted": 1618430435199,
    "periodEnded": 0,
    "stripeCurrentPeriodEnd": 0,
    "stripeCurrentPeriodStart": 0,
    "billingStatus": "OPEN",
    "usage": 34,
    "softLimit": 3000,
    "hardLimit": 5000
  },
  "overageExclTax": 0,
  "overageInclTax": 0,
  "overageCurrency": null,
  "overageQuantity": 0
}

Api Usage History

GET

Cost : Free

HTTP request

GET

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

Request header

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

Response

The HTTP response body is an object.

Name	Type	Description
detailedUsage	Array of objects	Print historical API usage (NB. new output format form v2.0.15)
[{...}].apiKey	Object	API key information
{...}.userId	Object	Unique user identifier
{...}.admin	Boolean	Does the API Key have admin priviledges
{...}.vetted	Boolean	Is the API Key vetted for machine learning
{...}.learnable	Boolean	Is the API Key authorised to feed the machine learning
{...}.anonymized	Boolean	Is the API Key anonymized (using its SHA-256 digest for logging)
{...}.partner	Boolean	Does the API Key have a partnership role
{...}.striped	Boolean	Is the API Key associated to a valid Stripe account
{...}.corporate	Boolean	Does the API Key have a corporate role
{...}.disabled	Boolean	Is the API Key temporarily or permanently disabled
{...}.api_key	String	The user API Key.
[{...}].apiService	String	Name of the service requested
[{...}].createdDateTime	Number	Date of the analysis, in UNIX time format
[{...}].totalUsage	Number	Total cost of the analysis in credits
[{...}].lastFlushedDateTime	Number	Last time the counter was reset, in UNIX time format
[{...}].lastUsedDateTime	Number	Last time the API key was used, in UNIX time format
[{...}].serviceFeaturesUsage	Object	Details regarding usage of special features

Code sample

Api Usage History code sample for shell :

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

The above command returns JSON structured like this :

{
  "detailedUsage": [
    {
      "apiKey": {
        "userId": null,
        "admin": false,
        "vetted": false,
        "learnable": true,
        "anonymized": false,
        "partner": false,
        "striped": false,
        "corporate": false,
        "disabled": false,
        "api_key": "b214894824e1c4762fb650866fea8f3c"
      },
      "apiService": "personalname_us_race_ethnicity",
      "createdDateTime": 1620385794616,
      "totalUsage": 1,
      "lastFlushedDateTime": 1620386273418,
      "lastUsedDateTime": 1620386699945,
      "serviceFeaturesUsage": {}
    }
  ]
}

Api Usage History Aggregate

GET

Cost : Free

HTTP request

GET

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

Request header

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

Response

The HTTP response body is an object.

Name	Type	Description
timeUnit	String	Unit of time used in the "rowHeaders" field. May vary depending on API usage ("DAY", "WEEK" or "MONTH")
periodStart	Number	Start of the reporting period, in UNIX time format
periodEnd	Number	End of the reporting period, in UNIX time format
totalUsage	Number	Total usage during the current period
historyTruncated	Boolean	Indicates if returned data was truncaded due to size limits
data	Array of arrays	Aggregated API usage, formated as an array of data points (or array of arrays)
colHeaders	Array	Column headers used to link API services to the values in each data point
rowHeaders	Array	Row headers used to link a period of time to a data point

Code sample

Api Usage History Aggregate code sample for shell :

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

The above command returns JSON structured like this :

{
  "timeUnit": "DAY",
  "periodStart": 1600616581000,
  "periodEnd": 1600702981000,
  "totalUsage": 42,
  "historyTruncated": false,
  "data": [
    [
      0,
      0,
      0,
      10,
      10,
      0,
      0,
      0,
      0,
      10,
      10,
      2
    ]
  ],
  "colHeaders": [
    "chineseNameCandidates",
    "japaneseNameCandidates",
    "japaneseNameMatching",
    "name_category",
    "name_parser_type",
    "personalfullname_country",
    "personalfullname_gender",
    "personalname_country_diaspora",
    "personalname_gender",
    "personalname_origin_country",
    "personalname_phone_prefix",
    "personalname_us_race_ethnicity"
  ],
  "rowHeaders": [
    "2020-09-20"
  ]
}

Learnable

GET

Cost : Free

HTTP request

GET

https://v2.namsor.com/NamSorAPIv2/api2/json/learnable/{source}/{learnable}

Request parameters

Name	Type	Required	Description
source	String	Required	The API Key to set as learnable or non-learnable
learnable	Boolean	Required	Should the API key be set to learnable

Response

In case of a success the API will respond with an HTTP 200 code.

Code sample

Learnable code sample for shell :

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

Anonymize

GET

Cost : Free

HTTP request

GET

https://v2.namsor.com/NamSorAPIv2/api2/json/anonymize/{source}/{anonymized}

Request parameters

Name	Type	Required	Description
source	String	Required	The API Key to set as anonymized or non-anonymized
anonymized	Boolean	Required	Should the API key be set to anonymized

Response

In case of a success the API will respond with an HTTP 200 code.

Code sample

Anonymize code sample for shell :

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

Disable API Key

GET

Cost : Free

HTTP request

GET

https://v2.namsor.com/NamSorAPIv2/api2/json/disable/{source}/{disabled}

Request header

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

Request parameters

Name	Type	Required	Description
source	String	Required	The API Key to set as enabled or disabled
disabled	Boolean	Required	Should the API key be set to disabled

Response

The HTTP response body is an object.

Name	Type	Description	Enumerators
script	Object		Alphabets
id	Object
firstName	String
lastName	String
orderOption	Object
matchCandidates	Array of objects	Disabled the API Key.
[{...}].candidateName	String
[{...}].probability	Number
[{...}].predScoreGivenName	Number
[{...}].predScoreFamilyName	Number
[{...}].candidateName	String
[{...}].probability	Number
[{...}].predScoreGivenName	Number
[{...}].predScoreFamilyName	Number

Code sample

Disable API Key code sample for shell :

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

The above command returns JSON structured like this :

{
  "script": null,
  "id": null,
  "firstName": "LiYing",
  "lastName": "Zhao",
  "orderOption": null,
  "matchCandidates": [
    {
      "candidateName": "赵丽英",
      "probability": 0.26153460755147884,
      "predScoreGivenName": 0,
      "predScoreFamilyName": 0
    },
    {
      "candidateName": "赵丽颖",
      "probability": 0.11856235542333707,
      "predScoreGivenName": 0,
      "predScoreFamilyName": 0
    }
  ]
}