Skip to content

markus-perl/gender-api-client

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
bin
 
 
 
 
 
 
 
 
 
 

Gender-API.com PHP Client

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('elisabeth1499@gmail.com');
    if ($name->genderFound()) {
        echo $name->getGender(); // will return "female"
    }
    
    // Get gender by email address name and country
    $name = $apiClient->getByEmailAddressAndCountry('elisabeth.smith776@gmail.com', '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);