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. The API can determine the likely gender, ethnicity and country of origin of an individual with a particular name.
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 the 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","A2773")
gender_batch.addItem("Gon","Freecs", "M9835")
gender_batch.addItem("Jonathan","Joestar", "M6104")
# Use classify function with required API Key argument and receive responses in the form of a list.
response_list = gender_batch.classify("Insert API key")
print(response_list[2].likely_gender)
# Refer to the Batches section to look at the different types of batches and view the type of responses that will be returned when a batch is classified.
Use the export_to_excel
function to create a file with the required file name to represent the batch's data in spreadsheet form.
gender_batch.export_to_excel("File Name.xlsx")
Result:
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 aid with classification.
- 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(first_name: str, last_name: str, country_code: CountryCodes) Infer the likely ethnicity/diaspora of a personal name, given a country of residence ISO2 code
first_name: The desired first name.
last_name: The desired last name.
country_code: The country code to aid with classification.
- 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: 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: The full name to be parsed.
country_code: The country code to aid with classification.
- 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. Assumes names 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
- GenderFullResponse
ID
name
likely_gender
gender_scale
score
- 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
-->classify
function returnsGenderResponse
listGenderGeoBatch
-->classify
function returnsGenderResponse
listParsedGenderBatch
-->classify
function returnsGenderResponse
listParsedGenderGeoBatch
-->classify
function returnsGenderResponse
listGenderFullBatch
-->classify
function returnsGenderFullResponse
listGenderFullGeoBatch
-->classify
function returnsGenderFullResponse
listOriginBatch
-->classify
function returnsOriginResponse
listCountryBatch
-->classify
function returnsCountryResponse
listUS_RaceEthnicityBatch
-->classify
function returnsRaceEthnicityResponse
listUS_ZipRaceEthnicityBatch
-->classify
function returnsRaceEthnicityResponse
listDiasporaBatch
-->classify
function returnsDiasporaResponse
listParseNameBatch
-->classify
function returnsParsedNameResponse
listParseNameGeoBatch
-->classify
function returnsParsedNameResponse
list
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.
Contributing
To contribute to this repository, fork it and make changes. To run tests, cd into namsorclient and
run python -m pytest
. If all tests pass, sumbit a pull request. Note that the faker and xlrd modules are required for testing.
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.