Gender API for PHP

Create one configured client

The PHP client targets PHP 8.1 and later. Install it through Composer, read the key from configuration backed by an environment variable, and construct the client in your dependency container. Reusing one configured service keeps authentication and timeout policy out of controllers and jobs.

Pass a two-letter country code when your record has a trustworthy country field. Read the result as an array containing gender plus its probability, confidence, evidence count and source. Keep gender nullable in DTOs and database columns so an unknown answer is not coerced into a category.

Do not place lookup calls in a Blade template or a synchronous page loop. Resolve data in an application service, and move large enrichments to a queue or the managed file workflow.

use NameGender\Client;

$client = new Client($_ENV['NAMEGENDER_API_KEY']);
$result = $client->name('Ayşe', country: 'TR');

echo $result['gender'] ?? 'unknown';
echo $result['probability'];
echo $result['source'];

Use bulk calls in queues and imports

When an import contains multiple records, collect independent lookup keys and send them through the bulk method. Deduplicate the combination of normalized name and country first, then map the returned values back to every original row.

Chunk work above the request limit and persist progress after each chunk. A queue retry can then resume from a known boundary. Keep business rules such as a minimum probability outside the HTTP client so they can change without rewriting transport code.

For a one-time spreadsheet, direct upload is usually simpler than building a Laravel import job. The dashboard previews the columns, estimates the credit cost and returns an enriched file without placing long network work inside a web request.

$results = $client->bulk(['Ayşe', 'Mehmet', 'Priya']);

foreach ($results as $result) {
    if (($result['probability'] ?? 0) >= 90) {
        // Apply your documented rule.
    }
}

Separate null, validation and transport errors

A successful response with gender set to null means there was not enough evidence. It should not trigger the same retry path as a connection timeout. Validation and authentication responses require a code or configuration change, while rate and eligible server failures may be retried with bounded backoff.

Set timeouts suitable for your request path. A page response should fail fast and fall back neutrally; a queue worker can wait longer and retry. In either case, avoid swallowing the status into a blank field that cannot be diagnosed later.

Exclude API keys and full customer records from logs, exception context and monitoring breadcrumbs. A request identifier, status, latency and internal record key are normally sufficient for tracing without copying personal data into another system.

Questions

Related pages