A modern, type-safe PHP client for the Gender-API.com service. Determine gender from first names, full names, or email addresses with high accuracy across 200+ countries.
- 🔍 Name Gender Detection - Detect gender from first names with 99%+ accuracy
- 🌍 Country Localization - Improve accuracy with country-specific results
- 📧 Email Analysis - Extract and analyze names from email addresses
- 🗺️ Country of Origin - Discover name origins and geographic distribution
- 📊 Batch Processing - Query multiple names in a single API call
- 🔒 Type-Safe - Full PHP 8.3+ support with strict typing
- ⚡ Modern - PSR-4 autoloading, PHPUnit 11, PHPStan Level 6
Install via Composer:
composer require gender-api/clientGet your free API key at: gender-api.com/account
<?php
use GenderApi\Client as GenderApiClient;
$client = new GenderApiClient('your-api-key');
// Simple gender lookup
$result = $client->getByFirstName('Elisabeth');
if ($result->genderFound()) {
echo $result->getGender(); // "female"
echo $result->getAccuracy(); // 99
}For names that vary by country (e.g., "Andrea" is male in Italy, female in Germany):
// In Italy, Andrea is typically male
$result = $client->getByFirstNameAndCountry('Andrea', 'IT');
echo $result->getGender(); // "male"
// In Germany, Andrea is typically female
$result = $client->getByFirstNameAndCountry('Andrea', 'DE');
echo $result->getGender(); // "female"Detect country from IP address or browser locale:
// Localize by IP address
$result = $client->getByFirstNameAndClientIpAddress('Jan', '178.27.52.144');
// Localize by browser locale
$result = $client->getByFirstNameAndLocale('Jan', 'de_DE');The API automatically splits full names and identifies the first name:
$result = $client->getByFirstNameAndLastName('Sandra Miller');
echo $result->getFirstName(); // "Sandra"
echo $result->getLastName(); // "Miller"
echo $result->getGender(); // "female"With country and strict mode:
$result = $client->getByFirstNameAndLastNameAndCountry(
'Maria Garcia',
'ES',
strict: true
);Extract and analyze names from email addresses:
$result = $client->getByEmailAddress('elisabeth.smith@company.com');
echo $result->getGender(); // "female"
echo $result->getFirstName(); // "Elisabeth" (extracted)
echo $result->getLastName(); // "Smith"Query multiple names in a single API call for efficiency:
$names = ['Michael', 'Sarah', 'Kim', 'Jordan'];
$results = $client->getByMultipleNames($names);
foreach ($results as $result) {
printf(
"%s: %s (%d%% confidence)\n",
$result->getFirstName(),
$result->getGender(),
$result->getAccuracy()
);
}
// Output:
// Michael: male (99% confidence)
// Sarah: female (99% confidence)
// Kim: female (72% confidence)
// Jordan: male (68% confidence)With country filter:
$results = $client->getByMultipleNamesAndCountry(['Andrea', 'Nicola'], 'IT');Discover where a name originates from:
$result = $client->getCountryOfOrigin('Giuseppe');
echo $result->getGender(); // "male"
foreach ($result->getCountryOfOrigin() as $country) {
printf(
"%s (%s): %.0f%%\n",
$country->getCountryName(),
$country->getCountry(),
$country->getProbability() * 100
);
}
// Output:
// Italy (IT): 89%
// Argentina (AR): 4%
// United States (US): 3%
// Get interactive map URL
echo $result->getCountryOfOriginMapUrl();Monitor your API usage:
$stats = $client->getStats();
echo $stats->getRemainingCredits(); // 4523
echo $stats->isLimitReached(); // false$client = new GenderApiClient('your-api-key');
$client->setProxy('proxy.company.com', 3128);For enterprise or on-premise installations:
$client = new GenderApiClient('your-api-key');
$client->setApiUrl('https://custom-api.example.com/');- PHP 8.3 or higher
- Composer
# Clone the repository
git clone https://github.com/markus-perl/gender-api-client.git
cd gender-api-client
# Install dependencies
composer install
# Start Docker environment (optional)
docker-compose up -d# Unit tests (with mocked data)
./vendor/bin/phpunit --testsuite unit
# Integration tests (requires API key in .env)
cp .env.example .env
# Edit .env and add your API key
./vendor/bin/phpunit --testsuite integration
# All tests
./vendor/bin/phpunit --testsuite unit,integration./vendor/bin/phpstan analyse| Property | Type | Description |
|---|---|---|
getFirstName() |
?string |
The queried name |
getProbability() |
?float |
Probability (e.g. 0.99) |
getGender() |
?string |
"male", "female", or "unknown" |
getAccuracy() |
?int |
Confidence percentage (0-100) |
getSamples() |
?int |
Number of data samples |
getCountry() |
?string |
ISO 3166-1 country code |
genderFound() |
bool |
Whether a gender was determined |
| Property | Type | Description |
|---|---|---|
getRemainingCredits() |
?int |
API credits remaining |
isLimitReached() |
?bool |
Whether quota is exhausted |
use GenderApi\Client as GenderApiClient;
use GenderApi\Client\ApiException;
use GenderApi\Client\RuntimeException;
use GenderApi\Client\InvalidArgumentException;
use GenderApi\Client\Downloader\NetworkErrorException;
try {
$result = $client->getByFirstName('Elisabeth');
} catch (InvalidArgumentException $e) {
// Invalid input parameters
} catch (ApiException $e) {
// API returned an error (e.g., invalid key, limit exceeded)
echo $e->getCode(); // Error code
echo $e->getMessage(); // Error message
} catch (NetworkErrorException $e) {
// Network connectivity issues
} catch (RuntimeException $e) {
// Other runtime errors (e.g., missing API key)
}- Homepage: gender-api.com
- API Documentation: gender-api.com/api-docs
- OpenAPI Specification: docs/openapi.yml
- FAQ: gender-api.com/faq
- Error Codes: gender-api.com/error-codes
- Support: gender-api.com/contact
This project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request