Package: namsor-client
Overviewnamsor-clientis 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.Installationpip install namsor-clientUsagefromnamsorclientimportNamsorClientfromnamsorclient.country_codesimportCountryCodesfromnamsorclient.request_objectsimport*# 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) endpointgender_batch=GenderBatch()# Add items, with required arguments, to the batch you wantgender_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 theexport_to_excelfunction 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:APIgender(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:GenderResponsegenderGeo(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:GenderResponsegenderFullGeo(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:GenderResponsegenderFull(full_name: str)Infer the likely gender of a full name, ex. John H. Smithfull_name: The name to be classified.Returns:GenderResponseusRaceEthnicity(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:OriginResponseusRaceEthnicityZIP5(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 namelast_name: The desired last namezip5_code: The zip code to aid with classificationReturns:OriginResponsediaspora(first_name: str, last_name: str, country_code: CountryCodes)Infer the likely ethnicity/diaspora of a personal name, given a country of residence ISO2 codefirst_name: The desired first name.last_name: The desired last name.country_code: The country code to aid with classification.Returns:DiasporaResponseparseName(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:ParseNameResponseparseNameGeo(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:ParseNameResponseorigin(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:OriginResponsecountry(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:OriginResponseResponsesGenderResponseIDfirst_namelast_namelikely_gendergender_scalescoreprobability_calibratedGenderFullResponseIDnamelikely_gendergender_scalescoreOriginResponseIDfirst_namelast_namelikely_genderscorecountry_origincountry_origin_altregion_origintop_region_originsub_region_originCountryResponseIDnamescorecountrycountry_altregiontop_regionsub_regionRaceEthnicityResponseIDfirst_namelast_namerace_ethnicityrace_ethnicity_altscoreDiasporaResponseIDfirst_namelast_namescoreethnicityethnicity_altliftedcountryParseNameResponseIDnamename_parser_typename_parser_type_altfirst_last_namescoreBatchesThe 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-->classifyfunction returnsGenderResponselistGenderGeoBatch-->classifyfunction returnsGenderResponselistParsedGenderBatch-->classifyfunction returnsGenderResponselistParsedGenderGeoBatch-->classifyfunction returnsGenderResponselistGenderFullBatch-->classifyfunction returnsGenderFullResponselistGenderFullGeoBatch-->classifyfunction returnsGenderFullResponselistOriginBatch-->classifyfunction returnsOriginResponselistCountryBatch-->classifyfunction returnsCountryResponselistUS_RaceEthnicityBatch-->classifyfunction returnsRaceEthnicityResponselistUS_ZipRaceEthnicityBatch-->classifyfunction returnsRaceEthnicityResponselistDiasporaBatch-->classifyfunction returnsDiasporaResponselistParseNameBatch-->classifyfunction returnsParsedNameResponselistParseNameGeoBatch-->classifyfunction returnsParsedNameResponselistCountry CodesWhenever a country code needs to be passed to any function, theCountryCodesclass should be used. It exposes an enum with all recognized country codes of the world marked by the respective country's name.ContributingTo contribute to this repository, fork it and make changes. To run tests, cd into namsorclient and
runpython -m pytest. If all tests pass, sumbit a pull request. Note that the faker and xlrd modules are required for testing.