gender-api/client

An easy to use API client for Gender-API.com

v1.0.4 2022-01-21 07:33 UTC

Requires

• php: >=8.0.0
• ext-fileinfo: *
• ext-mbstring: *

Requires (Dev)

• phpunit/phpunit: 9.*

MIT

• genderize
• gender api
• gender of names

README

About

PHP client for the Gender-API.com API.

Homepage: https://gender-api.com

FAQ: https://gender-api.com/en/frequently-asked-questions

API Docs: https://gender-api.com/en/api-docs

Contact: https://gender-api.com/en/contact

Installation

my-project$ composer require gender-api/client

API-Key

Get a free API key here: https://gender-api.com/en/account

Development

Start the dockerized development machine with

docker-compose up

Install all required packages

bin/composer install

Run all unit tests with mock data

bin/phpunit

Run all unit tests against the API

API_KEY=<yourkey> bin/phpunit

Simple Usage

use GenderApi\Client as GenderApiClient;

try {

    $apiClient = new GenderApiClient('insert your API key');
    $name = $apiClient->getByFirstName('elisabeth');

    if ($name->genderFound()) {
        echo $name->getGender(); // will return "female" (possible values: male, female, unknown)
    }

} catch (GenderApi\Exception $e) {
    // Name lookup failed due to a network error or insufficient requests left
    // See https://gender-api.com/en/api-docs/error-codes
    echo 'Exception: ' . $e->getMessage();
}

Advanced Usage

use GenderApi\Client as GenderApiClient;

try {

    $apiClient = new GenderApiClient('insert your API key');
    ````
    // Get gender by first name and country
    $name = $apiClient->getByFirstNameAndCountry('elisabeth', 'US');

    // Get gender by first name and client IP
    $name = $apiClient->getByFirstNameAndClientIpAddress('elisabeth', '178.27.52.144');

    // Get gender by first name and browser locale
    $name = $apiClient->getByFirstNameAndLocale('elisabeth', 'en_US');
    
    //Query multiple names with a single call
    foreach ($apiClient->getMultipleNames(array('stefan', 'elisabeth')) as $name) {
        if ($name->genderFound()) {
            echo $name->getName() . ': ' . $name->getGender(); // will return "female" (possible values: male, female, unknown)
        }
    }

} catch (GenderApi\Exception $e) {
    // Name lookup failed due to a network error or insufficient requests left
    // See https://gender-api.com/en/api-docs/error-codes
    echo 'Exception: ' . $e->getMessage();
}

Email Address

use GenderApi\Client as GenderApiClient;

try {

    $apiClient = new GenderApiClient('insert your API key');
    
    // Get gender by email address name and country
    $name = $apiClient->getByEmailAddress('[e-mail]');
    if ($name->genderFound()) {
        echo $name->getGender(); // will return "female"
    }
    
    // Get gender by email address name and country
    $name = $apiClient->getByEmailAddressAndCountry('[e-mail]', 'US');
    echo $name->getGender(); // will return "female"
    if ($name->genderFound()) {
        echo $name->getGender(); // will return "female"
    }
    
} catch (GenderApi\Exception $e) {
    // Name lookup failed due to a network error or insufficient requests left
    // See https://gender-api.com/en/api-docs/error-codes
    echo 'Exception: ' . $e->getMessage();
}

Split First And Last Name

use GenderApi\Client as GenderApiClient;

try {

    $apiClient = new GenderApiClient('insert your API key');
    
    // Get gender by email address name and country
    $name = $apiClient->getByFirstNameAndLastName('Frank Underwood');
 
    if ($name->genderFound()) {
        echo $name->getGender(); // will return "male"
        echo $name->getFirstName(); // will return "Frank"
        echo $name->getLastName(); // will return "Underwood"
    }

} catch (GenderApi\Exception $e) {
    // Name lookup failed due to a network error or insufficient requests left
    // See https://gender-api.com/en/api-docs/error-codes
    echo 'Exception: ' . $e->getMessage();
}

Country Of Origin

use GenderApi\Client as GenderApiClient;

try {

    $apiClient = new GenderApiClient('insert your API key');
    
    // Get gender by email address name and country
    $name = $apiClient->getCountryOfOrigin('Frank');
 
    if ($name->genderFound()) {
        echo $name->getGender(); // will return "male"
        echo $name->getFirstName(); // will return "Frank"
        echo $name->getLastName(); // will return "Underwood"
        
        echo $name->getCountryOfOriginMapUrl(); // will return a link to a map that displays the result in a rendered for
        
        foreach ($name->getCountryOfOrigin() as $country) {
                var_dump($country); // country of origin
        }
        
    }

} catch (GenderApi\Exception $e) {
    // Name lookup failed due to a network error or insufficient requests left
    // See https://gender-api.com/en/api-docs/error-codes
    echo 'Exception: ' . $e->getMessage();
}

Statistics

use GenderApi\Client as GenderApiClient;

try {

    $apiClient = new GenderApiClient('insert your API key');
    
    $stats = $apiClient->getStats();
    
    // Check your query limit
    if ($stats->isLimitReached()) {
        echo "query limit reached.";
    }
    
    // Get remaining requests
    echo $stats->getRemainingRequests() . ' requests left.';

} catch (GenderApi\Exception $e) {
    // Name lookup failed due to a network error
    // See https://gender-api.com/en/api-docs/error-codes
    echo 'Exception: ' . $e->getMessage();
}

Proxy

If you need a proxy server to access the Internet in your company, you can set one via the setProxy command.

use GenderApi\Client as GenderApiClient;

$apiClient = new GenderApiClient('insert your API key');
$apiClient->setProxy('localhost', 3128);