A Wrapper for the Namsor Classification API
Project description
Overview
namsor-client is a python package that serves as a wrapper for the Namsor classification API.
Installation
pip install namsor-client
Usage
from namsorclient import NamsorClient
from namsorclient.country_codes import CountryCodes
from namsorclient.request_objects import *
# Create an instance of NamsorClient and pass in your API key as an argument
client = NamsorClient("Insert API key")
# Access the gender (GET) endpoint with function that returns a response of type GenderResponse
response = client.gender("Lelouch","Lamperouge")
# Access the different parts of the response for this particular endpoint
print(response.ID)
print(response.first_name)
print(response.last_name)
print(response.likely_gender)
print(response.gender_scale)
print(response.score)
print(response.probability_calibrated)
# Refer to Responses section to view all different variables of each different Response
# Access the genderBatch (POST) endpoint
gender_batch = GenderBatch()
# Add items, with required arguments, to the batch you want
gender_batch.addItem("Lelouch","Lamperouge","A2140")
gender_batch.addItem("Gon","Freecs", "M0245")
gender_batch.addItem("Jonathan","Joestar", "M0014")
response_list = client.batch(gender_batch)
print(response_list[2].likely_gender)
API
-
gender(first_name: str, last_name: str) Infer the likely gender of a name.
first_name: The desired first name.
last_name: The desired last name.
Returns: GenderResponse
-
genderGeo(first_name: str, last_name: str, country_code: CountryCodes) Infer the likely gender of a name, given a local context (ISO2country code).
first_name: The desired first name.
last_name: The desired last name.
country_code: The country code, to be passed using the CountryCodes object.
Returns: GenderResponse
-
genderFullGeo(full_name: str, country_code: CountryCodes) Infer the likely gender of a full name, given a local context (ISO2 country code).
full_name: The name to be classified.
country_code: The country code to aid with classification.
Returns: GenderResponse
-
genderFull(full_name: str) Infer the likely gender of a full name, ex. John H. Smith
full_name: The name to be classified.
Returns: GenderResponse
-
usRaceEthnicity(first_name: str, last_name: str) Infer a US resident's likely race/ethnicity according to US Census taxonomy W_N(white, non latino), HL (hispano latino), A (asian, non latino), B_NL (black, non latino).
first_name: The desired first name.
last_name: The desired last name.
Returns: OriginResponse
-
usRaceEthnicityZIP5(first_name: str, last_name: str, zip5_code: str) Infer a US resident's likely race/ethnicity according to US Census taxonomy, usingZIP5code info. Output is W_NL (white, non latino), HL (hispano latino), A (asian,non latino, B_NL (black, non latino).
first_name: The desired first name
last_name: The desired last name
zip5_code: The zip code to aid with classification
Returns: OriginResponse
-
diaspora(country_code: CountryCodes, first_name: str, last_name: str) Infer the likely ethnicity/diaspora of a personal name, given a country of residence ISO2 code
first_name (str): The desired first name.
last_name (str): The desired last name.
coutry_code (CountryCodes): The country code to aid with parsing.
Returns: DiasporaResponse
-
parseName(full_name: str) Infer the likely first/last name structure of a name, ex. John Smith or SMITH, John or SMITH; John, given an ISO2 country of residence.
full_name (str): The full name to be parsed.
Returns: ParseNameResponse
-
parseNameGeo(full_name: str, country_code: CountryCodes) Infer the likely first/last name structure of a name, ex. John Smith or SMITH, John or SMITH; John, given an ISO2 country of residence.
full_name (str): The full name to be parsed.
coutry_code (CountryCodes): The country code to aid with parsing.
Returns: ParseNameResponse
-
origin(first_name: str, last_name: str) Infer the likely country of origin of a personal name. Assumes names as they are in the country of origin. For US, CA, AU, NZ and other melting-pots : use 'diaspora' instead.
first_name : The desired first name.
last_name : The desired last name.
Returns: OriginResponse
-
country(full_name: str) Infer the likely country of residence of a personal full name, or one surname. Assumesnames as they are in the country of residence OR the country of origin.
full_name : The name whose country of residence should be determined.
Returns: OriginResponse
Responses
- GenderResponse
ID
first_name
last_name
likely_gender
gender_scale
score
probability_calibrated
- OriginResponse
ID
first_name
last_name
likely_gender
score
country_origin
country_origin_alt
region_origin
top_region_origin
sub_region_origin
- CountryResponse
ID
name
score
country
country_alt
region
top_region
sub_region
- RaceEthnicityResponse
ID
first_name
last_name
race_ethnicity
race_ethnicity_alt
score
- DiasporaResponse
ID
first_name
last_name
score
ethnicity
ethnicity_alt
lifted
country
- ParseNameResponse
ID
name
name_parser_type
name_parser_type_alt
first_last_name
score
Batches
The wrapper also exposes batch functions for each of the different classifications. These are to be used when multiple items need to be classified together.
GenderBatch
returns GenderResponseGenderGeoBatch
returns GenderResponseParsedGenderBatch
returns GenderResponseParsedGenderGeoBatch
returns GenderResponseGenderFullBatch
returns GenderResponseGenderFullGeoBatch
returns GenderResponseOriginBatch
returns OriginResponseCountryBatch
returns CountryBatchUS_RaceEthnicityBatch
returns RaceEthnicityBatchUS_ZipRaceEthnicityBatch
returns RaceEthnicityBatchDiasporaBatch
returns DiasporaResponseParseNameBatch
returns ParsedNameResponseParseNameGeoBatch
returns ParsedNameResponse
Country Codes
Whenever a country code needs to be passed to any function, the CountryCodes class should be used. It exposes an enum with all recognized country codes of the world marked by the respective country's name.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.