README

A simple Laravel 12+ client for the Genderize.io API. It provides a fluent interface for easy request building.

Version overview

From v13.0.0 on, the package major version matches the highest Laravel major version it supports. v13.0.0 supports Laravel 13.x and 12.x. This is the only maintained line: master is where it is developed, and the v13.x branch tracks it and carries the released state.

Deprecated releases

Earlier releases stay installable and unchanged, but they are no longer maintained: they receive no fixes and no further releases. Laravel 11.x and 10.x are past their security support window, and Composer refuses to install them because of published security advisories.

The Laravel 5.x releases live in the archived pixelpeter/laravel5-genderize-api-client repository: 2.0.x for Laravel 5.7 and 5.6, 1.1.x/2.0.x for Laravel 5.5. That repository is read-only.

Installation

Step 1: Install Through Composer

composer require pixelpeter/laravel-genderize-api-client

Step 2: Use the Facade

Package discovery registers the service provider and the Genderize alias, so there is nothing to add by hand. If you have disabled discovery for this package, register the alias in bootstrap/app.php or use the facade class directly:

use Pixelpeter\Genderize\Facades\Genderize;

Step 3: Publish the configuration file

This is only needed when you have an API key from Genderize.io

php artisan vendor:publish --provider="Pixelpeter\Genderize\GenderizeServiceProvider"

Examples

Send requests

Single name

use Genderize;

Genderize::name('Peter')->get();

Multiple names (max. 10)

use Genderize;

Genderize::name(['John', 'Jane'])->get();

// or for better readability you can use the plural
Genderize::names(['John', 'Jane'])->get();

Add language and country options

use Genderize;

Genderize::name('John')->country('US')->lang('EN')->get();

Working with the response

For single usage

use Genderize;

$response = Genderize::name('Peter')->get();

print $response->result->gender; // 'male'
print $response->result->name; // 'Peter'
print $response->result->probability; '0.99'
print $response->result->count; 144
print $response->result->isMale(); true
print $response->result->isFemale(); false
print $response->result->isNotMale(); false
print $response->result->isNotFemale(); true

For batch usage

use Genderize;

$response = Genderize::names(['John', 'Jane'])->country('US')->lang('EN')->get();

foreach($response->result as $row)
{
    print $row->name;
}

Getting information about the request and limits

use Genderize;

$response = Genderize::name('Peter')->get();

print $response->meta->code; // 200 - HTTP response code
print $response->meta->limit; // 1000 - Max number of allowed requests
print $response->meta->remaining; // 950 - Number of requests left
print $response->meta->reset->diffInSeconds(); // Carbon\Carbon - time left till reset

More documentation

Refer to Genderize.io API Documentation for more examples and documentation.

Testing

Run the tests with:

vendor/bin/phpunit

License

The MIT License (MIT). Please see License File for more information.