### Install NameAPI Client from GitHub

Source: https://github.com/optimaize/nameapi-client-python/blob/main/README.md

Commands to clone the repository and install dependencies from source.

```bash
python -m venv myenv
myenv\Scripts\activate
git clone https://github.com/optimaize/nameapi-client-python.git
cd nameapi-client-python
pip install -r requirements.txt
```

--------------------------------

### Install NameAPI Client via PyPI

Source: https://github.com/optimaize/nameapi-client-python/blob/main/README.md

Use pip to install the library from the Python Package Index.

```bash
pip install nameapi-client-python
```

--------------------------------

### Initialize NameApiClient

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Initialize the client with an API key and verify the connection using the ping method.

```python
from nameapi_client.client import NameApiClient

# Initialize client with your API key from nameapi.org
api_key = "your-api-key-here"
client = NameApiClient(api_key)

# Test connection with ping
response = client.ping()
print(response)  # Output: "pong"
```

--------------------------------

### Create a Simple Input Person

Source: https://github.com/optimaize/nameapi-client-python/blob/main/README.md

Construct a basic person object using the builder pattern.

```python
name_object = WesternInputPersonNameBuilder().fullname("John F. Kennedy").build()
input_person = NaturalInputPersonBuilder().name(name_object).build()
```

--------------------------------

### Create Person Input Objects

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Construct natural and legal person objects using builder patterns for various naming conventions and attributes.

```python
from nameapi_client.ontology.input_person import NaturalInputPersonBuilder, LegalInputPersonBuilder
from nameapi_client.ontology.name import (
    WesternInputPersonNameBuilder,
    AmericanInputPersonNameBuilder,
    LegalInputPersonNameBuilder,
    InputPersonName,
    NameField,
    CommonNameFieldType
)
from nameapi_client.ontology.gender import StoragePersonGender
from nameapi_client.ontology.age import BirthDate, AgeInfoFactory

# Simple person with full name
name = WesternInputPersonNameBuilder().fullname("John F. Kennedy").build()
person = NaturalInputPersonBuilder().name(name).build()

# Person with separate given name and surname
name = WesternInputPersonNameBuilder() \
    .given_name("Petra") \
    .surname("Muller") \
    .build()
person = NaturalInputPersonBuilder().name(name).build()

# American-style name with prefix, middle name, and suffix
name = AmericanInputPersonNameBuilder() \
    .prefix("Dr.") \
    .given_name("Peter") \
    .middle_name("T.") \
    .surname("Johnson") \
    .suffix("jr") \
    .build()
person = NaturalInputPersonBuilder().name(name).build()

# Using raw NameField objects for custom field types
name = InputPersonName([
    NameField("Petra", CommonNameFieldType.GIVENNAME),
    NameField("Muller", CommonNameFieldType.SURNAME)
])
person = NaturalInputPersonBuilder().name(name).build()

# Complex person with additional attributes
person = NaturalInputPersonBuilder() \
    .name(WesternInputPersonNameBuilder().given_name("John").surname("Doe").build()) \
    .gender(StoragePersonGender.MALE) \
    .age(BirthDate(year=1985, month=6, day=15)) \
    .add_email("john.doe@example.com") \
    .add_tel_number("+1-555-123-4567") \
    .add_nationality("US") \
    .add_native_languages("en") \
    .correspondence_language("en") \
    .build()

# Legal person (company/organization)
legal_name = LegalInputPersonNameBuilder().name("Google").legal_form("Inc.").build()
company = LegalInputPersonBuilder().name(legal_name).build()

# Alternative: full company name
legal_name = LegalInputPersonNameBuilder().name("Google Inc.").build()
company = LegalInputPersonBuilder().name(legal_name).build()
```

--------------------------------

### Create Name Objects

Source: https://github.com/optimaize/nameapi-client-python/blob/main/README.md

Various ways to construct name objects using builders or field lists.

```python
name_object_1 = WesternInputPersonNameBuilder() \
    .fullname("Petra Müller") \
    .build()

name_object_2 = WesternInputPersonNameBuilder() \
    .given_name("Petra") \
    .surname("Müller") \
    .build()

name_object_3 = WesternInputPersonNameBuilder() \
    .name_field(NameField("Petra", CommonNameFieldType.GIVENNAME)) \
    .name_field(NameField("Müller", CommonNameFieldType.SURNAME)) \
    .build()

name_object_4 = InputPersonName([NameField("petra müller", CommonNameFieldType.FULLNAME)])
```

--------------------------------

### Build Structured Address Objects

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Import necessary builders to create structured address objects for person records.

```python
from nameapi_client.ontology.address import (
    StructuredAddressBuilder,
    StructuredPlaceInfoBuilder,
    StructuredStreetInfoBuilder
)
from nameapi_client.ontology.input_person import NaturalInputPersonBuilder
from nameapi_client.ontology.name import WesternInputPersonNameBuilder
```

--------------------------------

### Build Structured Addresses

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Constructs address objects using builders for place and street information. Supports both full address details and minimal place-only configurations.

```python
# Build a complete address
address = StructuredAddressBuilder() \
    .place_info(
        StructuredPlaceInfoBuilder()
            .postal_code("90210")
            .locality("Beverly Hills")
            .country("US")
            .build()
    ) \
    .street_info(
        StructuredStreetInfoBuilder()
            .street_name("Hill Road")
            .house_number("512")
            .build()
    ) \
    .build()

# Add address to a person
person = NaturalInputPersonBuilder() \
    .name(WesternInputPersonNameBuilder().given_name("John").surname("Doe").build()) \
    .add_address_for_all(address) \
    .build()

# Minimal address with just place info
address = StructuredAddressBuilder() \
    .place_info(
        StructuredPlaceInfoBuilder()
            .locality("Zurich")
            .country("CH")
            .build()
    ) \
    .build()
```

--------------------------------

### Send a Ping Request

Source: https://github.com/optimaize/nameapi-client-python/blob/main/README.md

Test the connection to the NameAPI service.

```python
client = NameApiClient(None)
response = client.ping() # return the string 'pong'
```

--------------------------------

### Define Age and Birth Date Information

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Creates age information objects using the AgeInfoFactory or direct BirthDate instantiation. These objects are used to improve parsing accuracy and enable risk detection.

```python
from nameapi_client.ontology.age import BirthDate, BirthYear, BirthYearMonth, AgeInfoFactory
from nameapi_client.ontology.input_person import NaturalInputPersonBuilder
from nameapi_client.ontology.name import WesternInputPersonNameBuilder
from datetime import datetime

# Full birth date
birth_date = BirthDate(year=1985, month=6, day=15)

# Using AgeInfoFactory for various formats
full_date = AgeInfoFactory.for_date(1985, 6, 15)
year_month = AgeInfoFactory.for_year_and_month(1985, 6)
year_only = AgeInfoFactory.for_year(1985)
year_range = AgeInfoFactory.for_year_range(1980, 1989)

# From datetime object
birth_date = BirthDate.from_date(datetime(1985, 6, 15))

# From age range (computes year range automatically)
age_info = AgeInfoFactory.for_age_range(25, 35)  # Person between 25 and 35 years old
age_info = AgeInfoFactory.for_minimal_age(18)    # Person at least 18 years old
age_info = AgeInfoFactory.for_maximal_age(65)    # Person at most 65 years old

# Add to person
person = NaturalInputPersonBuilder() \
    .name(WesternInputPersonNameBuilder().fullname("John Doe").build()) \
    .age(BirthDate(year=1985, month=6, day=15)) \
    .build()
```

--------------------------------

### Format Names

Source: https://github.com/optimaize/nameapi-client-python/blob/main/README.md

Display personal names in a specific format or casing.

```python
api_key = None  # Set your api_key here
client = NameApiClient(api_key)
response = client.person_name_formatter(input_person)
```

--------------------------------

### Create Complex Input Person

Source: https://github.com/optimaize/nameapi-client-python/blob/main/README.md

Construct a person object with additional metadata like gender, email, phone, and age.

```python
input_person = NaturalInputPersonBuilder() \
            .name(name_object_1) \
            .gender(StoragePersonGender.MALE) \
            .add_email("email@example.com") \
            .add_tel_number("+5555555") \
            .age(BirthDate(year=1999, month=2, day=1))\
            .build()
```

--------------------------------

### Compare Person Names with Transliteration Differences

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Compares two person names that differ only in transliteration (e.g., 'Muller' vs 'Mueller'). The client treats these as equivalent.

```python
person1 = NaturalInputPersonBuilder() \
    .name(WesternInputPersonNameBuilder().fullname("Petra Muller").build()) \
    .build()
person2 = NaturalInputPersonBuilder() \
    .name(WesternInputPersonNameBuilder().fullname("Petra Mueller").build()) \
    .build()

result = client.person_matcher(person1, person2)
print(f"Match Type: {result.match_type}")  # PersonMatchType.EQUAL (treated as equivalent)
```

--------------------------------

### Parse Email Names

Source: https://github.com/optimaize/nameapi-client-python/blob/main/README.md

Extract names from email address strings.

```python
api_key = None  # Set your api_key here
client = NameApiClient(api_key)
email_address="daniela.meyer@example.de"
response = client.email_name_parser(email_address)
```

--------------------------------

### Compare Person Names with Variations

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Compares two person names with significant variations, including middle initials and compound surnames. The client identifies these as matching.

```python
person1 = NaturalInputPersonBuilder() \
    .name(WesternInputPersonNameBuilder().fullname("Petra K. Muller").build()) \
    .build()
person2 = NaturalInputPersonBuilder() \
    .name(WesternInputPersonNameBuilder().fullname("Petra Mueller-Meyer").build()) \
    .build()

result = client.person_matcher(person1, person2)
print(f"Match Type: {result.match_type}")  # PersonMatchType.MATCHING
```

--------------------------------

### Parse Person Name Components

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Extracts and prints various components of a parsed person's name, including given name, surname, and gender. Requires a pre-matched person object.

```python
parsed_person = best_match.parsed_person
output_name = parsed_person.output_person_name

given_name = output_name.get_first(TermType.GIVENNAME).string  # "Petra"
surname = output_name.get_first(TermType.SURNAME).string       # "Muller"
gender = parsed_person.gender_info.gender                       # ComputedPersonGender.FEMALE

print(f"Given Name: {given_name}")
print(f"Surname: {surname}")
print(f"Gender: {gender}")
print(f"Confidence: {best_match.confidence}")
print(f"Likeliness: {best_match.likeliness}")
```

--------------------------------

### Parse Legal Person Name

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Parses a legal person name (company name) and extracts business name and legal form. Uses `LegalInputPersonNameBuilder` and `LegalInputPersonBuilder`.

```python
legal_name = LegalInputPersonNameBuilder().name("Google Inc.").build()
company = LegalInputPersonBuilder().name(legal_name).build()

result = client.person_name_parser(company)
output_name = result.get_best_match().parsed_person.output_person_name

print(f"Business Name: {output_name.get_first(TermType.BUSINESSNAME).string}")       # "Google"
print(f"Legal Form: {output_name.get_first(TermType.BUSINESSLEGALFORM).string}")     # "Inc."
```

--------------------------------

### Check for Parser Disputes

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Parses a name and checks for any parser disputes, such as gender mismatches. Requires a `NaturalInputPersonBuilder` with a specified gender.

```python
name = WesternInputPersonNameBuilder().fullname("Petra Muller").build()
person = NaturalInputPersonBuilder().name(name).build()

result = client.person_name_parser(person)
disputes = result.get_best_match().parser_disputes
for dispute in disputes:
    print(f"Dispute: {dispute.dispute_type} - {dispute.message}")
# Output: Dispute: DisputeType.GENDER - Gender mismatch detected
```

--------------------------------

### Parse Names

Source: https://github.com/optimaize/nameapi-client-python/blob/main/README.md

Split a full name into its constituent parts.

```python
api_key = None  # Set your api_key here
client = NameApiClient(api_key)
response = client.person_name_parser(input_person)
```

--------------------------------

### Compare Identical Names

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Compares two identical person records to determine if they are the same person. Returns the match type, points, and confidence score. Initializes `NameApiClient` with an API key.

```python
from nameapi_client.client import NameApiClient
from nameapi_client.ontology.input_person import NaturalInputPersonBuilder
from nameapi_client.ontology.name import WesternInputPersonNameBuilder
from nameapi_client.services.person_matcher import PersonMatchType

client = NameApiClient("your-api-key")

# Compare two identical names
person1 = NaturalInputPersonBuilder() \
    .name(WesternInputPersonNameBuilder().fullname("Petra Muller").build()) \
    .build()
person2 = NaturalInputPersonBuilder() \
    .name(WesternInputPersonNameBuilder().fullname("Petra Muller").build()) \
    .build()

result = client.person_matcher(person1, person2)

print(f"Match Type: {result.match_type}")      # PersonMatchType.EQUAL
print(f"Points: {result.points}")              # Score indicating match strength
print(f"Confidence: {result.confidence}")      # Confidence in the result
```

--------------------------------

### Format Lowercase Name to Proper Case

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Formats a lowercase full name into proper case using the Name API client. This is useful for standardizing name display.

```python
from nameapi_client.client import NameApiClient
from nameapi_client.ontology.input_person import NaturalInputPersonBuilder
from nameapi_client.ontology.name import InputPersonName, NameField, CommonNameFieldType

client = NameApiClient("your-api-key")

# Format a lowercase name to proper case
name = InputPersonName([NameField("petra muller", CommonNameFieldType.FULLNAME)])
person = NaturalInputPersonBuilder().name(name).build()

result = client.person_name_formatter(person)

print(f"Formatted: {result.formatted}")  # "Petra Muller"
print(f"Is Unknown: {result.is_unknown}")  # False if formatting succeeded
```

--------------------------------

### Format All-Caps Name to Proper Case

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Formats an all-caps full name into proper case. This demonstrates the client's ability to handle different input casing conventions.

```python
# Format all-caps name
name = InputPersonName([NameField("JOHN DOE", CommonNameFieldType.FULLNAME)])
person = NaturalInputPersonBuilder().name(name).build()

result = client.person_name_formatter(person)
print(f"Formatted: {result.formatted}")  # "John Doe"
```

--------------------------------

### Match Names

Source: https://github.com/optimaize/nameapi-client-python/blob/main/README.md

Compare two person objects to determine if they represent the same individual.

```python
api_key = None  # Set your api_key here
client = NameApiClient(api_key)

name_object_1 = WesternInputPersonNameBuilder().fullname("John F. Kennedy").build()
input_person_1 = NaturalInputPersonBuilder().name(name_object).build()
name_object_2 = WesternInputPersonNameBuilder().fullname("Jack Kennedy").build()
input_person_2 = NaturalInputPersonBuilder().name(name_object).build()

response = client.person_matcher(input_person_1, input_person_2)
```

--------------------------------

### Parse Natural Person Names

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Use the name parser to decompose a full name into components and identify person attributes.

```python
from nameapi_client.client import NameApiClient
from nameapi_client.ontology.input_person import NaturalInputPersonBuilder, LegalInputPersonBuilder
from nameapi_client.ontology.name import (
    WesternInputPersonNameBuilder,
    AmericanInputPersonNameBuilder,
    LegalInputPersonNameBuilder,
    TermType
)

client = NameApiClient("your-api-key")

# Parse a natural person name
name = WesternInputPersonNameBuilder().fullname("Petra Muller").build()
person = NaturalInputPersonBuilder().name(name).build()

result = client.person_name_parser(person)
best_match = result.get_best_match()
```

--------------------------------

### Detect Input Risks

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Use the risk detector to identify disguised or invalid input in person records. Supports various risk types like RANDOM_TYPING, PADDING, and SPACED_TYPING.

```python
name = WesternInputPersonNameBuilder().fullname("P e t e r M e y e r").build()
person = NaturalInputPersonBuilder().name(name).build()

result = client.risk_detector(person)
print(f"Risk Type: {result.get_worst_risk().risk_type}")  # FakeRiskType.INVALID

# Check all detected risks
for risk in result.risks:
    print(f"{risk.data_item}: {risk.risk_type} (score: {risk.risk_score}) - {risk.reason}")

# Validate a legitimate name (no risks expected)
name = WesternInputPersonNameBuilder().fullname("Petra Schmidt").build()
person = NaturalInputPersonBuilder().name(name).build()

result = client.risk_detector(person)
print(f"Has Risk: {result.has_risk()}")  # False

# Detect risks in other data fields (email, address, etc.)
from nameapi_client.ontology.address import StructuredAddressBuilder, StructuredPlaceInfoBuilder

person = NaturalInputPersonBuilder() \
    .name(WesternInputPersonNameBuilder().fullname("Peter Meyer").build()) \
    .add_email("asdf@asdf.de") \
    .build()

result = client.risk_detector(person)
if result.has_risk():
    risk = result.get_worst_risk()
    print(f"Data Item: {risk.data_item}")  # DataItem.EMAIL
    print(f"Risk Type: {risk.risk_type}")  # FakeRiskType.OTHER
```

--------------------------------

### Detect Risk

Source: https://github.com/optimaize/nameapi-client-python/blob/main/README.md

Identify potentially fake or invalid data in person records.

```python
api_key = None  # Set your api_key here
client = NameApiClient(api_key)
response = client.risk_detector(input_person)
```

--------------------------------

### Detect Placeholder Name Risk

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Detects if a person's name is a common placeholder like 'John Doe'. This helps identify potentially fake or test data.

```python
from nameapi_client.client import NameApiClient
from nameapi_client.ontology.input_person import NaturalInputPersonBuilder
from nameapi_client.ontology.name import WesternInputPersonNameBuilder
from nameapi_client.services.risk_detector import DataItem, FakeRiskType, DisguiseRiskType

client = NameApiClient("your-api-key")

# Detect placeholder name
name = WesternInputPersonNameBuilder().fullname("John Doe").build()
person = NaturalInputPersonBuilder().name(name).build()

result = client.risk_detector(person)

if result.has_risk():
    print(f"Overall Score: {result.score}")  # Higher = more risky
    worst_risk = result.get_worst_risk()
    print(f"Data Item: {worst_risk.data_item}")    # DataItem.NAME
    print(f"Risk Type: {worst_risk.risk_type}")    # FakeRiskType.PLACEHOLDER
    print(f"Risk Score: {worst_risk.risk_score}")  # 0-1, higher = worse
    print(f"Reason: {worst_risk.reason}")          # Human-readable explanation
```

--------------------------------

### Detect Famous Person Name Risk

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Detects if a name corresponds to a famous individual, like 'Barak Obama'. This can help distinguish between regular individuals and public figures.

```python
# Detect famous person
name = WesternInputPersonNameBuilder().fullname("Barak Obama").build()
person = NaturalInputPersonBuilder().name(name).build()

result = client.risk_detector(person)
print(f"Risk Type: {result.get_worst_risk().risk_type}")  # FakeRiskType.FAMOUS
```

--------------------------------

### Detect Disposable Email Addresses

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Check if an email address belongs to a known disposable or temporary domain.

```python
from nameapi_client.client import NameApiClient
from nameapi_client.services.email_parser import EmailDisposableResult

client = NameApiClient("your-api-key")

# Check disposable email address
result = client.disposable_email_detector("someone@10minutemail.com")
print(f"Is Disposable: {result}")  # EmailDisposableResult.YES

# Check legitimate email address
result = client.disposable_email_detector("user@gmail.com")
print(f"Is Disposable: {result}")  # EmailDisposableResult.NO

# Check unknown domain
result = client.disposable_email_detector("user@unknowndomain.xyz")
print(f"Is Disposable: {result}")  # EmailDisposableResult.UNKNOWN or NO
```

--------------------------------

### Access Detailed Person Match Results

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Retrieves detailed results from a person matching operation, including scores for name, gender, age, and the overall composition of the match.

```python
# Access detailed match results
print(f"Name Match: {result.person_name_matcher_result.match_type}")
print(f"Gender Match: {result.gender_matcher_result.match_type}")
print(f"Age Match: {result.age_matcher_result.match_type}")
print(f"Composition: {result.person_match_composition}")  # FULL, PARTIAL, or INTERSECTION
```

--------------------------------

### Detect Disposable Email Address

Source: https://github.com/optimaize/nameapi-client-python/blob/main/README.md

Use the `disposable_email_detector` method to check if an email address belongs to a known disposable email provider. Ensure your API key is set.

```python
api_key = None  # Set your api_key here
client = NameApiClient(api_key)
email_address="someone@10minutemail.com"
response = client.disposable_email_detector(email_address)
```

--------------------------------

### Parse American-Style Name

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Parses an American-style full name, including titles and qualifiers, and prints the extracted components. Uses `AmericanInputPersonNameBuilder` and `NaturalInputPersonBuilder`.

```python
name = AmericanInputPersonNameBuilder().fullname("Dr. Peter T. Johnson jr").build()
person = NaturalInputPersonBuilder().name(name).build()

result = client.person_name_parser(person)
output_name = result.get_best_match().parsed_person.output_person_name

print(f"Title: {output_name.get_first(TermType.TITLE).string}")           # "Dr."
print(f"Given Name: {output_name.get_first(TermType.GIVENNAME).string}")  # "Peter"
print(f"Middle Initial: {output_name.get_first(TermType.GIVENNAMEINITIAL).string}")  # "T."
print(f"Surname: {output_name.get_first(TermType.SURNAME).string}")       # "Johnson"
print(f"Qualifier: {output_name.get_first(TermType.QUALIFIER).string}")   # "jr"
```

--------------------------------

### Check Gender Clarity

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Checks the clarity of the determined gender, indicating if it's clear, has some indication, or is unknown. Uses the `is_clear()` and `has_gender_info()` methods of the gender result.

```python
from nameapi_client.client import NameApiClient
from nameapi_client.ontology.input_person import NaturalInputPersonBuilder
from nameapi_client.ontology.name import WesternInputPersonNameBuilder
from nameapi_client.ontology.gender import ComputedPersonGender

client = NameApiClient("your-api-key")

# Check gender clarity
if result.gender.is_clear():
    print("Gender is clearly determined")
elif result.gender.has_gender_info():
    print("Gender has some indication but not definitive")
else:
    print("Gender is unknown")

# Possible gender values:
# ComputedPersonGender.MALE - Clearly male
# ComputedPersonGender.FEMALE - Clearly female
# ComputedPersonGender.NEUTRAL - Gender-neutral name
# ComputedPersonGender.UNKNOWN - Cannot determine
# ComputedPersonGender.INDETERMINABLE - Name doesn't indicate gender
# ComputedPersonGender.CONFLICT - Conflicting gender signals
```

--------------------------------

### Genderize Name

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Determines the gender of a person based on their name and provides confidence scores. Initializes `NameApiClient` with an API key.

```python
from nameapi_client.client import NameApiClient
from nameapi_client.ontology.input_person import NaturalInputPersonBuilder
from nameapi_client.ontology.name import WesternInputPersonNameBuilder
from nameapi_client.ontology.gender import ComputedPersonGender

client = NameApiClient("your-api-key")

# Genderize a name
name = WesternInputPersonNameBuilder().fullname("Petra Muller").build()
person = NaturalInputPersonBuilder().name(name).build()

result = client.person_genderizer(person)

print(f"Gender: {result.gender}")  # ComputedPersonGender.FEMALE
print(f"Is Female: {result.gender.is_female()}")  # True
print(f"Is Male: {result.gender.is_male()}")      # False
```

--------------------------------

### Genderize Names

Source: https://github.com/optimaize/nameapi-client-python/blob/main/README.md

Identify the gender associated with a person's name.

```python
api_key = None  # Set your api_key here
client = NameApiClient(api_key)
response = client.person_genderizer(input_person)
```

--------------------------------

### Detect Humorous Name Risk

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Detects names that are likely humorous or pun-based, like 'Sandy Beach'. This can be useful for filtering out non-serious entries.

```python
# Detect humorous name
name = WesternInputPersonNameBuilder().fullname("Sandy Beach").build()
person = NaturalInputPersonBuilder().name(name).build()

result = client.risk_detector(person)
print(f"Risk Type: {result.get_worst_risk().risk_type}")  # FakeRiskType.HUMOROUS
```

--------------------------------

### Parse Names from Email Addresses

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Extract given names and surnames from email addresses. The parser identifies if the email contains a person's name, initials, or is a functional address.

```python
from nameapi_client.client import NameApiClient
from nameapi_client.services.email_parser import EmailAddressParsingResultType

client = NameApiClient("your-api-key")

# Extract name from email address
result = client.email_name_parser("john.doe@gmail.com")

print(f"Result Type: {result.result_type}")  # EmailAddressParsingResultType.PERSON_NAME

best_match = result.get_best_match()
if best_match:
    print(f"Confidence: {best_match.confidence}")

    # Extract given names
    for gn in best_match.given_names:
        print(f"Given Name: {gn.name} (type: {gn.email_address_name_type})")
    # Output: Given Name: john (type: EmailAddressNameType.NAME)

    # Extract surnames
    for sn in best_match.surnames:
        print(f"Surname: {sn.name} (type: {sn.email_address_name_type})")
    # Output: Surname: doe (type: EmailAddressNameType.NAME)

# Detect functional email (not a person name)
result = client.email_name_parser("webmaster@example.com")
print(f"Result Type: {result.result_type}")  # EmailAddressParsingResultType.FUNCTIONAL

# Detect initials in email
result = client.email_name_parser("j.d@example.com")
print(f"Result Type: {result.result_type}")  # EmailAddressParsingResultType.INITIALS
```

--------------------------------

### Genderize with Separate Name Fields

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Genderizes a name by providing separate given name and surname fields. Uses `WesternInputPersonNameBuilder` to construct the name.

```python
from nameapi_client.client import NameApiClient
from nameapi_client.ontology.input_person import NaturalInputPersonBuilder
from nameapi_client.ontology.name import WesternInputPersonNameBuilder
from nameapi_client.ontology.gender import ComputedPersonGender

client = NameApiClient("your-api-key")

# Genderize with separate name fields
name = WesternInputPersonNameBuilder() \
    .given_name("John") \
    .surname("Doe") \
    .build()
person = NaturalInputPersonBuilder().name(name).build()

result = client.person_genderizer(person)
print(f"Gender: {result.gender}")  # ComputedPersonGender.MALE
```

--------------------------------

### Detect Random Typing Name Risk

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Identifies names that appear to be random typing, such as 'Asdf asdf'. This is a common indicator of invalid or test data.

```python
# Detect random typing
name = WesternInputPersonNameBuilder().fullname("Asdf asdf").build()
person = NaturalInputPersonBuilder().name(name).build()

result = client.risk_detector(person)
print(f"Risk Type: {result.get_worst_risk().risk_type}")  # FakeRiskType.RANDOM_TYPING
```

--------------------------------

### Detect Fictional Character Name Risk

Source: https://context7.com/optimaize/nameapi-client-python/llms.txt

Identifies if a name belongs to a known fictional character, such as 'Mickey Mouse'. This is useful for data validation.

```python
# Detect fictional character
name = WesternInputPersonNameBuilder().fullname("Mickey Mouse").build()
person = NaturalInputPersonBuilder().name(name).build()

result = client.risk_detector(person)
print(f"Risk Type: {result.get_worst_risk().risk_type}")  # FakeRiskType.FICTIONAL
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.