API version: 2.0.21

API key:

API documentation

Introduction

Gender from names

Genderize Name
Gender from first name , last name (optional).
Genderize Name Geo
Gender from first name , last name (optional), country code .
Genderize Full Name
Gender from full name .
Genderize Full Name Geo
Gender from full name , country code .

Origin from names

Name Origin
Origin from first name (optional), last name (optional).
Full Name Origin
Origin from full name .

Diaspora from names

Name Diaspora
Diaspora from first name (optional), last name , country code (optional).
Full Name Diaspora
Diaspora from full name , country code .

Country of residence from names

Name Country
Country of residence from first name (optional), last name (optional).
Full Name Country
Country of residence from full name .
Names Corridor
Interaction from first name , last name , country code , first name , last name , country code .

US race ethnicity from names

Name US Race
US race from first name (optional), last name (optional), country code (optional).
Full Name US Race
US race from full name , country code (optional).
Name US Race ZIP
US race from first name (optional), last name (optional), country code (optional), 5 digit zip code .

Indian names

Caste Indian Name
Caste group from first name (optional), last name (optional), state .
Caste Indian Full Name
Caste group from full name , state .
Religion Indian Name
Religion from first name (optional), last name (optional), state .
Religion Indian Full Name
Religion from full name , state .
Subclassification Indian Name
Indian State or Union territory from first name (optional), last name (optional).
Subclassification Indian Full Name
Indian State or Union territory from full name .

Split full names

Split Name
Split name from full name .
Split Name Geo
Split name from full name , country code .

Name type recognition

Name Type
Name type from proper noun .
Name Type Geo
Name type from proper noun , country code .

Phone number format

Format Phone Number
Phone prefix from first name (optional), last name (optional), phone number .
Format Phone Number Geo
Phone prefix from first name (optional), last name (optional), phone number , country code .

Admin

Admin API – Manage your account and API keys

Namsor's Admin API allows you to manage your account and API keys.

Api Status

GET

Cost: 1 credit per name.
Description: Returns the current version of the Namsor software and the status of the classifiers (API services).
More about: Api Status

HTTP request

GET

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

Request header
Property	Required	Description
`X-API-KEY`	Required	Your Namsor's services API key

To get an API key for free, please create an account.

Response
Name	Type	Description
`softwareVersion`	Object	Software version information.
`softwareNameAndVersion`	String	Name and version of the API.
`softwareVersion`	Array	Software version, as an array (major, minor and patch).
`classifierName`	String	Name of the classifier / service.
`serving`	Boolean	True if the classifier is serving requests (has reached minimal learning, is not shutting down).
`learning`	Boolean	True if the classifier is learning.
`shuttingDown`	Boolean	True if the classifier is shutting down.
`probabilityCalibrated`	Boolean	True if the classifier has finished the initial learning and has calibrated probabilities (during initial learning, calibrated probabilities will be equal to -1).

Code sample:

Api Status code sample for shell:

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

The above command returns JSON structured like this:

{
    "softwareVersion": {
        "softwareNameAndVersion": "NamSorAPIv2.0.14B01",
        "softwareVersion": [
            2,
            0,
            14
        ]
    },
    "classifiers": [
        {
            "classifierName": "name_category",
            "serving": true,
            "learning": true,
            "shuttingDown": false,
            "probabilityCalibrated": false
        },
        {
            "classifierName": "personalname_gender",
            "serving": true,
            "learning": true,
            "shuttingDown": false,
            "probabilityCalibrated": true
        }
    ]
}

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 returns JSON structured like this:

{
    "softwareVersion": {
        "softwareNameAndVersion": "NamSorAPIv2.0.14B01",
        "softwareVersion": [
            2,
            0,
            14
        ]
    },
    "classifiers": [
        {
            "classifierName": "name_category",
            "serving": true,
            "learning": true,
            "shuttingDown": false,
            "probabilityCalibrated": false
        },
        {
            "classifierName": "personalname_gender",
            "serving": true,
            "learning": true,
            "shuttingDown": false,
            "probabilityCalibrated": true
        }
    ]
}

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 returns JSON structured like this:

{
    "softwareVersion": {
        "softwareNameAndVersion": "NamSorAPIv2.0.14B01",
        "softwareVersion": [
            2,
            0,
            14
        ]
    },
    "classifiers": [
        {
            "classifierName": "name_category",
            "serving": true,
            "learning": true,
            "shuttingDown": false,
            "probabilityCalibrated": false
        },
        {
            "classifierName": "personalname_gender",
            "serving": true,
            "learning": true,
            "shuttingDown": false,
            "probabilityCalibrated": true
        }
    ]
}

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 returns JSON structured like this:

{
    "softwareVersion": {
        "softwareNameAndVersion": "NamSorAPIv2.0.14B01",
        "softwareVersion": [
            2,
            0,
            14
        ]
    },
    "classifiers": [
        {
            "classifierName": "name_category",
            "serving": true,
            "learning": true,
            "shuttingDown": false,
            "probabilityCalibrated": false
        },
        {
            "classifierName": "personalname_gender",
            "serving": true,
            "learning": true,
            "shuttingDown": false,
            "probabilityCalibrated": true
        }
    ]
}

Api Usage

GET

Cost: 1 credit per name.
Description: Returns information on your subscription plan, billing period and current API usage.
More about: Api Usage

HTTP request

GET

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

Request header
Property	Required	Description
`X-API-KEY`	Required	Your Namsor's services API key

To get an API key for free, please create an account.

Response
Name	Type	Description
`subscription`	Object	Subscription information.
`apiKey`	String	Your Namsor API key.
`planStarted`	Number	Start date of the plan, in UNIX time format.
`priorPlanStarted`	Number	Datetime when the user subscribed to the prior plan.
`planEnded`	Number	End date of the plan, in UNIX time format.
`taxRate`	Number	Applicable tax rate for the plan.
`planName`	String	Name of the plan.
`planBaseFeesKey`	String	Current plan key (as in Stripe product).
`planStatus`	String	Plan status.
`planQuota`	Number	Total number of credits associated with this plan.
`priceUSD`	Number	Price in US dollars ($).
`priceOverageUSD`	Number	Overage price in US dollars ($).
`price`	Number	Price in the user's preferred currency.
`priceOverage`	Number	Overaged price in the user's preferred currency.
`currency`	String	The user's preferred currency.
`currencyFactor`	Number	For USD, GBP, EUR - the factor is 1.
`stripeCustomerId`	String	Unique Stripe Customer identifier.
`stripeStatus`	String	Stripe status.
`stripeSubscription`	String	Stripe subscription identifier.
`userId`	String	Unique user identifier.
`billingPeriod`	Object	Billing information.
`apiKey`	String	Your Namsor API key.
`subscriptionStarted`	Number	Subscription start date, in UNIX time format.
`periodStarted`	Number	Subscription period start date, in UNIX time format.
`periodEnded`	Number	Subscription end date, in UNIX time format.
`stripeCurrentPeriodEnd`	Number	End of the current plan in Stripe.
`stripeCurrentPeriodStart`	Number	Start of the current plan in Stripe.
`billingStatus`	String	Status of the current period billing.
`usage`	Number	Number of credits used so far.
`softLimit`	Number	Current soft limit for the period.
`hardLimit`	Number	Current hard limit for the period.
`overageExclTax`	Number	Overage amount excluding tax.
`overageInclTax`	Number	Overage amount including tax (if applicable).
`overageCurrency`	String	Currency of the overage amount.
`overageQuantity`	Number	Quantity above monthly quota of the current subscritpion, in credits.

Code sample:

Api Usage code sample for shell:

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

The above command returns JSON structured like this:

{
    "subscription": {
        "apiKey": "v7menlws2yo8r2mnm10f3uai53tmblth",
        "planStarted": 1602705605199,
        "priorPlanStarted": 0,
        "planEnded": 0,
        "taxRate": 0,
        "planName": "BASIC",
        "planBaseFeesKey": "namsorapi_v2_BASIC_usd",
        "planStatus": "OPEN",
        "planQuota": 5000,
        "priceUSD": 0,
        "priceOverageUSD": 0.005,
        "price": 0,
        "priceOverage": 0.005,
        "currency": "usd",
        "currencyFactor": 1,
        "stripeCustomerId": null,
        "stripeStatus": null,
        "stripeSubscription": null,
        "userId": "GYUAUzTKPusJ3aqUH5gQte0dOQCr"
    },
    "billingPeriod": {
        "apiKey": "v7menlws2yo8r2mnm10f3uai53tmblth",
        "subscriptionStarted": 1602705635199,
        "periodStarted": 1618430435199,
        "periodEnded": 0,
        "stripeCurrentPeriodEnd": 0,
        "stripeCurrentPeriodStart": 0,
        "billingStatus": "OPEN",
        "usage": 34,
        "softLimit": 3000,
        "hardLimit": 5000
    },
    "overageExclTax": 0,
    "overageInclTax": 0,
    "overageCurrency": null,
    "overageQuantity": 0
}

Api Usage 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 returns JSON structured like this:

{
    "subscription": {
        "apiKey": "v7menlws2yo8r2mnm10f3uai53tmblth",
        "planStarted": 1602705605199,
        "priorPlanStarted": 0,
        "planEnded": 0,
        "taxRate": 0,
        "planName": "BASIC",
        "planBaseFeesKey": "namsorapi_v2_BASIC_usd",
        "planStatus": "OPEN",
        "planQuota": 5000,
        "priceUSD": 0,
        "priceOverageUSD": 0.005,
        "price": 0,
        "priceOverage": 0.005,
        "currency": "usd",
        "currencyFactor": 1,
        "stripeCustomerId": null,
        "stripeStatus": null,
        "stripeSubscription": null,
        "userId": "GYUAUzTKPusJ3aqUH5gQte0dOQCr"
    },
    "billingPeriod": {
        "apiKey": "v7menlws2yo8r2mnm10f3uai53tmblth",
        "subscriptionStarted": 1602705635199,
        "periodStarted": 1618430435199,
        "periodEnded": 0,
        "stripeCurrentPeriodEnd": 0,
        "stripeCurrentPeriodStart": 0,
        "billingStatus": "OPEN",
        "usage": 34,
        "softLimit": 3000,
        "hardLimit": 5000
    },
    "overageExclTax": 0,
    "overageInclTax": 0,
    "overageCurrency": null,
    "overageQuantity": 0
}

Api Usage 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 returns JSON structured like this:

{
    "subscription": {
        "apiKey": "v7menlws2yo8r2mnm10f3uai53tmblth",
        "planStarted": 1602705605199,
        "priorPlanStarted": 0,
        "planEnded": 0,
        "taxRate": 0,
        "planName": "BASIC",
        "planBaseFeesKey": "namsorapi_v2_BASIC_usd",
        "planStatus": "OPEN",
        "planQuota": 5000,
        "priceUSD": 0,
        "priceOverageUSD": 0.005,
        "price": 0,
        "priceOverage": 0.005,
        "currency": "usd",
        "currencyFactor": 1,
        "stripeCustomerId": null,
        "stripeStatus": null,
        "stripeSubscription": null,
        "userId": "GYUAUzTKPusJ3aqUH5gQte0dOQCr"
    },
    "billingPeriod": {
        "apiKey": "v7menlws2yo8r2mnm10f3uai53tmblth",
        "subscriptionStarted": 1602705635199,
        "periodStarted": 1618430435199,
        "periodEnded": 0,
        "stripeCurrentPeriodEnd": 0,
        "stripeCurrentPeriodStart": 0,
        "billingStatus": "OPEN",
        "usage": 34,
        "softLimit": 3000,
        "hardLimit": 5000
    },
    "overageExclTax": 0,
    "overageInclTax": 0,
    "overageCurrency": null,
    "overageQuantity": 0
}

Api Usage 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 returns JSON structured like this:

{
    "subscription": {
        "apiKey": "v7menlws2yo8r2mnm10f3uai53tmblth",
        "planStarted": 1602705605199,
        "priorPlanStarted": 0,
        "planEnded": 0,
        "taxRate": 0,
        "planName": "BASIC",
        "planBaseFeesKey": "namsorapi_v2_BASIC_usd",
        "planStatus": "OPEN",
        "planQuota": 5000,
        "priceUSD": 0,
        "priceOverageUSD": 0.005,
        "price": 0,
        "priceOverage": 0.005,
        "currency": "usd",
        "currencyFactor": 1,
        "stripeCustomerId": null,
        "stripeStatus": null,
        "stripeSubscription": null,
        "userId": "GYUAUzTKPusJ3aqUH5gQte0dOQCr"
    },
    "billingPeriod": {
        "apiKey": "v7menlws2yo8r2mnm10f3uai53tmblth",
        "subscriptionStarted": 1602705635199,
        "periodStarted": 1618430435199,
        "periodEnded": 0,
        "stripeCurrentPeriodEnd": 0,
        "stripeCurrentPeriodStart": 0,
        "billingStatus": "OPEN",
        "usage": 34,
        "softLimit": 3000,
        "hardLimit": 5000
    },
    "overageExclTax": 0,
    "overageInclTax": 0,
    "overageCurrency": null,
    "overageQuantity": 0
}

Available Services

GET

Cost: 1 credit per name.
Description: Returns a list of the API services (classifiers) and their usage costs in credits.
More about: Available Services

HTTP request

GET

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

Request header
Property	Required	Description
`X-API-KEY`	Required	Your Namsor's services API key

To get an API key for free, please create an account.

Response
Name	Type	Description
`serviceName`	String	Name of the classifier / service.
`serviceGroup`	String	Group the classifier / service belong to.
`costInUnits`	Number	Usage cost of the service, in credits.

Code sample:

Available Services code sample for shell:

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

The above command returns JSON structured like this:

{
    "serviceName": "name_category",
    "serviceGroup": "general",
    "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 returns JSON structured like this:

{
    "serviceName": "name_category",
    "serviceGroup": "general",
    "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 returns JSON structured like this:

{
    "serviceName": "name_category",
    "serviceGroup": "general",
    "costInUnits": 1
}

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 returns JSON structured like this:

{
    "serviceName": "name_category",
    "serviceGroup": "general",
    "costInUnits": 1
}

Software Version

GET

Cost: 1 credit per name.
Description: Returns the current version of the Namsor software.
More about: Software Version

HTTP request

GET

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

Request header
Property	Required	Description
`X-API-KEY`	Required	Your Namsor's services API key

To get an API key for free, please create an account.

Response
Name	Type	Description
`softwareNameAndVersion`	String	Name and version of the API.
`softwareVersion`	Array	Software version, as an array (major, minor and patch).

Code sample:

Software Version code sample for shell:

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

The above command returns JSON structured like this:

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

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 returns JSON structured like this:

{
    "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 returns JSON structured like this:

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

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 returns JSON structured like this:

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

Taxonomy Classes

GET

Cost: 1 credit per name.
Description: Returns a list of the possible enumerators for a given classifier.
More about: Taxonomy Classes

HTTP request

GET

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

Request header
Property	Required	Description
`X-API-KEY`	Required	Your Namsor's services API key

To get an API key for free, please create an account.

Request parameters
Name	Type	Required	Description
`classifierName`	String	Required	Name of the classifier.

Response
Name	Type	Description
`classifierName`	String	Name of the submitted classifier.
`taxonomyClasses`	Array	Possible enumerators for this classifier.

Code sample:

Taxonomy Classes code sample for shell:

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

The above command returns JSON structured like this:

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

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 returns JSON structured like this:

{
    "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 returns JSON structured like this:

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

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 returns JSON structured like this:

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