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