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
Every endpoint needs an API Key.
Do not give your API key to ANYBODY.

API Requests and Responses

Every endpoint delivers JSON with either an individual object or a nested set of objects..
At present, some NamSor API endpoints incorporate nested object configurations in their request body or responses. Kindly consult the relevant code sample for guidance.
Note that in the code samples, data has been transformed to URL encoded ASCII code characters when required. For instance, 谢晓亮 becomes %E8%B0%A2%E6%99%93%E4%BA%AE. URLs don't support spaces or non-ASCII characters. When sending GET requests to the API, use URL encoding to change non-ASCII characters into a web-friendly format.

Data Privacy

Out of the box, Namsor's machine learning system can enhance data assessments using input data and keeps logs of the requests made. These settings can be altered through your user profile or via specific API endpoints. Every data log undergoes AES encryption prior to storage.

To prevent machine learning from using your submitted data, adjust the learnable option to false under the "Enhance privacy" category on the my account page. When this setting is turned off for an API key, the respective data won't contribute to the machine learning process.

To turn off the record of service use, adjust the anonymized option to true under the "Enhance privacy" category on the my account page. If this setting is enabled for an API key, any data processed with that key undergoes irreversible anonymization via SHA encryption. It's important to mention that even with anonymized data, the smart handling of repetitive queries remains operational.

Authentication

API Key Creation

Accounts for customers are consistent across all Namsor group websites. To generate an API key, head to Namsor or any other site under the Namsor umbrella and register an account. Once registered, go to the account details page to obtain your API key. Your fresh account includes 500 complimentary credits, which you can promptly utilize with any of Namsor's offerings, be it the API, spreadsheet tool, or Developer tools.

API Key Installation

Include your API key in the request header under the X-API-KEY attribute. For proper key integration, kindly consult the given code examples.

Substitute your-api-key with your actual Namsor API key.

Credits

What are Credits

Our usage is monitored through a credit system. Every package offers a set number of monthly credits and a fee for any requests beyond this allocation. The complimentary Basic plan provides 500 credits, but if you need more, additional plans are on offer. To give you an idea, with 500 credits, you can either:

Analyze 500 names to ascertain their gender.

Admin routes are free.

Repeated Operations Tolerance

Our API is designed with intelligent processing, allowing you to analyze the same data up to 20 times without additional charges. So, if you input the same full name five times to deduce its gender, it will cost you just 1 credit.

Soft Limit vs Hard Limit

Within your user account, you have the option to establish two kinds of credit consumption boundaries:

A soft limit which, upon being hit, will prompt an email alert.
A hard limit which, once attained, will both send an email warning and deactivate the API key.

Track Usage

You have two methods to monitor your credit consumption: either view the visuals in your user profile or access the relevant Admin pathways (API Usage, API Usage History, and API Usage History Aggregate).

Errors

401UnauthorizedIncorrect ir missing API Key.
403ForbiddenAPI Key Disabled or API Limit Reached.
404Not FoundThe designated path was not located.
500Internal Server ErrorServer issue. Please retry after some time.

Gender from names

Estimate the gender based on a first name, an optional surname, or a complete undistinguished name. Incorporating the surname allows our system to determine geographical context, enhancing gender prediction. The function that separates full names into "First & last name" tends to be more precise than the one that takes "Full name" as a whole.

Genderize Name

The Genderize Name tool examines both a first name and an optional surname to deduce the dominant gender. Its precision is somewhat superior to the Genderize Full Name function, and providing both first and last names bolsters the accuracy. It delivers the primary gender with an associated adjusted likelihood. Names that present a gender likelihood between 40% and 50% are considered unisex.

Method:

Detail: Delivers the probable gender for up to 100 first names, with optional surnames.
Accuracy:
Cost: 1 credit per name.
Test: Genderize Name feature.

HTTP request:

POST

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

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Request body:
Name	Type	Required	Detail
`personalNames`	Array of objects	Required	A list of personal names.
`[{...}].id`	String	Optional	Unique identifier.
`[{...}].firstName`	String	Required	First name, given name, nickname.
`[{...}].lastName`	String	Optional	Last name, family name, surname.

Response:
Name	Type	Detail	Enumerators
`personalNames`	Array of objects	Roster of provided names with their assigned genders.
`[{...}].script`	String	The name's script presented, in ISO 15924 notation.	Script
`[{...}].id`	String	Given unique identifier.
`[{...}].firstName`	String	Provided first name.
`[{...}].lastName`	String	Provided last name.
`[{...}].likelyGender`	String	Most likely gender.	Genders
`[{...}].genderScale`	Number	The gender scale spans from -1 (indicating male) to +1 (signifying female).
`[{...}].score`	Number	A greater value suggests a more dependable outcome; the score isn't normalized..
`[{...}].probabilityCalibrated`	Number	A higher value indicates a more trustworthy outcome, with a scale from 0 to 1.

Code sample:

Genderize Name code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderBatch", {
"method": "POST",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json",
  "Content-Type": "application/json"
},
"body": JSON.stringify({
  "personalNames": [
    {
      "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
      "firstName": "John",
      "lastName": "Smith"
    }
  ]
})
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

Body parameter:

{
  "personalNames": [
    {
      "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
      "firstName": "John",
      "lastName": "Smith"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
            "firstName": "John",
            "lastName": "Smith",
            "likelyGender": "male",
            "genderScale": -0.9757694244599513,
            "score": 10.622513344078705,
            "probabilityCalibrated": 0.9878847122299756
        }
    ]
}

Genderize Name code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderBatch"

payload = {
  "personalNames": [
    {
      "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
      "firstName": "John",
      "lastName": "Smith"
    }
  ]
}
headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json",
"Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Body parameter:

{
  "personalNames": [
    {
      "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
      "firstName": "John",
      "lastName": "Smith"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
            "firstName": "John",
            "lastName": "Smith",
            "likelyGender": "male",
            "genderScale": -0.9757694244599513,
            "score": 10.622513344078705,
            "probabilityCalibrated": 0.9878847122299756
        }
    ]
}

Genderize Name 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":"59b9393d-8dc4-464e-a26e-6b6841621e24","firstName":"John","lastName":"Smith"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
      "firstName": "John",
      "lastName": "Smith"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
            "firstName": "John",
            "lastName": "Smith",
            "likelyGender": "male",
            "genderScale": -0.9757694244599513,
            "score": 10.622513344078705,
            "probabilityCalibrated": 0.9878847122299756
        }
    ]
}

Genderize Name code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"59b9393d-8dc4-464e-a26e-6b6841621e24\",\"firstName\":\"John\",\"lastName\":\"Smith\"}]}")
.asString();

Body parameter:

{
  "personalNames": [
    {
      "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
      "firstName": "John",
      "lastName": "Smith"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
            "firstName": "John",
            "lastName": "Smith",
            "likelyGender": "male",
            "genderScale": -0.9757694244599513,
            "score": 10.622513344078705,
            "probabilityCalibrated": 0.9878847122299756
        }
    ]
}

For GET method requests, every parameter is mandatory. For a smoother experience with our requests, we suggest opting for the POST method.

Detail: Estimate the most likely gender from a first name and an optional last name.
Accuracy:
Cost: 1 credit per name.
Test: Genderize Name feature.

HTTP request:

GET

https://v2.namsor.com/NamSorAPIv2/api2/json/gender/{firstName}/{lastName}

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Request parameters
Name	Type	Required	Detail
`firstName`	String	Required	First name, given name, nickname.
`lastName`	String	Required	Last name, family name, surname.

Response:
Name	Type	Detail	Enumerators
`script`	String	The name's script presented, in ISO 15924 notation.	Script
`id`	String	Unique identifier.
`firstName`	String	Provided first name.
`lastName`	String	Provided last name.
`likelyGender`	String	Most likely gender.	Genders
`genderScale`	Number	The gender scale spans from -1 (indicating male) to +1 (signifying female).
`score`	Number	A greater value suggests a more dependable outcome; the score isn't normalized..
`probabilityCalibrated`	Number	A higher value indicates a more trustworthy outcome, with a scale from 0 to 1.

Code sample:

Genderize Name code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/gender/John/Smith", {
"method": "GET",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json"
}
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
    "firstName": "John",
    "lastName": "Smith",
    "likelyGender": "male",
    "genderScale": -0.9757694244599513,
    "score": 10.622513344078705,
    "probabilityCalibrated": 0.9878847122299756
}

Genderize Name code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/gender/John/Smith"

headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
    "firstName": "John",
    "lastName": "Smith",
    "likelyGender": "male",
    "genderScale": -0.9757694244599513,
    "score": 10.622513344078705,
    "probabilityCalibrated": 0.9878847122299756
}

Genderize Name code sample for shell:

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

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
    "firstName": "John",
    "lastName": "Smith",
    "likelyGender": "male",
    "genderScale": -0.9757694244599513,
    "score": 10.622513344078705,
    "probabilityCalibrated": 0.9878847122299756
}

Genderize Name code sample for java:

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/gender/John/Smith")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.asString();

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
    "firstName": "John",
    "lastName": "Smith",
    "likelyGender": "male",
    "genderScale": -0.9757694244599513,
    "score": 10.622513344078705,
    "probabilityCalibrated": 0.9878847122299756
}

Genderize Full Name

The Genderize Full Name tool examines a full name, which includes both first and last names, to deduce its gender. The function provides the gender along with a likelihood score. Names with a likelihood score ranging between 40% and 50% are viewed as unisex.

When the first and last names are distinctly recognizable, the Genderize Name function tends to have enhanced precision.

Method:

Detail: Delivers the probable gender for up to 100 undivided full names.
Accuracy:
Cost: 1 credit per name.
Test: Genderize Full Name feature.

HTTP request:

POST

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

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Request body:
Name	Type	Required	Detail
`personalNames`	Array of objects	Required	A list of personal full names.
`[{...}].id`	String	Optional	Unique identifier.
`[{...}].name`	String	Required	A combined full name (comprising both first and last names)..

Response:
Name	Type	Detail	Enumerators
`personalNames`	Array of objects	Roster of provided full names with determined genders.
`[{...}].script`	String	The name's script presented, in ISO 15924 notation.	Script
`[{...}].id`	String	Given unique identifier.
`[{...}].name`	String	Provided full name.
`[{...}].likelyGender`	String	Most likely gender.	Genders
`[{...}].genderScale`	Number	The gender scale spans from -1 (indicating male) to +1 (signifying female).
`[{...}].score`	Number	A greater value suggests a more dependable outcome; the score isn't normalized..
`[{...}].probabilityCalibrated`	Number	A higher value indicates a more trustworthy outcome, with a scale from 0 to 1.

Code sample:

Genderize Full Name code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullBatch", {
"method": "POST",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json",
  "Content-Type": "application/json"
},
"body": JSON.stringify({
  "personalNames": [
    {
      "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
      "name": "John Smith"
    }
  ]
})
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

Body parameter:

{
  "personalNames": [
    {
      "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
      "name": "John Smith"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
            "name": "John Smith",
            "likelyGender": "male",
            "genderScale": -0.929374967691815,
            "score": 11.53988881064575,
            "probabilityCalibrated": 0.9646874838459075
        }
    ]
}

Genderize Full Name code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullBatch"

payload = {
  "personalNames": [
    {
      "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
      "name": "John Smith"
    }
  ]
}
headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json",
"Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Body parameter:

{
  "personalNames": [
    {
      "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
      "name": "John Smith"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
            "name": "John Smith",
            "likelyGender": "male",
            "genderScale": -0.929374967691815,
            "score": 11.53988881064575,
            "probabilityCalibrated": 0.9646874838459075
        }
    ]
}

Genderize 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":"0b81a1d0-b625-4a89-b4f8-8fee1d1326ce","name":"John Smith"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
      "name": "John Smith"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
            "name": "John Smith",
            "likelyGender": "male",
            "genderScale": -0.929374967691815,
            "score": 11.53988881064575,
            "probabilityCalibrated": 0.9646874838459075
        }
    ]
}

Genderize Full Name code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"0b81a1d0-b625-4a89-b4f8-8fee1d1326ce\",\"name\":\"John Smith\"}]}")
.asString();

Body parameter:

{
  "personalNames": [
    {
      "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
      "name": "John Smith"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
            "name": "John Smith",
            "likelyGender": "male",
            "genderScale": -0.929374967691815,
            "score": 11.53988881064575,
            "probabilityCalibrated": 0.9646874838459075
        }
    ]
}

For GET method requests, every parameter is mandatory. For a smoother experience with our requests, we suggest opting for the POST method.

Detail: Estimate the gender from a complete, undivided name.
Accuracy:
Cost: 1 credit per name.
Test: Genderize Full Name feature.

HTTP request:

GET

https://v2.namsor.com/NamSorAPIv2/api2/json/genderFull/{name}

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Request parameters
Name	Type	Required	Detail
`name`	String	Required	A combined full name (comprising both first and last names)..

Response:
Name	Type	Detail	Enumerators
`script`	String	The name's script presented, in ISO 15924 notation.	Script
`id`	String	Unique identifier.
`name`	String	Provided full name.
`likelyGender`	String	Most likely gender.	Genders
`genderScale`	Number	The gender scale spans from -1 (indicating male) to +1 (signifying female).
`score`	Number	A greater value suggests a more dependable outcome; the score isn't normalized..
`probabilityCalibrated`	Number	A higher value indicates a more trustworthy outcome, with a scale from 0 to 1.

Code sample:

Genderize Full Name code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFull/John%20Smith", {
"method": "GET",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json"
}
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
    "name": "John Smith",
    "likelyGender": "male",
    "genderScale": -0.929374967691815,
    "score": 11.53988881064575,
    "probabilityCalibrated": 0.9646874838459075
}

Genderize Full Name code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderFull/John%20Smith"

headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
    "name": "John Smith",
    "likelyGender": "male",
    "genderScale": -0.929374967691815,
    "score": 11.53988881064575,
    "probabilityCalibrated": 0.9646874838459075
}

Genderize Full Name code sample for shell:

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

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
    "name": "John Smith",
    "likelyGender": "male",
    "genderScale": -0.929374967691815,
    "score": 11.53988881064575,
    "probabilityCalibrated": 0.9646874838459075
}

Genderize Full Name code sample for java:

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFull/John%20Smith")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.asString();

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
    "name": "John Smith",
    "likelyGender": "male",
    "genderScale": -0.929374967691815,
    "score": 11.53988881064575,
    "probabilityCalibrated": 0.9646874838459075
}

Gender from names improved with a local context

Identify the gender using a specified name and, when available, a surname, or a whole full name. The accuracy is heightened when local context clues, such as country of residence or origin, are provided. By considering this localized or cultural backdrop, the system examines the name against its environmental, historical, and modern influences. This approach refines the system's capacity to precisely gauge the gender linked with the name.

Genderize Name Geo

The Genderize Name Geo tool scrutinizes a first name and, if provided, a last name, taking into account the local context (country of origin or residence), to pinpoint the most likely gender. This approach offers heightened accuracy compared to the standard Genderize Name function, especially when both first and last names are supplied. It provides the most likely gender along with a normalized probability. Names with gender probabilities ranging between 40% and 50% are viewed as gender-neutral.

Method:

Detail: Provides the probable gender for up to 100 first names, with optional last names, based on their regional background.
Accuracy:
Cost: 1 credit per name.
Test: Genderize Name Geo feature.

HTTP request:

POST

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

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Request body:
Name	Type	Required	Detail
`personalNames`	Array of objects	Required	A compilation of individual names along with their associated local backgrounds.
`[{...}].id`	String	Optional	Unique identifier.
`[{...}].firstName`	String	Required	First name, given name, nickname.
`[{...}].lastName`	String	Optional	Last name, family name, surname.
`[{...}].countryIso2`	String	Required	Local context (country of residence, country of origin, etc), in ISO 3166-1 alpha-2 format.

Response:
Name	Type	Detail	Enumerators
`personalNames`	Array of objects	Roster of submited names with their assigned genders.
`[{...}].script`	String	The name's script presented, in ISO 15924 notation.	Script
`[{...}].id`	String	Given unique identifier.
`[{...}].firstName`	String	Provided first name.
`[{...}].lastName`	String	Provided last name.
`[{...}].likelyGender`	String	Most likely gender.	Genders
`[{...}].genderScale`	Number	The gender scale spans from -1 (indicating male) to +1 (signifying female).
`[{...}].score`	Number	A greater value suggests a more dependable outcome; the score isn't normalized..
`[{...}].probabilityCalibrated`	Number	A higher value indicates a more trustworthy outcome, with a scale from 0 to 1.

Code sample:

Genderize Name Geo code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeoBatch", {
"method": "POST",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json",
  "Content-Type": "application/json"
},
"body": JSON.stringify({
  "personalNames": [
    {
      "id": "fbd28ba3-7a9d-46e3-8f6f-a8cbc71e0ee2",
      "firstName": "John",
      "lastName": "Smith",
      "countryIso2": "US"
    }
  ]
})
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

Body parameter:

{
  "personalNames": [
    {
      "id": "fbd28ba3-7a9d-46e3-8f6f-a8cbc71e0ee2",
      "firstName": "John",
      "lastName": "Smith",
      "countryIso2": "US"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "fbd28ba3-7a9d-46e3-8f6f-a8cbc71e0ee2",
            "firstName": "John",
            "lastName": "Smith",
            "likelyGender": "male",
            "genderScale": -0.9999601946111383,
            "score": 17.734397494023867,
            "probabilityCalibrated": 0.9999800973055691
        }
    ]
}

Genderize Name Geo code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeoBatch"

payload = {
  "personalNames": [
    {
      "id": "fbd28ba3-7a9d-46e3-8f6f-a8cbc71e0ee2",
      "firstName": "John",
      "lastName": "Smith",
      "countryIso2": "US"
    }
  ]
}
headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json",
"Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Body parameter:

{
  "personalNames": [
    {
      "id": "fbd28ba3-7a9d-46e3-8f6f-a8cbc71e0ee2",
      "firstName": "John",
      "lastName": "Smith",
      "countryIso2": "US"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "fbd28ba3-7a9d-46e3-8f6f-a8cbc71e0ee2",
            "firstName": "John",
            "lastName": "Smith",
            "likelyGender": "male",
            "genderScale": -0.9999601946111383,
            "score": 17.734397494023867,
            "probabilityCalibrated": 0.9999800973055691
        }
    ]
}

Genderize Name 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":"fbd28ba3-7a9d-46e3-8f6f-a8cbc71e0ee2","firstName":"John","lastName":"Smith","countryIso2":"US"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "fbd28ba3-7a9d-46e3-8f6f-a8cbc71e0ee2",
      "firstName": "John",
      "lastName": "Smith",
      "countryIso2": "US"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "fbd28ba3-7a9d-46e3-8f6f-a8cbc71e0ee2",
            "firstName": "John",
            "lastName": "Smith",
            "likelyGender": "male",
            "genderScale": -0.9999601946111383,
            "score": 17.734397494023867,
            "probabilityCalibrated": 0.9999800973055691
        }
    ]
}

Genderize Name Geo code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderGeoBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"fbd28ba3-7a9d-46e3-8f6f-a8cbc71e0ee2\",\"firstName\":\"John\",\"lastName\":\"Smith\",\"countryIso2\":\"US\"}]}")
.asString();

Body parameter:

{
  "personalNames": [
    {
      "id": "fbd28ba3-7a9d-46e3-8f6f-a8cbc71e0ee2",
      "firstName": "John",
      "lastName": "Smith",
      "countryIso2": "US"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "fbd28ba3-7a9d-46e3-8f6f-a8cbc71e0ee2",
            "firstName": "John",
            "lastName": "Smith",
            "likelyGender": "male",
            "genderScale": -0.9999601946111383,
            "score": 17.734397494023867,
            "probabilityCalibrated": 0.9999800973055691
        }
    ]
}

For GET method requests, every parameter is mandatory. For a smoother experience with our requests, we suggest opting for the POST method.

Detail: Estimate the most likely gender from a first name and an optional last name.
Accuracy:
Cost: 1 credit per name.
Test: Genderize Name Geo feature.

HTTP request:

GET

https://v2.namsor.com/NamSorAPIv2/api2/json/gender/{firstName}/{lastName}

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Request parameters
Name	Type	Required	Detail
`firstName`	String	Required	First name, given name, nickname.
`lastName`	String	Required	Last name, family name, surname.

Response:
Name	Type	Detail	Enumerators
`script`	String	The name's script presented, in ISO 15924 notation.	Script
`id`	String	Unique identifier.
`firstName`	String	Provided first name.
`lastName`	String	Provided last name.
`likelyGender`	String	Most likely gender.	Genders
`genderScale`	Number	The gender scale spans from -1 (indicating male) to +1 (signifying female).
`score`	Number	A greater value suggests a more dependable outcome; the score isn't normalized..
`probabilityCalibrated`	Number	A higher value indicates a more trustworthy outcome, with a scale from 0 to 1.

Code sample:

Genderize Name code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/gender/John/Smith", {
"method": "GET",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json"
}
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
    "firstName": "John",
    "lastName": "Smith",
    "likelyGender": "male",
    "genderScale": -0.9757694244599513,
    "score": 10.622513344078705,
    "probabilityCalibrated": 0.9878847122299756
}

Genderize Name code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/gender/John/Smith"

headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
    "firstName": "John",
    "lastName": "Smith",
    "likelyGender": "male",
    "genderScale": -0.9757694244599513,
    "score": 10.622513344078705,
    "probabilityCalibrated": 0.9878847122299756
}

Genderize Name code sample for shell:

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

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
    "firstName": "John",
    "lastName": "Smith",
    "likelyGender": "male",
    "genderScale": -0.9757694244599513,
    "score": 10.622513344078705,
    "probabilityCalibrated": 0.9878847122299756
}

Genderize Name code sample for java:

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/gender/John/Smith")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.asString();

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "59b9393d-8dc4-464e-a26e-6b6841621e24",
    "firstName": "John",
    "lastName": "Smith",
    "likelyGender": "male",
    "genderScale": -0.9757694244599513,
    "score": 10.622513344078705,
    "probabilityCalibrated": 0.9878847122299756
}

Genderize Full Name Geo

The Genderize Full Name Geo tool scrutinizes a full name, which includes both the first and last names, factoring in the country of residence, to pinpoint its most likely gender. This approach offers greater precision than the standard Genderize Full Name function. It provides the gender as well as a probability. Names with a probability close to 50% are considered unisex.

When the first and last names are distinctly recognizable, the Genderize Name Geo function tends to have enhanced precision.

Method:

Detail: Provides the probable gender for up to 100 whole full names based on their regional background.
Accuracy:
Cost: 1 credit per name.
Test: Genderize Full Name Geo feature.

HTTP request:

POST

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

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Request body:
Name	Type	Required	Detail
`personalNames`	Array of objects	Required	A roster of individual names with their associated local backgrounds.
`[{...}].id`	String	Optional	Unique identifier.
`[{...}].name`	String	Required	A combined full name (comprising both first and last names)..
`[{...}].countryIso2`	String	Required	Local context (country of residence, country of origin, etc), in ISO 3166-1 alpha-2 format.

Response:
Name	Type	Detail	Enumerators
`personalNames`	Array of objects	Roster of provided full names with determined genders.
`[{...}].script`	String	The name's script presented, in ISO 15924 notation.	Script
`[{...}].id`	String	Given unique identifier.
`[{...}].name`	String	Provided full name.
`[{...}].likelyGender`	String	Most likely gender.	Genders
`[{...}].genderScale`	Number	The gender scale spans from -1 (indicating male) to +1 (signifying female).
`[{...}].score`	Number	A greater value suggests a more dependable outcome; the score isn't normalized..
`[{...}].probabilityCalibrated`	Number	A higher value indicates a more trustworthy outcome, with a scale from 0 to 1.

Code sample:

Genderize Full Name Geo code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeoBatch", {
"method": "POST",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json",
  "Content-Type": "application/json"
},
"body": JSON.stringify({
  "personalNames": [
    {
      "id": "db97a06b-21e5-4716-b214-4310f2c27b34",
      "name": "John Smith",
      "countryIso2": "US"
    }
  ]
})
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

Body parameter:

{
  "personalNames": [
    {
      "id": "db97a06b-21e5-4716-b214-4310f2c27b34",
      "name": "John Smith",
      "countryIso2": "US"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "db97a06b-21e5-4716-b214-4310f2c27b34",
            "name": "John Smith",
            "likelyGender": "male",
            "genderScale": -0.929844340168597,
            "score": 11.61845253624304,
            "probabilityCalibrated": 0.9649221700842985
        }
    ]
}

Genderize Full Name Geo code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeoBatch"

payload = {
  "personalNames": [
    {
      "id": "db97a06b-21e5-4716-b214-4310f2c27b34",
      "name": "John Smith",
      "countryIso2": "US"
    }
  ]
}
headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json",
"Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Body parameter:

{
  "personalNames": [
    {
      "id": "db97a06b-21e5-4716-b214-4310f2c27b34",
      "name": "John Smith",
      "countryIso2": "US"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "db97a06b-21e5-4716-b214-4310f2c27b34",
            "name": "John Smith",
            "likelyGender": "male",
            "genderScale": -0.929844340168597,
            "score": 11.61845253624304,
            "probabilityCalibrated": 0.9649221700842985
        }
    ]
}

Genderize 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":"db97a06b-21e5-4716-b214-4310f2c27b34","name":"John Smith","countryIso2":"US"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "db97a06b-21e5-4716-b214-4310f2c27b34",
      "name": "John Smith",
      "countryIso2": "US"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "db97a06b-21e5-4716-b214-4310f2c27b34",
            "name": "John Smith",
            "likelyGender": "male",
            "genderScale": -0.929844340168597,
            "score": 11.61845253624304,
            "probabilityCalibrated": 0.9649221700842985
        }
    ]
}

Genderize Full Name Geo code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFullGeoBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"db97a06b-21e5-4716-b214-4310f2c27b34\",\"name\":\"John Smith\",\"countryIso2\":\"US\"}]}")
.asString();

Body parameter:

{
  "personalNames": [
    {
      "id": "db97a06b-21e5-4716-b214-4310f2c27b34",
      "name": "John Smith",
      "countryIso2": "US"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "db97a06b-21e5-4716-b214-4310f2c27b34",
            "name": "John Smith",
            "likelyGender": "male",
            "genderScale": -0.929844340168597,
            "score": 11.61845253624304,
            "probabilityCalibrated": 0.9649221700842985
        }
    ]
}

For GET method requests, every parameter is mandatory. For a smoother experience with our requests, we suggest opting for the POST method.

Detail: Estimate the gender from a complete, undivided name.
Accuracy:
Cost: 1 credit per name.
Test: Genderize Full Name Geo feature.

HTTP request:

GET

https://v2.namsor.com/NamSorAPIv2/api2/json/genderFull/{name}

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Request parameters
Name	Type	Required	Detail
`name`	String	Required	A combined full name (comprising both first and last names)..

Response:
Name	Type	Detail	Enumerators
`script`	String	The name's script presented, in ISO 15924 notation.	Script
`id`	String	Unique identifier.
`name`	String	Provided full name.
`likelyGender`	String	Most likely gender.	Genders
`genderScale`	Number	The gender scale spans from -1 (indicating male) to +1 (signifying female).
`score`	Number	A greater value suggests a more dependable outcome; the score isn't normalized..
`probabilityCalibrated`	Number	A higher value indicates a more trustworthy outcome, with a scale from 0 to 1.

Code sample:

Genderize Full Name code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFull/John%20Smith", {
"method": "GET",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json"
}
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
    "name": "John Smith",
    "likelyGender": "male",
    "genderScale": -0.929374967691815,
    "score": 11.53988881064575,
    "probabilityCalibrated": 0.9646874838459075
}

Genderize Full Name code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderFull/John%20Smith"

headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
    "name": "John Smith",
    "likelyGender": "male",
    "genderScale": -0.929374967691815,
    "score": 11.53988881064575,
    "probabilityCalibrated": 0.9646874838459075
}

Genderize Full Name code sample for shell:

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

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
    "name": "John Smith",
    "likelyGender": "male",
    "genderScale": -0.929374967691815,
    "score": 11.53988881064575,
    "probabilityCalibrated": 0.9646874838459075
}

Genderize Full Name code sample for java:

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/genderFull/John%20Smith")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.asString();

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "0b81a1d0-b625-4a89-b4f8-8fee1d1326ce",
    "name": "John Smith",
    "likelyGender": "male",
    "genderScale": -0.929374967691815,
    "score": 11.53988881064575,
    "probabilityCalibrated": 0.9646874838459075
}

Chinese names

Assesses a Chinese given name and, when supplied, a surname, or an intact Chinese full name, using both Mandarin Chinese and its Latin transcription (Pinyin). This evaluation seeks to more precisely identify the associated gender.

Genderize Chinese Name

The Genderize Chinese Name tool precisely determines the gender of a Chinese first name, with an optional surname, written in either Pinyin or Standard Mandarin Chinese. Its accuracy is marginally better than the Genderize Chinese Full Name function. It offers the most likely gender along with an adjusted probability. Names that have a gender probability ranging between 40% and 50% are deemed gender-neutral.

Method:

Detail: Delivers the probable gender for up to 100 first names, with optional surnames, presented in Pinyin or Standard Mandarin Chinese.
Accuracy:
Cost: 1 credit per name.
Test: Genderize Chinese Name feature.

HTTP request:

POST

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

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Request body:
Name	Type	Required	Detail
`personalNames`	Array of objects	Required	A compilation of Chinese names.
`[{...}].id`	String	Optional	Unique identifier.
`[{...}].firstName`	String	Required	Chinese given name (first name) in Pinyin or standard Mandarin Chinese.
`[{...}].lastName`	String	Optional	Chinese surname (last name) in Pinyin or standard Mandarin Chinese.

Response:
Name	Type	Detail	Enumerators
`personalNames`	Array of objects	Roster of provided Chinese names with their assigned genders.
`[{...}].script`	String	The name's script presented, in ISO 15924 notation.	Script
`[{...}].id`	String	Given unique identifier.
`[{...}].firstName`	String	Provided given name.
`[{...}].lastName`	String	Provided surname.
`[{...}].likelyGender`	String	Most likely gender.	Genders
`[{...}].genderScale`	Number	The gender scale spans from -1 (indicating male) to +1 (signifying female).
`[{...}].score`	Number	A greater value suggests a more dependable outcome; the score isn't normalized..
`[{...}].probabilityCalibrated`	Number	A higher value indicates a more trustworthy outcome, with a scale from 0 to 1.

Code sample:

Genderize Chinese Name code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNamePinyinBatch", {
"method": "POST",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json",
  "Content-Type": "application/json"
},
"body": JSON.stringify({
  "personalNames": [
    {
      "id": "ba5ec5bb-3bf2-4662-b9ec-434f76559fbf",
      "firstName": "Xiaoming",
      "lastName": "Wang"
    }
  ]
})
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

Body parameter:

{
  "personalNames": [
    {
      "id": "ba5ec5bb-3bf2-4662-b9ec-434f76559fbf",
      "firstName": "Xiaoming",
      "lastName": "Wang"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "ba5ec5bb-3bf2-4662-b9ec-434f76559fbf",
            "firstName": "Xiaoming ",
            "lastName": "Wang",
            "likelyGender": "female",
            "genderScale": 0.2579147656089782,
            "score": 1.5028819454087738,
            "probabilityCalibrated": 0.6289573828044891
        }
    ]
}

Genderize Chinese Name code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNamePinyinBatch"

payload = {
  "personalNames": [
    {
      "id": "ba5ec5bb-3bf2-4662-b9ec-434f76559fbf",
      "firstName": "Xiaoming",
      "lastName": "Wang"
    }
  ]
}
headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json",
"Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Body parameter:

{
  "personalNames": [
    {
      "id": "ba5ec5bb-3bf2-4662-b9ec-434f76559fbf",
      "firstName": "Xiaoming",
      "lastName": "Wang"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "ba5ec5bb-3bf2-4662-b9ec-434f76559fbf",
            "firstName": "Xiaoming ",
            "lastName": "Wang",
            "likelyGender": "female",
            "genderScale": 0.2579147656089782,
            "score": 1.5028819454087738,
            "probabilityCalibrated": 0.6289573828044891
        }
    ]
}

Genderize Chinese Name 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":"ba5ec5bb-3bf2-4662-b9ec-434f76559fbf","firstName":"Xiaoming","lastName":"Wang"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "ba5ec5bb-3bf2-4662-b9ec-434f76559fbf",
      "firstName": "Xiaoming",
      "lastName": "Wang"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "ba5ec5bb-3bf2-4662-b9ec-434f76559fbf",
            "firstName": "Xiaoming ",
            "lastName": "Wang",
            "likelyGender": "female",
            "genderScale": 0.2579147656089782,
            "score": 1.5028819454087738,
            "probabilityCalibrated": 0.6289573828044891
        }
    ]
}

Genderize Chinese Name code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNamePinyinBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"ba5ec5bb-3bf2-4662-b9ec-434f76559fbf\",\"firstName\":\"Xiaoming\",\"lastName\":\"Wang\"}]}")
.asString();

Body parameter:

{
  "personalNames": [
    {
      "id": "ba5ec5bb-3bf2-4662-b9ec-434f76559fbf",
      "firstName": "Xiaoming",
      "lastName": "Wang"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "ba5ec5bb-3bf2-4662-b9ec-434f76559fbf",
            "firstName": "Xiaoming ",
            "lastName": "Wang",
            "likelyGender": "female",
            "genderScale": 0.2579147656089782,
            "score": 1.5028819454087738,
            "probabilityCalibrated": 0.6289573828044891
        }
    ]
}

For GET method requests, every parameter is mandatory. For a smoother experience with our requests, we suggest opting for the POST method.

Detail: Provides the probable gender of a Chinese first name and surname, whether in Pinyin or Standard Mandarin Chinese.
Accuracy:
Cost: 1 credit per name.
Test: Genderize Chinese Name feature.

HTTP request:

GET

https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNamePinyin/{lastName}/{firstName}

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Request parameters
Name	Type	Required	Detail
`lastName`	String	Required	Chinese surname (last name) in Pinyin or Mandarin Chinese.
`firstName`	String	Required	Chinese given name (first name) in Pinyin or Mandarin Chinese.

Response:
Name	Type	Detail	Enumerators
`script`	String	The name's script presented, in ISO 15924 notation.	Script
`id`	String	Unique identifier.
`firstName`	String	Provided given name.
`lastName`	String	Provided surname.
`likelyGender`	String	Most likely gender.	Genders
`genderScale`	Number	The gender scale spans from -1 (indicating male) to +1 (signifying female).
`score`	Number	A greater value suggests a more dependable outcome; the score isn't normalized..
`probabilityCalibrated`	Number	A higher value indicates a more trustworthy outcome, with a scale from 0 to 1.

Code sample:

Genderize Chinese Name code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNamePinyin/Wang/Xiaoming", {
"method": "GET",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json"
}
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "ba5ec5bb-3bf2-4662-b9ec-434f76559fbf",
    "firstName": "Xiaoming ",
    "lastName": "Wang",
    "likelyGender": "female",
    "genderScale": 0.2579147656089782,
    "score": 1.5028819454087738,
    "probabilityCalibrated": 0.6289573828044891
}

Genderize Chinese Name code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNamePinyin/Wang/Xiaoming"

headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "ba5ec5bb-3bf2-4662-b9ec-434f76559fbf",
    "firstName": "Xiaoming ",
    "lastName": "Wang",
    "likelyGender": "female",
    "genderScale": 0.2579147656089782,
    "score": 1.5028819454087738,
    "probabilityCalibrated": 0.6289573828044891
}

Genderize Chinese Name code sample for shell:

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

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "ba5ec5bb-3bf2-4662-b9ec-434f76559fbf",
    "firstName": "Xiaoming ",
    "lastName": "Wang",
    "likelyGender": "female",
    "genderScale": 0.2579147656089782,
    "score": 1.5028819454087738,
    "probabilityCalibrated": 0.6289573828044891
}

Genderize Chinese Name code sample for java:

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNamePinyin/Wang/Xiaoming")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.asString();

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "ba5ec5bb-3bf2-4662-b9ec-434f76559fbf",
    "firstName": "Xiaoming ",
    "lastName": "Wang",
    "likelyGender": "female",
    "genderScale": 0.2579147656089782,
    "score": 1.5028819454087738,
    "probabilityCalibrated": 0.6289573828044891
}

Genderize Chinese Full Name

The Genderize Chinese Full Name function precisely determines the gender of a whole Chinese name written in standard Mandarin. It delivers the most probable gender along with an adjusted likelihood. Names with a gender probability ranging from 40% to 50% can be considered as unisex.

The Genderize Chinese Full Name feature is exclusively compatible with Chinese full names penned in Standard Mandarin Chinese.

Method:

Detail: Provides the probable gender for a maximum of 100 unseparated Chinese full names (including family and given names) in Standard Mandarin Chinese.
Accuracy:
Cost: 1 credit per name.
Test: Genderize Chinese Full Name feature.

HTTP request:

POST

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

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Request body:
Name	Type	Required	Detail
`personalNames`	Array of objects	Required	A compilation of Chinese full names.
`[{...}].id`	String	Optional	Unique identifier.
`[{...}].name`	String	Required	Unsplit Chinese full name (given name and surname) in Standard Mandarin Chinese.

Response:
Name	Type	Detail	Enumerators
`personalNames`	Array of objects	Roster of provided Chinese full names with their assigned genders.
`[{...}].script`	String	The name's script presented, in ISO 15924 notation.	Script
`[{...}].id`	String	Given unique identifier.
`[{...}].name`	String	Provided full name.
`[{...}].likelyGender`	String	Most likely gender.	Genders
`[{...}].genderScale`	Number	The gender scale spans from -1 (indicating male) to +1 (signifying female).
`[{...}].score`	Number	A greater value suggests a more dependable outcome; the score isn't normalized..
`[{...}].probabilityCalibrated`	Number	A higher value indicates a more trustworthy outcome, with a scale from 0 to 1.

Code sample:

Genderize Chinese Full Name code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNameBatch", {
"method": "POST",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json",
  "Content-Type": "application/json"
},
"body": JSON.stringify({
  "personalNames": [
    {
      "id": "64275bed-b88c-4bd9-b915-0a189d89400d",
      "name": "王晓明"
    }
  ]
})
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

Body parameter:

{
  "personalNames": [
    {
      "id": "64275bed-b88c-4bd9-b915-0a189d89400d",
      "name": "王晓明"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "HAN",
            "id": "64275bed-b88c-4bd9-b915-0a189d89400d",
            "name": "王晓明",
            "likelyGender": "male",
            "genderScale": -0.05024680441744089,
            "score": 0.06555061355894772,
            "probabilityCalibrated": 0.5251234022087204
        }
    ]
}

Genderize Chinese Full Name code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNameBatch"

payload = {
  "personalNames": [
    {
      "id": "64275bed-b88c-4bd9-b915-0a189d89400d",
      "name": "王晓明"
    }
  ]
}
headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json",
"Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Body parameter:

{
  "personalNames": [
    {
      "id": "64275bed-b88c-4bd9-b915-0a189d89400d",
      "name": "王晓明"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "HAN",
            "id": "64275bed-b88c-4bd9-b915-0a189d89400d",
            "name": "王晓明",
            "likelyGender": "male",
            "genderScale": -0.05024680441744089,
            "score": 0.06555061355894772,
            "probabilityCalibrated": 0.5251234022087204
        }
    ]
}

Genderize Chinese Full Name 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":"64275bed-b88c-4bd9-b915-0a189d89400d","name":"王晓明"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "64275bed-b88c-4bd9-b915-0a189d89400d",
      "name": "王晓明"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "HAN",
            "id": "64275bed-b88c-4bd9-b915-0a189d89400d",
            "name": "王晓明",
            "likelyGender": "male",
            "genderScale": -0.05024680441744089,
            "score": 0.06555061355894772,
            "probabilityCalibrated": 0.5251234022087204
        }
    ]
}

Genderize Chinese Full Name code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseNameBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"64275bed-b88c-4bd9-b915-0a189d89400d\",\"name\":\"王晓明\"}]}")
.asString();

Body parameter:

{
  "personalNames": [
    {
      "id": "64275bed-b88c-4bd9-b915-0a189d89400d",
      "name": "王晓明"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "HAN",
            "id": "64275bed-b88c-4bd9-b915-0a189d89400d",
            "name": "王晓明",
            "likelyGender": "male",
            "genderScale": -0.05024680441744089,
            "score": 0.06555061355894772,
            "probabilityCalibrated": 0.5251234022087204
        }
    ]
}

For GET method requests, every parameter is mandatory. For a smoother experience with our requests, we suggest opting for the POST method.

Detail: Provides the probable gender associated with a whole Chinese name in Standard Mandarin Chinese.
Accuracy:
Cost: 1 credit per name.
Test: Genderize Chinese Full Name feature.

HTTP request:

GET

https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseName/{name}

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Request parameters
Name	Type	Required	Detail
`name`	String	Required	Unsplit Chinese full name (given name and surname) in standard Mandarin Chinese.

Response:
Name	Type	Detail	Enumerators
`script`	String	The name's script presented, in ISO 15924 notation.	Script
`id`	String	Unique identifier.
`name`	String	Provided full name.
`likelyGender`	String	Most likely gender.	Genders
`genderScale`	Number	The gender scale spans from -1 (indicating male) to +1 (signifying female).
`score`	Number	A greater value suggests a more dependable outcome; the score isn't normalized..
`probabilityCalibrated`	Number	A higher value indicates a more trustworthy outcome, with a scale from 0 to 1.

Code sample:

Genderize Chinese Full Name code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseName/王晓明", {
"method": "GET",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json"
}
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

The above command produces a JSON structure as follows:

{
    "script": "HAN",
    "id": "64275bed-b88c-4bd9-b915-0a189d89400d",
    "name": "王晓明",
    "likelyGender": "male",
    "genderScale": -0.05024680441744089,
    "score": 0.06555061355894772,
    "probabilityCalibrated": 0.5251234022087204
}

Genderize Chinese Full Name code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseName/王晓明"

headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

The above command produces a JSON structure as follows:

{
    "script": "HAN",
    "id": "64275bed-b88c-4bd9-b915-0a189d89400d",
    "name": "王晓明",
    "likelyGender": "male",
    "genderScale": -0.05024680441744089,
    "score": 0.06555061355894772,
    "probabilityCalibrated": 0.5251234022087204
}

Genderize Chinese Full Name code sample for shell:

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

The above command produces a JSON structure as follows:

{
    "script": "HAN",
    "id": "64275bed-b88c-4bd9-b915-0a189d89400d",
    "name": "王晓明",
    "likelyGender": "male",
    "genderScale": -0.05024680441744089,
    "score": 0.06555061355894772,
    "probabilityCalibrated": 0.5251234022087204
}

Genderize Chinese Full Name code sample for java:

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/genderChineseName/王晓明")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.asString();

The above command produces a JSON structure as follows:

{
    "script": "HAN",
    "id": "64275bed-b88c-4bd9-b915-0a189d89400d",
    "name": "王晓明",
    "likelyGender": "male",
    "genderScale": -0.05024680441744089,
    "score": 0.06555061355894772,
    "probabilityCalibrated": 0.5251234022087204
}

Japanese names

Assesses a Japanese given name, and when provided, a surname, or a complete unified Japanese name, using Kanji or Latin characters. The goal is to determine the gender that's most probable with heightened accuracy.

Genderize Japanese Name

The Genderize Japanese Name tool adeptly determines the gender of a Japanese first name and, if provided, a surname, written in either Kanji or Latin script. Its precision is marginally superior to that of the Genderize Japanese Full Name function. Names with a probability close to 50% can be considered as gender-neutral.

Method:

Detail: Delivers the probable gender for up to 100 Japanese first names, with optional surnames, whether penned in the Latin script or Kanji characters.
Accuracy:
Cost: 1 credit per name.
Test: Genderize Japanese Name feature.

HTTP request:

POST

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

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Request body:
Name	Type	Required	Detail
`personalNames`	Array of objects	Required	A compilation of Japanese names.
`[{...}].id`	String	Optional	Unique identifier.
`[{...}].firstName`	String	Required	Japanese given name represented in either Latin or Kanji script.
`[{...}].lastName`	String	Optional	Japanese surname represented in either Latin or Kanji script.

Response:
Name	Type	Detail	Enumerators
`personalNames`	Array of objects	Roster of provided Japanese names with their assigned genders.
`[{...}].script`	String	The name's script presented, in ISO 15924 notation.	Script
`[{...}].id`	String	Given unique identifier.
`[{...}].firstName`	String	Provided given name.
`[{...}].lastName`	String	Provided surname.
`[{...}].likelyGender`	String	Most likely gender.	Genders
`[{...}].genderScale`	Number	The gender scale spans from -1 (indicating male) to +1 (signifying female).
`[{...}].score`	Number	A greater value suggests a more dependable outcome; the score isn't normalized..
`[{...}].probabilityCalibrated`	Number	A higher value indicates a more trustworthy outcome, with a scale from 0 to 1.

Code sample:

Genderize Japanese Name code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameBatch", {
"method": "POST",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json",
  "Content-Type": "application/json"
},
"body": JSON.stringify({
  "personalNames": [
    {
      "id": "230fa70e-8c2e-4e70-beeb-93ac08ac4038",
      "firstName": "Sanae",
      "lastName": "Yamamoto"
    }
  ]
})
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

Body parameter:

{
  "personalNames": [
    {
      "id": "230fa70e-8c2e-4e70-beeb-93ac08ac4038",
      "firstName": "Sanae",
      "lastName": "Yamamoto"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "230fa70e-8c2e-4e70-beeb-93ac08ac4038",
            "firstName": "Sanae",
            "lastName": "Yamamoto",
            "likelyGender": "female",
            "genderScale": 0.9999279399338183,
            "score": 17.14089975408791,
            "probabilityCalibrated": 0.9999639699669092
        }
    ]
}

Genderize Japanese Name code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameBatch"

payload = {
  "personalNames": [
    {
      "id": "230fa70e-8c2e-4e70-beeb-93ac08ac4038",
      "firstName": "Sanae",
      "lastName": "Yamamoto"
    }
  ]
}
headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json",
"Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Body parameter:

{
  "personalNames": [
    {
      "id": "230fa70e-8c2e-4e70-beeb-93ac08ac4038",
      "firstName": "Sanae",
      "lastName": "Yamamoto"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "230fa70e-8c2e-4e70-beeb-93ac08ac4038",
            "firstName": "Sanae",
            "lastName": "Yamamoto",
            "likelyGender": "female",
            "genderScale": 0.9999279399338183,
            "score": 17.14089975408791,
            "probabilityCalibrated": 0.9999639699669092
        }
    ]
}

Genderize Japanese Name 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":"230fa70e-8c2e-4e70-beeb-93ac08ac4038","firstName":"Sanae","lastName":"Yamamoto"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "230fa70e-8c2e-4e70-beeb-93ac08ac4038",
      "firstName": "Sanae",
      "lastName": "Yamamoto"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "230fa70e-8c2e-4e70-beeb-93ac08ac4038",
            "firstName": "Sanae",
            "lastName": "Yamamoto",
            "likelyGender": "female",
            "genderScale": 0.9999279399338183,
            "score": 17.14089975408791,
            "probabilityCalibrated": 0.9999639699669092
        }
    ]
}

Genderize Japanese Name code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"230fa70e-8c2e-4e70-beeb-93ac08ac4038\",\"firstName\":\"Sanae\",\"lastName\":\"Yamamoto\"}]}")
.asString();

Body parameter:

{
  "personalNames": [
    {
      "id": "230fa70e-8c2e-4e70-beeb-93ac08ac4038",
      "firstName": "Sanae",
      "lastName": "Yamamoto"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "LATIN",
            "id": "230fa70e-8c2e-4e70-beeb-93ac08ac4038",
            "firstName": "Sanae",
            "lastName": "Yamamoto",
            "likelyGender": "female",
            "genderScale": 0.9999279399338183,
            "score": 17.14089975408791,
            "probabilityCalibrated": 0.9999639699669092
        }
    ]
}

For GET method requests, every parameter is mandatory. For a smoother experience with our requests, we suggest opting for the POST method.

Detail: Provides the probable gender of a Japanese given name and surname, whether expressed in Latin script or Kanji characters.
Accuracy:
Cost: 1 credit per name.
Test: Genderize Japanese Name feature.

HTTP request:

GET

https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseName/{lastName}/{firstName}

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Request parameters
Name	Type	Required	Detail
`lastName`	String	Required	Japanese surname represented in either Latin or Kanji script.
`firstName`	String	Required	Japanese given name represented in either Latin or Kanji script.

Response:
Name	Type	Detail	Enumerators
`script`	String	The name's script presented, in ISO 15924 notation.	Script
`id`	String	Unique identifier.
`firstName`	String	Provided given name.
`lastName`	String	Provided surname.
`likelyGender`	String	Most likely gender.	Genders
`genderScale`	Number	The gender scale spans from -1 (indicating male) to +1 (signifying female).
`score`	Number	A greater value suggests a more dependable outcome; the score isn't normalized..
`probabilityCalibrated`	Number	A higher value indicates a more trustworthy outcome, with a scale from 0 to 1.

Code sample:

Genderize Japanese Name code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseName/Yamamoto/Sanae", {
"method": "GET",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json"
}
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "230fa70e-8c2e-4e70-beeb-93ac08ac4038",
    "firstName": "Sanae",
    "lastName": "Yamamoto",
    "likelyGender": "female",
    "genderScale": 0.9999279399338183,
    "score": 17.14089975408791,
    "probabilityCalibrated": 0.9999639699669092
}

Genderize Japanese Name code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseName/Yamamoto/Sanae"

headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "230fa70e-8c2e-4e70-beeb-93ac08ac4038",
    "firstName": "Sanae",
    "lastName": "Yamamoto",
    "likelyGender": "female",
    "genderScale": 0.9999279399338183,
    "score": 17.14089975408791,
    "probabilityCalibrated": 0.9999639699669092
}

Genderize Japanese Name code sample for shell:

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

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "230fa70e-8c2e-4e70-beeb-93ac08ac4038",
    "firstName": "Sanae",
    "lastName": "Yamamoto",
    "likelyGender": "female",
    "genderScale": 0.9999279399338183,
    "score": 17.14089975408791,
    "probabilityCalibrated": 0.9999639699669092
}

Genderize Japanese Name code sample for java:

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseName/Yamamoto/Sanae")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.asString();

The above command produces a JSON structure as follows:

{
    "script": "LATIN",
    "id": "230fa70e-8c2e-4e70-beeb-93ac08ac4038",
    "firstName": "Sanae",
    "lastName": "Yamamoto",
    "likelyGender": "female",
    "genderScale": 0.9999279399338183,
    "score": 17.14089975408791,
    "probabilityCalibrated": 0.9999639699669092
}

Genderize Japanese Full Name

The Genderize Japanese Full Name tool precisely determines the gender of a whole Japanese name, comprising both surname and first name, penned in Kanji or the Latin script. Names with a gender probability spanning between 40% and 50% are viewed as unisex.

When the given and surname are distinctly recognizable, the Genderize Japanese Name function tends to have enhanced precision.

Method:

Detail: Provides the probable gender for up to 100 Japanese full names, including surnames and given names, whether penned in Kanji or the Latin script.
Accuracy:
Cost: 1 credit per name.
Test: Genderize Japanese Full Name feature.

HTTP request:

POST

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

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Request body:
Name	Type	Required	Detail
`personalNames`	Array of objects	Required	A compilation of Japanese full names.
`[{...}].id`	String	Optional	Unique identifier.
`[{...}].name`	String	Required	Unsplit Japanese full name (given name and surname) in Kanji or Latin alphabet.

Response:
Name	Type	Detail	Enumerators
`personalNames`	Array of objects	Roster of provided Japanese full names with their assigned genders.
`[{...}].script`	String	The name's script presented, in ISO 15924 notation.	Script
`[{...}].id`	String	Given unique identifier.
`[{...}].name`	String	Provided full name.
`[{...}].likelyGender`	String	Most likely gender.	Genders
`[{...}].genderScale`	Number	The gender scale spans from -1 (indicating male) to +1 (signifying female).
`[{...}].score`	Number	A greater value suggests a more dependable outcome; the score isn't normalized..
`[{...}].probabilityCalibrated`	Number	A higher value indicates a more trustworthy outcome, with a scale from 0 to 1.

Code sample:

Genderize Japanese Full Name code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFullBatch", {
"method": "POST",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json",
  "Content-Type": "application/json"
},
"body": JSON.stringify({
  "personalNames": [
    {
      "id": "04ac145e-6636-4f61-869e-1345a2a31dea",
      "name": "早苗 山本"
    }
  ]
})
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

Body parameter:

{
  "personalNames": [
    {
      "id": "04ac145e-6636-4f61-869e-1345a2a31dea",
      "name": "早苗 山本"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "HAN",
            "id": "8c34c749-279c-4de8-b588-9cda951c9fdd",
            "name": "早苗 山本",
            "likelyGender": "female",
            "genderScale": 0.9824793433203705,
            "score": 26.120365131524423,
            "probabilityCalibrated": 0.9912396716601852
        }
    ]
}

Genderize Japanese Full Name code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFullBatch"

payload = {
  "personalNames": [
    {
      "id": "04ac145e-6636-4f61-869e-1345a2a31dea",
      "name": "早苗 山本"
    }
  ]
}
headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json",
"Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Body parameter:

{
  "personalNames": [
    {
      "id": "04ac145e-6636-4f61-869e-1345a2a31dea",
      "name": "早苗 山本"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "HAN",
            "id": "8c34c749-279c-4de8-b588-9cda951c9fdd",
            "name": "早苗 山本",
            "likelyGender": "female",
            "genderScale": 0.9824793433203705,
            "score": 26.120365131524423,
            "probabilityCalibrated": 0.9912396716601852
        }
    ]
}

Genderize Japanese Full Name 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":"04ac145e-6636-4f61-869e-1345a2a31dea","name":"早苗 山本"}]}'

Body parameter:

{
  "personalNames": [
    {
      "id": "04ac145e-6636-4f61-869e-1345a2a31dea",
      "name": "早苗 山本"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "HAN",
            "id": "8c34c749-279c-4de8-b588-9cda951c9fdd",
            "name": "早苗 山本",
            "likelyGender": "female",
            "genderScale": 0.9824793433203705,
            "score": 26.120365131524423,
            "probabilityCalibrated": 0.9912396716601852
        }
    ]
}

Genderize Japanese Full Name code sample for java:

HttpResponse<String> response = Unirest.post("https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFullBatch")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.body("{\"personalNames\":[{\"id\":\"04ac145e-6636-4f61-869e-1345a2a31dea\",\"name\":\"早苗 山本\"}]}")
.asString();

Body parameter:

{
  "personalNames": [
    {
      "id": "04ac145e-6636-4f61-869e-1345a2a31dea",
      "name": "早苗 山本"
    }
  ]
}

The above command produces a JSON structure as follows:

{
    "personalNames": [
        {
            "script": "HAN",
            "id": "8c34c749-279c-4de8-b588-9cda951c9fdd",
            "name": "早苗 山本",
            "likelyGender": "female",
            "genderScale": 0.9824793433203705,
            "score": 26.120365131524423,
            "probabilityCalibrated": 0.9912396716601852
        }
    ]
}

For GET method requests, every parameter is mandatory. For a smoother experience with our requests, we suggest opting for the POST method.

Detail: Identify the gender for a complete Japanese name, encompassing both surname and first name, whether in Kanji or Latin script.
Accuracy:
Cost: 1 credit per name.
Test: Genderize Japanese Full Name feature.

HTTP request:

GET

https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFull/{name}

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Request parameters
Name	Type	Required	Detail
`name`	String	Required	Unsplit Japanese full name (given name and surname) in Kanji or Latin alphabet.

Response:
Name	Type	Detail	Enumerators
`script`	String	The name's script presented, in ISO 15924 notation.	Script
`id`	String	Unique identifier.
`name`	String	Provided full name.
`likelyGender`	String	Most likely gender.	Genders
`genderScale`	Number	The gender scale spans from -1 (indicating male) to +1 (signifying female).
`score`	Number	A greater value suggests a more dependable outcome; the score isn't normalized..
`probabilityCalibrated`	Number	A higher value indicates a more trustworthy outcome, with a scale from 0 to 1.

Code sample:

Genderize Japanese Full Name code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFull/早苗%20山本", {
"method": "GET",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json"
}
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

The above command produces a JSON structure as follows:

{
    "script": "HAN",
    "id": "8c34c749-279c-4de8-b588-9cda951c9fdd",
    "name": "早苗 山本",
    "likelyGender": "female",
    "genderScale": 0.9824793433203705,
    "score": 26.120365131524423,
    "probabilityCalibrated": 0.9912396716601852
}

Genderize Japanese Full Name code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFull/早苗%20山本"

headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

The above command produces a JSON structure as follows:

{
    "script": "HAN",
    "id": "8c34c749-279c-4de8-b588-9cda951c9fdd",
    "name": "早苗 山本",
    "likelyGender": "female",
    "genderScale": 0.9824793433203705,
    "score": 26.120365131524423,
    "probabilityCalibrated": 0.9912396716601852
}

Genderize Japanese Full Name code sample for shell:

curl --request GET \ 
--url https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFull/早苗%20山本 \
--header 'X-API-KEY: your-api-key' \
--header 'Accept: application/json'

The above command produces a JSON structure as follows:

{
    "script": "HAN",
    "id": "8c34c749-279c-4de8-b588-9cda951c9fdd",
    "name": "早苗 山本",
    "likelyGender": "female",
    "genderScale": 0.9824793433203705,
    "score": 26.120365131524423,
    "probabilityCalibrated": 0.9912396716601852
}

Genderize Japanese Full Name code sample for java:

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/genderJapaneseNameFull/早苗%20山本")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.asString();

The above command produces a JSON structure as follows:

{
    "script": "HAN",
    "id": "8c34c749-279c-4de8-b588-9cda951c9fdd",
    "name": "早苗 山本",
    "likelyGender": "female",
    "genderScale": 0.9824793433203705,
    "score": 26.120365131524423,
    "probabilityCalibrated": 0.9912396716601852
}

Admin

The Admin endpoints provide a variety of administrative tools. You can view your API usage records, verify the status and accessibility of Namsor's endpoints, or investigate the enumerators available for a specific classifier. Additionally, you have the option to adjust your privacy settings or deactivate your key.

Software Version

GET

Detail: Provides the latest version of the Namsor software.
Cost: 1 credit per name.

HTTP request:

GET

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

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Response:
Name	Type	Detail
`softwareNameAndVersion`	String	API name along with its version.
`softwareVersion`	Array	Software version in array format [major, minor, patch].

Code sample:

Software Version code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/softwareVersion", {
"method": "GET",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json"
}
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

The above command produces a JSON structure as follows:

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

Software Version code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/softwareVersion"

headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

The above command produces a JSON structure as follows:

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

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 produces a JSON structure as follows:

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

Software Version code sample for java:

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/softwareVersion")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.asString();

The above command produces a JSON structure as follows:

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

Api Status

GET

Detail: Provides the existing version of Namsor software and the condition of the classifiers (API services).
Cost: 1 credit per name.

HTTP request:

GET

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

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Response:
Name	Type	Detail
`softwareVersion`	Object	Details about the software's version.
`{...}.softwareNameAndVersion`	String	API name along with its version.
`{...}.softwareVersion`	Array	Software version in array format [major, minor, patch].
`classifiers`	Array of objects	Catalog of accessible classifiers.
`[{...}].classifierName`	String	Service or classifier name.
`[{...}].serving`	Boolean	True: the classifier is active and processing requests (has achieved minimal learning and is not shutting down).
`[{...}].learning`	Boolean	True: classifier is learning.
`[{...}].shuttingDown`	Boolean	True: classifier is shutting down.
`[{...}].probabilityCalibrated`	Boolean	True: the classifier has completed its initial learning phase and provides calibrated probabilities. When it's in the initial learning stage, calibrated probabilities are set to -1.

Code sample:

Api Status code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/apiStatus", {
"method": "GET",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json"
}
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

The above command produces a JSON structure as follows:

{
    "softwareVersion": {
        "softwareNameAndVersion": "NamSorAPIv2.0.28B05",
        "softwareVersion": [
            2,
            0,
            28
        ]
    },
    "classifiers": [
        {
            "classifierName": "personalname_gender",
            "serving": true,
            "learning": true,
            "shuttingDown": false,
            "probabilityCalibrated": true
        },
        {
            "classifierName": "personalfullname_gender",
            "serving": true,
            "learning": true,
            "shuttingDown": false,
            "probabilityCalibrated": true
        }
    ]
}

Api Status code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/apiStatus"

headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

The above command produces a JSON structure as follows:

{
    "softwareVersion": {
        "softwareNameAndVersion": "NamSorAPIv2.0.28B05",
        "softwareVersion": [
            2,
            0,
            28
        ]
    },
    "classifiers": [
        {
            "classifierName": "personalname_gender",
            "serving": true,
            "learning": true,
            "shuttingDown": false,
            "probabilityCalibrated": true
        },
        {
            "classifierName": "personalfullname_gender",
            "serving": true,
            "learning": true,
            "shuttingDown": false,
            "probabilityCalibrated": true
        }
    ]
}

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 produces a JSON structure as follows:

{
    "softwareVersion": {
        "softwareNameAndVersion": "NamSorAPIv2.0.28B05",
        "softwareVersion": [
            2,
            0,
            28
        ]
    },
    "classifiers": [
        {
            "classifierName": "personalname_gender",
            "serving": true,
            "learning": true,
            "shuttingDown": false,
            "probabilityCalibrated": true
        },
        {
            "classifierName": "personalfullname_gender",
            "serving": true,
            "learning": true,
            "shuttingDown": false,
            "probabilityCalibrated": true
        }
    ]
}

Api Status code sample for java:

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/apiStatus")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.asString();

The above command produces a JSON structure as follows:

{
    "softwareVersion": {
        "softwareNameAndVersion": "NamSorAPIv2.0.28B05",
        "softwareVersion": [
            2,
            0,
            28
        ]
    },
    "classifiers": [
        {
            "classifierName": "personalname_gender",
            "serving": true,
            "learning": true,
            "shuttingDown": false,
            "probabilityCalibrated": true
        },
        {
            "classifierName": "personalfullname_gender",
            "serving": true,
            "learning": true,
            "shuttingDown": false,
            "probabilityCalibrated": true
        }
    ]
}

Available Services

GET

Detail: Provides a roster of API services (classifiers) along with their respective credit charges for usage.
Cost: 1 credit per name.

HTTP request:

GET

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

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Response:
Name	Type	Detail
`apiServices`	Array of objects	Catalog of accessible API functions.
`[{...}].serviceName`	String	Service or classifier name.
`[{...}].serviceGroup`	String	Category to which the service or classifier belong to.
`[{...}].costInUnits`	Number	Service usage fee measured in credits.

Code sample:

Available Services code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/apiServices", {
"method": "GET",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json"
}
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

The above command produces a JSON structure as follows:

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

Available Services code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/apiServices"

headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

The above command produces a JSON structure as follows:

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

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 produces a JSON structure as follows:

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

Available Services code sample for java:

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/apiServices")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.asString();

The above command produces a JSON structure as follows:

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

Taxonomy Classes

GET

Detail: Delivers a roster of potential enumerators associated with a specific classifier.
Cost: 1 credit per name.

HTTP request:

GET

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

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Request parameters
Name	Type	Required	Detail
`classifierName`	String	Required	Classifier's name.

Response:
Name	Type	Detail
`classifierName`	String	Provided classifier's name.
`taxonomyClasses`	Array	Classifier's numerators list.

Code sample:

Taxonomy Classes code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/taxonomyClasses/personalname_gender", {
"method": "GET",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json"
}
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

The above command produces a JSON structure as follows:

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

Taxonomy Classes code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/taxonomyClasses/personalname_gender"

headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

The above command produces a JSON structure as follows:

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

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 produces a JSON structure as follows:

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

Taxonomy Classes code sample for java:

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/taxonomyClasses/personalname_gender")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.asString();

The above command produces a JSON structure as follows:

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

Api Usage

GET

Detail: Delivers details about your subscription package, billing cycle, and present API consumption.
Cost: 1 credit per name.

HTTP request:

GET

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

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Response:
Name	Type	Detail
`subscription`	Object	Details about the subscription.
`{...}.apiKey`	String	Your API key for Namsor.
`{...}.planStarted`	Number	Plan's beginning date in UNIX timestamp.
`{...}.priorPlanStarted`	Number	The date when the prior plan was activated.
`{...}.planEnded`	Number	Termination date of the plan in UNIX timestamp.
`{...}.taxRate`	Number	Tax rate applied to this subscription.
`{...}.planName`	String	Subscription plan's name.
`{...}.planBaseFeesKey`	String	Plan key as per Stripe.
`{...}.planStatus`	String	Status of the subscription.
`{...}.planQuota`	Number	Overall credit count linked with this subscription.
`{...}.priceUSD`	Number	Amount in US dollars ($).
`{...}.priceOverageUSD`	Number	Additional charge in US dollars ($).
`{...}.price`	Number	Amount in the selected currency of the user.
`{...}.priceOverage`	Number	Additional charge in the user's selected currency.
`{...}.currency`	String	The currency selected by the user.
`{...}.currencyFactor`	Number	For currencies like USD, GBP, and EUR, the value is 1.
`{...}.stripeCustomerId`	String	Distinctive identifier for Stripe Customer.
`{...}.stripeStatus`	String	Status on Stripe.
`{...}.stripeSubscription`	String	Stripe's unique subscription ID.
`{...}.userId`	String	Unique user identification code.
`billingPeriod`	Object	Invoice details.
`{...}.apiKey`	String	Your API key for Namsor.
`{...}.subscriptionStarted`	Number	Start date of the subscription, represented in UNIX timestamp.
`{...}.periodStarted`	Number	Beginning date of the subscription term, in UNIX timestamp.
`{...}.periodEnded`	Number	Date when the subscription ends, in UNIX timestamp.
`{...}.stripeCurrentPeriodEnd`	Number	End date of the existing plan on Stripe.
`{...}.stripeCurrentPeriodStart`	Number	Start date of the existing plan on Stripe.
`{...}.billingStatus`	String	Billing status for the ongoing period.
`{...}.usage`	Number	Total credits consumed to date.
`{...}.softLimit`	Number	Present soft limit for this billing term.
`{...}.hardLimit`	Number	Present hard limit for this billing term.
`overageExclTax`	Number	Additional charges before tax.
`overageInclTax`	Number	Additional charges after adding tax (when relevant).
`overageCurrency`	String	Additional charges currency type.
`overageQuantity`	Number	Excess amount over the monthly limit for the ongoing subscription, represented in credits.

Code sample:

Api Usage code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsage", {
"method": "GET",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json"
}
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

The above command produces a JSON structure as follows:

{
    "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 code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsage"

headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

The above command produces a JSON structure as follows:

{
    "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 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 produces a JSON structure as follows:

{
    "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 code sample for java:

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsage")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.asString();

The above command produces a JSON structure as follows:

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

Detail: Provides an in-depth record of usage history, showcasing which services were accessed and the API key parameters that were utilized.
Cost: 1 credit per name.

HTTP request:

GET

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

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Response:
Name	Type	Detail
`detailedUsage`	Array of objects	Display historical API usage records (Note: Updated output format starting from v2.0.15).
`[{...}].apiKey`	Object	Details about the API key.
`{...}.userId`	String	Unique user identification code.
`{...}.admin`	Boolean	Does the API key possess administrative permissions.
`{...}.vetted`	Boolean	Has the API key been verified for machine learning tasks.
`{...}.learnable`	Boolean	Is the API key permitted to input data into the machine learning system.
`{...}.anonymized`	Boolean	Is the user's API key anonymized (logs using its SHA-256 hash).
`{...}.partner`	Boolean	Is the API key designated with a partner status.
`{...}.striped`	Boolean	Is the API key linked to an active Stripe account.
`{...}.corporate`	Boolean	Does the API key hold a corporate status?.
`{...}.disabled`	Boolean	Has the API key been deactivated, either temporarily or indefinitely.
`{...}.api_key`	String	The specific API key for the user.
`[{...}].apiService`	String	Service name being accessed.
`[{...}].createdDateTime`	Number	Timestamp of the analysis, represented in UNIX format.
`[{...}].totalUsage`	Number	Total credit expense for the conducted analysis.
`[{...}].lastFlushedDateTime`	Number	Timestamp marking the last reset of the counter, in UNIX format.
`[{...}].lastUsedDateTime`	Number	Timestamp of the most recent use of the API key, in UNIX format.
`[{...}].serviceFeaturesUsage`	Object	Information about the utilization of advanced functionalities.

Code sample:

Api Usage History code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsageHistory", {
"method": "GET",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json"
}
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

The above command produces a JSON structure as follows:

{
    "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 code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsageHistory"

headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

The above command produces a JSON structure as follows:

{
    "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 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 produces a JSON structure as follows:

{
    "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 code sample for java:

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsageHistory")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.asString();

The above command produces a JSON structure as follows:

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

Detail: Delivers a consolidated record of API usage, breaking down usage by service. Each data point in the "data" field aligns with a row header in the "rowHeaders" field. Similarly, every value within a data point in the "data" field matches a column header in the "colHeaders" field. Ex: To find the period of data[0], lookup rowHeaders[0]. To find the service corresponding to data[0][3], lookup colHeaders[3].
Cost: 1 credit per name.

HTTP request:

GET

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

Request header:
Property	Required	Detail
`X-API-KEY`	Required	Your API key for Namsor's services.

Response:
Name	Type	Detail
`timeUnit`	String	Time unit utilizes in the "rowHeaders" field. Can vary based on API use, such as "DAY", "WEEK", or "MONTH".
`periodStart`	Number	Reporting period commencement, represented in UNIX time.
`periodEnd`	Number	Reporting period ending, represented in UNIX format.
`totalUsage`	Number	Cumulative usage for the ongoing period.
`historyTruncated`	Boolean	Indication if the retrieved data has been shortened due to size constraints.
`data`	Array of arrays	Consolidated API usage displayed as an array of data indicators (or nested arrays).
`colHeaders`	Array	Column labels used to link API services with their respective values in each dataset.
`rowHeaders`	Array	Row labels who associated a time span with a specific data set..

Code sample:

Api Usage History Aggregate code sample for javascript:

const response = await fetch("https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsageHistoryAggregate", {
"method": "GET",
"headers": {
  "X-API-KEY": "your-api-key",
  "Accept": "application/json"
}
});

if (response.ok) {
const data = await response.json(); // Extract JSON data from response
console.log(data); // View data in the console
} else {
console.error("The request failed with status:", response.status, response);
}

The above command produces a JSON structure as follows:

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

Api Usage History Aggregate code sample for python:

import requests

url = "https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsageHistoryAggregate"

headers = {
"X-API-KEY": "your-api-key",
"Accept": "application/json"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

The above command produces a JSON structure as follows:

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

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 produces a JSON structure as follows:

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

Api Usage History Aggregate code sample for java:

HttpResponse<String> response = Unirest.get("https://v2.namsor.com/NamSorAPIv2/api2/json/apiUsageHistoryAggregate")
.header("X-API-KEY", "your-api-key")
.header("Accept", "application/json")
.asString();

The above command produces a JSON structure as follows:

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