API version:

API key:

Introduction

Request

Gender of a name

Gender
Gender from first names , last names (optional).
Gender Full Name
Gender from full names .

Gender improve with country

Gender Geo
Gender from first names , last names (optional), country codes .
Gender Full Name Geo
Gender from full names , country codes .

Gender of Japanese names

Gender Name Latin
Gender from first names , last names (optional).
Gender Name Kanji
Gender from names .

Gender of Chinese names

Gender Name Pinyin
Gender from first names , last names (optional).
Gender Name Mandarin
Gender from names .

Admin

Account

Tools

More features, by Namsor

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

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

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.

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:
Cost: 1 credit per name
Test: 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).
[{...}].lastName	String	Optional	Last name (or family name).

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

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:
Cost: 1 credit per name
Test: gender full name feature

HTTP request

POST

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

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	Full name (first name and last name).

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.
[{...}].name	String	Submitted full 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

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:
Cost: 1 credit per name
Test: gender geo 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

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:
Cost: 1 credit per name
Test: gender full name geo feature

HTTP request

POST

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

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, with a country ISO2 code.
[{...}].id	String	Optional	Unique identifier.
[{...}].name	String	Required	Full name (first name and last 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.
[{...}].name	String	Submitted full 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

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:
Cost: 1 credit per name
Test: gender name latin feature

HTTP request

POST

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

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) in Latin alphabet.
[{...}].lastName	String	Optional	Last name (or family name) in Latin alphabet.

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

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:
Cost: 1 credit per name
Test: gender name kanji feature

HTTP request

POST

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

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 full name (family name and given name) in Kanji.

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.
[{...}].name	String	Submitted 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

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:
Cost: 1 credit per name
Test: gender name pinyin feature

HTTP request

POST

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

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

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

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:
Cost: 1 credit per name
Test: gender name mandarin feature

HTTP request

POST

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

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, with a country ISO2 code.
[{...}].id	String	Optional	Unique identifier.
[{...}].name	String	Required	First name or full name in Standard Mandarin Chinese.

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.
[{...}].name	String	Submitted 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

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

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": "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

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/v7menlws2yo8r2mnm10f3uai53tmblth/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/v7menlws2yo8r2mnm10f3uai53tmblth/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 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

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'