Gender Guesser

API documentation

Gender Guesser 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 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 Gender Guesser 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 Gender Guesser'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 Gender Guesser 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 500 names to determine their gender.
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 gender 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.

Gender request

Gender Guesser’s name checking API can help you determine the probability of a person being male or female based on their name. We offer many processing options for gender determination, the name can either be provided: as a full name, as a first name and a last name. In addition to the name you may specify the country of origin to improve accuracy.

Gender Guesser API supports 22 alphabets : Cyrillic, Georgian, Latin, Arabic, Devanagari, Bengali, Greek, Armenian, Thai, Hebrew, Kannada, Gujarati, Tamil, Hangul, Telugu, Gurmukhi, Oriya, Han (Chinese traditional and simplified characters, Kanji), Hiragana, Myanmar, Katakana and Malayalam.

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: 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).
[{...}].lastNameStringOptionalLast name (or family name).

Response

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

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

Code sample

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

Gender Full Name

POST
  • Description: Returns the most likely gender of up to 100 full names.
  • Precision:Precision gauge
  • Cost: 1 credit per name
  • Test: gender full name feature

HTTP request

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

Request header

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

Request body

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

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

Response

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

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

Code sample

Gender Full Name code sample for shell :

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

Body parameter:

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

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "Alan Turing",
      "likelyGender": "male",
      "genderScale": -0.9831427708411884,
      "score": 19.119365238807685,
      "probabilityCalibrated": 0.9915713854205942
    }
  ]
}

Gender Geo

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: gender geo feature

HTTP request

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

Request header

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

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of 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 analysis.Alphabets
[{...}].idStringProvided unique identifier.
[{...}].firstNameStringSubmitted first name.
[{...}].lastNameStringSubmitted last name.
[{...}].likelyGenderStringMost likely gender.Genders
[{...}].genderScaleNumberGender scale ranging from -1 (male) to +1 (female).
[{...}].scoreNumberHigher implies a more reliable result, score is not normalized.
[{...}].probabilityCalibratedNumberHigher implies a more reliable result, ranges from 0 to 1.

Code sample

Gender Geo code sample for shell :

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeoBatch \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'
--header 'Content-Type: application/json' \
--data '{"personalNames":[{"id":"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
    }
  ]
}

Gender Full Name Geo

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

HTTP request

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

Request header

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

Request body

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

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

Response

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

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

Code sample

Gender Full Name Geo code sample for shell :

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

Body parameter:

{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "Maryam Mirzakhani",
      "countryIso2": "IR"
    }
  ]
}

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "Maryam Mirzakhani",
      "likelyGender": "female",
      "genderScale": 0.7336489993843776,
      "score": 8.702861844637805,
      "probabilityCalibrated": 0.8668244996921888
    }
  ]
}

Gender Name Latin

POST
  • Description: Return the most likely gender of up to 100 japanese first names and a last names (optional) in Latin alphabet.
  • Precision:Precision gauge
  • Cost: 1 credit per name
  • Test: gender name latin feature

HTTP request

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

Request header

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

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of names, with country code..
[{...}].idStringOptionalUnique identifier.
[{...}].firstNameStringRequiredFirst name (or given name) in Latin alphabet.
[{...}].lastNameStringOptionalLast name (or family name) in Latin alphabet.

Response

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

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

Code sample

Gender Name Latin code sample for shell :

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

Body parameter:

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

The above command returns JSON structured like this :

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

Gender Name Kanji

POST
  • Description: Find the most likely gender of up to 100 Japanese first or full names (surnames and given names), written in Kanji characters.
  • Precision:Precision gauge
  • Cost: 1 credit per name
  • Test: gender name kanji feature

HTTP request

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

Request header

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

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names.
[{...}].idStringOptionalUnique identifier.
[{...}].nameStringRequiredFirst name or full name (family name and given name) in Kanji.

Response

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

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

Code sample

Gender Name Kanji code sample for shell :

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

Body parameter:

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

The above command returns JSON structured like this :

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

Gender Name Pinyin

POST
  • Description: Return the most likely gender of up to 100 first names and last (optional) in Pinyin.
  • Precision:Precision gauge
  • Cost: 1 credit per name
  • Test: gender name pinyin feature

HTTP request

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

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) in Pinyin.
[{...}].lastNameStringOptionalLast name (or family name) in Pinyin.

Response

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

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

Code sample

Gender Name Pinyin code sample for shell :

curl --request POST \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNamePinyinBatch \
--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":"Dèng","lastName":"Qīngyún"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Dèng",
      "lastName": "Qīngyún"
    }
  ]
}

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "LATIN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "firstName": "Dèng",
      "lastName": "Qīngyún",
      "likelyGender": "male",
      "genderScale": -0.3132515162951226,
      "score": 6.747266465582973,
      "probabilityCalibrated": 0.6566257581475613
    }
  ]
}

Gender Name Mandarin

POST
  • Description: Returns the most likely gender of up to 100 first or full names (family names and given names) in Standard Mandarin Chinese.
  • Precision:Precision gauge
  • Cost: 1 credit per name
  • Test: gender name mandarin feature

HTTP request

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

Request header

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

Request body

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

NameTypeRequiredDescription
personalNamesArray of objectsRequiredA list of personal names, with a country ISO2 code.
[{...}].idStringOptionalUnique identifier.
[{...}].nameStringRequiredFirst name or full name in Standard Mandarin Chinese.

Response

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

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

Code sample

Gender Name Mandarin code sample for shell :

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

Body parameter:

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

The above command returns JSON structured like this :

{
  "personalNames": [
    {
      "script": "HAN",
      "id": "e630dda5-13b3-42c5-8f1d-648aa8a21c42",
      "name": "谢晓亮",
      "likelyGender": "male",
      "genderScale": -0.7130895869378251,
      "score": 8.286118331853034,
      "probabilityCalibrated": 0.8565447934689125
    }
  ]
}

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 Gender Guesser’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": "v7menlws2yo8r2mnm10f3uai53tmblth",
    "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": "GYUAUzTKPusJ3aqUH5gQte0dOQCr"
  },
  "billingPeriod": {
    "apiKey": "v7menlws2yo8r2mnm10f3uai53tmblth",
    "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/v7menlws2yo8r2mnm10f3uai53tmblth/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/v7menlws2yo8r2mnm10f3uai53tmblth/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 parameters

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

Response

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

Code sample

Disable API Key code sample for shell :

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