Ethnicity Estimate

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

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.

info symbol

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

Credits

What are Credits

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

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

Admin routes are free.

Repeated Operations Tolerance

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

Soft Limit vs Hard Limit

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

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

Track Usage

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

Errors

The NamSor API uses the following error codes:

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

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

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

Request header

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

Request body

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

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

Response

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

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names with their countries of origin
[{...}].scriptStringCharacter set used for analysisAlphabets
[{...}].idStringProvided unique identifier
[{...}].firstNameStringSubmitted first name, given name or nickname
[{...}].lastNameStringSubmitted last name, family name or surname
[{...}].countryOriginStringMost likely country of origin, in ISO 3166-1 alpha-2 formatCountry of origin
[{...}].countryOriginAltStringSecond most likely country of origin, in ISO 3166-1 alpha-2 formatCountry of origin
[{...}].countriesOriginTopArrayTop 10 most likely countries of origin, in ISO 3166-1 alpha-2 format, sorted from most likely to least likelyCountry of origin
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized
[{...}].regionOriginStringMost likely region of origin
[{...}].topRegionOriginStringMost likely region of origin (alternative classification)
[{...}].subRegionOriginStringMost likely subregion of origin
[{...}].probabilityCalibratedNumberThe calibrated probability for countryOrigin to have been guessed correctly. -1 = still calibrating.
[{...}].probabilityAltCalibratedNumberThe calibrated probability for countryOrigin OR countryOriginAlt to have been guessed correctly. -1 = still calibrating.

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

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

Request header

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

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names
[{...}].idStringOptionalUnique identifier
[{...}].firstNameStringOptionalFirst name or given name or nickname
[{...}].lastNameStringOptionalLast name or family name or surname
[{...}].countryIso2StringOptionalCountry of residence, in ISO 3166-1 alpha-2 format

Response

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

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names with their ethnicities
[{...}].scriptStringCharacter set used for analysisAlphabets
[{...}].idStringProvided unique identifier
[{...}].firstNameStringSubmitted first name
[{...}].lastNameStringSubmitted last name
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized
[{...}].probabilityAltCalibratedNumberThe calibrated probability for ethnicity OR ethnicityAlt to have been guessed correctly. -1 = still calibrating.
[{...}].probabilityCalibratedNumberThe calibrated probability for ethnicity to have been guessed correctly. -1 = still calibrating.
[{...}].ethnicityAltStringSecond most likely ethnicityEthnicities or diasporas
[{...}].ethnicityStringMost likely ethnicityEthnicities or diasporas
[{...}].liftedBooleanIndicates if the output ethnicity is based on machine learning only, or further lifted as a known fact by a country-specific rule
[{...}].countryIso2StringSubmitted country of residence, in ISO 3166-1 alpha-2 formatCountry of residence
[{...}].ethnicitiesTopArrayTop 10 most likely ethnicities, order from most likely to least likelyEthnicities 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

HTTP request

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

Request header

PropertyValuesRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
X-OPTION-USRACEETHNICITY-TAXONOMYUSRACEETHNICITY-6CLASSESOptionalEnumerators for the returned 'race' ethnicity. Do not specify the property of the http request to obtain 4 classes (W_NL, HL, A, B_NL), USRACEETHNICITY-6CLASSES will return 6 classes (W_NL, HL, A, B_NL, AI_AN, PI).

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names
[{...}].idStringOptionalUnique identifier
[{...}].firstNameStringOptionalFirst name or given name or nickname
[{...}].lastNameStringOptionalLast name or family name or surname
[{...}].countryIso2StringOptionalMost likely country of residence, in ISO 3166-1 alpha-2 format

Response

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

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names with their race ethnicity
[{...}].scriptStringCharacter set used for analysisAlphabets
[{...}].idStringProvided unique identifier
[{...}].firstNameStringSubmitted first name
[{...}].lastNameStringSubmitted last name
[{...}].raceEthnicityAltStringSecond most likely ethnicity (U.S. race and ethnicity categorization from US Census Taxonomy)U.S. race ethnicities
[{...}].raceEthnicityStringMost likely ethnicity (U.S. race and ethnicity categorization from US Census Taxonomy)U.S. race ethnicities
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized
[{...}].raceEthnicitiesTopArrayMost likely ethnicity, sorted from most likely to least likely (U.S. race and ethnicity categorization from US Census Taxonomy)U.S. race ethnicities
[{...}].probabilityCalibratedNumberThe calibrated probability for raceEthnicity to have been guessed correctly. -1 = still calibrating.
[{...}].probabilityAltCalibratedNumberThe 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

HTTP request

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

Request header

PropertyValuesRequiredDescription
X-API-KEYRequiredYour Namsor's services API key
X-OPTION-USRACEETHNICITY-TAXONOMYUSRACEETHNICITY-6CLASSESOptionalEnumerators for the returned 'race' ethnicity. Do not specify the property of the http request to obtain 4 classes (W_NL, HL, A, B_NL), USRACEETHNICITY-6CLASSES will return 6 classes (W_NL, HL, A, B_NL, AI_AN, PI).

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names
[{...}].idStringOptionalUnique identifier
[{...}].firstNameStringOptionalFirst name (or given name)
[{...}].lastNameStringOptionalLast name (or family name)
[{...}].countryIso2StringOptionalMost likely country of residence, in ISO 3166-1 alpha-2 format
[{...}].zipCodeStringRequiredPostal code (5-digit) of residence used by the United States Postal Service (USPS)

Response

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

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names with their race ethnicity
[{...}].scriptStringCharacter set used for analysisAlphabets
[{...}].idStringProvided unique identifier
[{...}].firstNameStringSubmitted first name
[{...}].lastNameStringSubmitted last name
[{...}].raceEthnicityAltStringSecond most likely ethnicity (U.S. race and ethnicity categorization from US Census Taxonomy)U.S. race ethnicities
[{...}].raceEthnicityStringMost likely ethnicity (U.S. race and ethnicity categorization from US Census Taxonomy)U.S. race ethnicities
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized
[{...}].raceEthnicitiesTopArrayMost likely ethnicity, sorted from most likely to least likely (U.S. race and ethnicity categorization from US Census Taxonomy)U.S. race ethnicities
[{...}].probabilityCalibratedNumberThe calibrated probability for raceEthnicity to have been guessed correctly. -1 = still calibrating.
[{...}].probabilityAltCalibratedNumberThe 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

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

Request header

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

Request body

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

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

Response

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

NameTypeDescriptionEnumerators
personalNamesArray of objectsList of submitted names with their countries of residence
[{...}].scriptStringCharacter set used for analysisAlphabets
[{...}].idStringProvided unique identifier
[{...}].nameStringSubmitted name
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized
[{...}].countryStringMost likely country of residence, in ISO 3166-1 alpha-2 formatCountry of residence
[{...}].countryAltStringSecond most likely country of residence, in ISO 3166-1 alpha-2 formatCountry of residence
[{...}].regionStringMost likely region of residence
[{...}].topRegionStringMost likely region of residence (alternative classification)
[{...}].subRegionStringMost likely subregion of residence
[{...}].countriesTopArrayTop 10 most likely countries of residence, in ISO 3166-1 alpha-2 format, sorted from most likely to least likely
[{...}].probabilityCalibratedNumberThe calibrated probability for country to have been guessed correctly. -1 = still calibrating.
[{...}].probabilityAltCalibratedNumberThe 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:Precision gauge
  • Cost: 1 credit per name.
  • Test: name gender feature.

HTTP request

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

Request header

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

Request body

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

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

Response

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

NameTypeDescriptionEnumerators
personalNamesArray of objectsA list of genderized names.
[{...}].scriptStringCharacter set used for analysisAlphabets
[{...}].idStringProvided unique identifier
[{...}].firstNameStringSubmitted first name
[{...}].lastNameStringSubmitted last name
[{...}].likelyGenderStringMost likely genderGenders
[{...}].genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized
[{...}].probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

Code sample

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

HTTP request

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

Request header

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

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of names, with country code.
[{...}].idStringOptionalUnique identifier
[{...}].firstNameStringRequiredFirst name (or given name)
[{...}].lastNameStringOptionalLast name (or family name)
[{...}].countryIso2StringRequiredMost likely country of origin, in ISO 3166-1 alpha-2 format

Response

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

NameTypeDescriptionEnumerators
personalNamesArray of objectsA list of genderized names.
[{...}].scriptStringCharacter set used for analysisAlphabets
[{...}].idStringProvided unique identifier
[{...}].firstNameStringSubmitted first name
[{...}].lastNameStringSubmitted last name
[{...}].likelyGenderStringMost likely genderGenders
[{...}].genderScaleNumberGender scale ranging from -1 (male) to +1 (female)
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized
[{...}].probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1

Code sample

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

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

Request header

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

Response

The HTTP response body is an object.

NameTypeDescription
softwareNameAndVersionStringName and version of the API
softwareVersionArraySoftware 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

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

Request header

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

Response

The HTTP response body is an object.

NameTypeDescription
softwareVersionObjectSoftware version information
{...}.softwareNameAndVersionStringName and version of the API
{...}.softwareVersionArraySoftware version, as an array (major, minor and patch)
classifiersArray of objectsList of available classifiers
[{...}].classifierNameStringName of the classifier / service
[{...}].servingBooleanTrue if the classifier is serving requests (has reached minimal learning, is not shutting down)
[{...}].learningBooleanTrue if the classifier is learning
[{...}].shuttingDownBooleanTrue if the classifier is shutting down
[{...}].probabilityCalibratedBooleanTrue if the classifier has finished the initial learning and has calibrated probabilities (during initial learning, calibrated probabilities will be equal to -1)
[{...}].classifierNameStringName of the classifier / service
[{...}].servingBooleanTrue if the classifier is serving requests (has reached minimal learning, is not shutting down)
[{...}].learningBooleanTrue if the classifier is learning
[{...}].shuttingDownBooleanTrue if the classifier is shutting down
[{...}].probabilityCalibratedBooleanTrue 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

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

Request header

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

Response

The HTTP response body is an object.

NameTypeDescription
apiServicesArray of objectsList of available API services
[{...}].serviceNameStringName of the classifier / service
[{...}].serviceGroupStringGroup the classifier / service belong to
[{...}].costInUnitsNumberUsage cost of the service, in credits
[{...}].serviceNameStringName of the classifier / service
[{...}].serviceGroupStringGroup the classifier / service belong to
[{...}].costInUnitsNumberUsage 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

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

Request header

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

Request parameters

NameTypeRequiredDescription
classifierNameStringRequiredName of the classifier

Response

The HTTP response body is an object.

NameTypeDescription
classifierNameStringName of the submitted classifier
taxonomyClassesArrayPossible 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

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

Request header

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

Response

The HTTP response body is an object.

NameTypeDescription
subscriptionObjectSubscription information
{...}.apiKeyStringYour Namsor API key
{...}.planStartedNumberStart date of the plan, in UNIX time format
{...}.priorPlanStartedNumberDatetime when the user subscribed to the prior plan
{...}.planEndedNumberEnd date of the plan, in UNIX time format
{...}.taxRateNumberApplicable tax rate for the plan
{...}.planNameStringName of the plan
{...}.planBaseFeesKeyStringCurrent plan key (as in Stripe product)
{...}.planStatusStringPlan status
{...}.planQuotaNumberTotal number of credits associated with this plan
{...}.priceUSDNumberPrice in U.S. dollars ($)
{...}.priceOverageUSDNumberOverage price in U.S. dollars ($)
{...}.priceNumberPrice in the user's preferred currency
{...}.priceOverageNumberOveraged price in the user's preferred currency
{...}.currencyStringThe user's preferred currency
{...}.currencyFactorNumberFor USD, GBP, EUR - the factor is 1
{...}.stripeCustomerIdObjectUnique Stripe Customer identifier
{...}.stripeStatusObjectStripe status
{...}.stripeSubscriptionObjectStripe subscription identifier
{...}.userIdStringUnique user identifier
billingPeriodObjectBilling information
{...}.apiKeyStringYour Namsor API key
{...}.subscriptionStartedNumberSubscription start date, in UNIX time format
{...}.periodStartedNumberSubscription period start date, in UNIX time format
{...}.periodEndedNumberSubscription end date, in UNIX time format
{...}.stripeCurrentPeriodEndNumberEnd of the current plan in Stripe
{...}.stripeCurrentPeriodStartNumberStart of the current plan in Stripe
{...}.billingStatusStringStatus of the current period billing
{...}.usageNumberNumber of credits used so far
{...}.softLimitNumberCurrent soft limit for the period
{...}.hardLimitNumberCurrent hard limit for the period
overageExclTaxNumberOverage amount including any tax
overageInclTaxNumberOverage amount including tax (if applicable)
overageCurrencyObjectCurrency of the overage amount
overageQuantityNumberQuantity 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

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

Request header

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

Response

The HTTP response body is an object.

NameTypeDescription
detailedUsageArray of objectsPrint historical API usage (NB. new output format form v2.0.15)
[{...}].apiKeyObjectAPI key information
{...}.userIdObjectUnique user identifier
{...}.adminBooleanDoes the API Key have admin priviledges
{...}.vettedBooleanIs the API Key vetted for machine learning
{...}.learnableBooleanIs the API Key authorised to feed the machine learning
{...}.anonymizedBooleanIs the API Key anonymized (using its SHA-256 digest for logging)
{...}.partnerBooleanDoes the API Key have a partnership role
{...}.stripedBooleanIs the API Key associated to a valid Stripe account
{...}.corporateBooleanDoes the API Key have a corporate role
{...}.disabledBooleanIs the API Key temporarily or permanently disabled
{...}.api_keyStringThe user API Key.
[{...}].apiServiceStringName of the service requested
[{...}].createdDateTimeNumberDate of the analysis, in UNIX time format
[{...}].totalUsageNumberTotal cost of the analysis in credits
[{...}].lastFlushedDateTimeNumberLast time the counter was reset, in UNIX time format
[{...}].lastUsedDateTimeNumberLast time the API key was used, in UNIX time format
[{...}].serviceFeaturesUsageObjectDetails 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

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

Request header

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

Response

The HTTP response body is an object.

NameTypeDescription
timeUnitStringUnit of time used in the "rowHeaders" field. May vary depending on API usage ("DAY", "WEEK" or "MONTH")
periodStartNumberStart of the reporting period, in UNIX time format
periodEndNumberEnd of the reporting period, in UNIX time format
totalUsageNumberTotal usage during the current period
historyTruncatedBooleanIndicates if returned data was truncaded due to size limits
dataArray of arraysAggregated API usage, formated as an array of data points (or array of arrays)
colHeadersArrayColumn headers used to link API services to the values in each data point
rowHeadersArrayRow 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

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

Request parameters

NameTypeRequiredDescription
sourceStringRequiredThe API Key to set as learnable or non-learnable
learnableBooleanRequiredShould 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

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

Request parameters

NameTypeRequiredDescription
sourceStringRequiredThe API Key to set as anonymized or non-anonymized
anonymizedBooleanRequiredShould 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

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

Request header

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

Request parameters

NameTypeRequiredDescription
sourceStringRequiredThe API Key to set as enabled or disabled
disabledBooleanRequiredShould the API key be set to disabled

Response

The HTTP response body is an object.

NameTypeDescriptionEnumerators
scriptObjectAlphabets
idObject
firstNameString
lastNameString
orderOptionObject
matchCandidatesArray of objectsDisabled the API Key.
[{...}].candidateNameString
[{...}].probabilityNumber
[{...}].predScoreGivenNameNumber
[{...}].predScoreFamilyNameNumber
[{...}].candidateNameString
[{...}].probabilityNumber
[{...}].predScoreGivenNameNumber
[{...}].predScoreFamilyNameNumber

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