API Documentation

Basic Use

The only thing you need to do for gender query is send the query to following address. The result of all your queries get back as JSON data.


Request
                                    
                                        GET https://genderapi.io/api/?name=abraham&key=<YourAPIKey>
                                    
                                
Field Data Type Description
name String Name to query
key String Your API key
Response
                                    
                                        {
                                            "name":"abraham",
                                            "q":"abraham",
                                            "gender":"male",
                                            "total_names":1173,
                                            "probability":99,
                                            "status":true,
                                            "duration":"106ms",
                                            "used_credits":1,
                                            "remaining_credits":472,
                                            "expires":1523404800,
                                            "server":"genderapi.io/api"
                                        }
                                    
                                
Field Data Type Description
name String Queried name

q String Name string that sent
gender String Possible values: male, female, null
total_names Integer Number of records that match your request on our server
probability String Determines the trueness of our service. 90 means that the result of gender query is 90% correct
status Boolean Result of your request (true or false)
duration String Processing time of your request on server
used_credits Integer Number of credits used on this request
remaining_credits Integer Number of credits remaining on your package
expires Timestamp Expiration date of your package
server String Server that responding to your request

Basic Installation

Basic sample codes for integration

                                        
                                           <?php
                                            function findGender($name) {
                                                $apiKey = ''; //Your API Key
                                                $getGender = json_decode(file_get_contents('https://genderapi.io/api/?key=' . $apiKey . '&name=' . urlencode($name)));
                                                return $getGender->gender;
                                            }
                                            echo findGender('angela');
                                        
                                    
Run Online

Composer command

                                    
                                        $ composer require genderapi/php-client
                                    
                                
                                        
                                           <?php
                                            use GenderApi\GenderApi;

                                            $genderApi = new GenderApi('Your API Key');
                                            $getGender = $genderApi->findGender('britney');

                                            echo $getGender;

                                            // OR, Get Result
                                            $getResult = $genderApi->result('britney');
                                            print_r($getResult);
                                        
                                    
View on GitHub

Python 3.*

                                        
                                            import json
                                            from urllib.request import urlopen

                                            apiKey = "" #Your API Key
                                            apiUrl = "https://genderapi.io/api/?name=georgi&key=" + apiKey

                                            result = urlopen(apiUrl).read().decode('utf-8')
                                            getGender = json.loads(result)

                                            print( "Gender: " + getGender["gender"]);
                                        
                                    
Run Online

Python 2.*

                                        
                                            import json
                                            import urllib2

                                            apiKey = "" #Your API Key
                                            apiUrl = "https://genderapi.io/api/?name=irina&key=" + apiKey
                                            getGender = json.load(urllib2.urlopen(apiUrl))

                                            print "Gender: " + getGender["gender"];
                                        
                                    
Run Online
                                        
                                            import java.io.IOException;
                                            import java.io.BufferedReader;
                                            import java.io.InputStreamReader;
                                            import java.net.URL;
                                            import java.net.HttpURLConnection;
                                            import com.google.gson.Gson;
                                            import com.google.gson.JsonObject;

                                            public class Main {

                                                public static void main(String[] args) {
                                                    try {
                                                        String apiKey = ""; //Your API Key
                                                        URL apiUrl = new URL("https://genderapi.io/api/?name=elvan&key=" + apiKey);
                                                        HttpURLConnection connect = (HttpURLConnection) apiUrl.openConnection();

                                                        if (connect.getResponseCode() != 200) {
                                                          throw new RuntimeException("An server error: " + connect.getResponseCode());
                                                        }

                                                        InputStreamReader iStream = new InputStreamReader(connect.getInputStream());
                                                        BufferedReader bReader = new BufferedReader(iStream);
                                                        Gson gson = new Gson();
                                                        JsonObject jsonOb = gson.fromJson(bReader, JsonObject.class);

                                                        String result = jsonOb.get("gender").getAsString();
                                                        System.out.println("Gender: " + result); // Gender: male
                                                        connect.disconnect();
                                                    } catch (IOException error) {
                                                        error.printStackTrace();
                                                    }
                                                }
                                            }
                                        
                                    

Javascript & jQuery Example

                                    
                                        <!-- Add Javascript & jQuery Library your project -->
                                        <script src="https://genderapi.io/assets/cdn/genderapi.min.js"></script>
                                    
                                
                                        
                                            //Javascript Code
                                            let API_KEY = ""; //Your API Key
                                            genderApi(API_KEY,"honor",function(result){
                                                console.log(result);
                                            });
                                        
                                    
Run Online
                                        
                                            //jQuery Code
                                            let API_KEY = ""; //Your API Key
                                            $.genderApi(API_KEY,"honor",function(result){
                                                console.log(result);
                                            });
                                        
                                    
Run Online

Javascript Callback Example

                                        
                                            <html>
                                                <head>
                                                    <meta charset="utf-8">
                                                    <title>GenderAPI.io - Javascript Callback Example</title>
                                                </head>
                                                <body>
                                                    <input readonly id="result"/>
                                                    <script>
                                                    function genderApiResult(result) {
                                                        var gender = document.getElementById('result');
                                                        if (result.gender) {
                                                            gender.value = result.gender;
                                                        } else {
                                                            gender.value = result.errmsg
                                                        }
                                                    }
                                                    </script>
                                                    <!-- Add Javascript Callback Library your project -->
                                                    <!-- Add your API key -->
                                                    <script src="//genderapi.io/api/?name=anna&callback=genderApiResult&key="></script>
                                                </body>
                                            
                                        
                                    
Run Online

Multiple Names Query

You can make multiple queries at once. The only thing you need is to put a "semicolon" between the names.

Request
                                    
                                        GET https://genderapi.io/api/?name=abraham;john;leyla&key=<YourAPIKey>
                                    
                                
Field Data Type Description
name String Name to query
key String Your API key
Response
                                    
                                        {
                                            "status":true,
                                            "duration":"64ms",
                                            "used_credits":3,
                                            "remaining_credits":494,
                                            "expires":1523404800,
                                            "server":"genderapi.io/api",
                                            "q":"abraham;john;leyla",
                                            "names":[
                                                {"name":"abraham","q":"abraham","gender":"male","total_names":1173,"probability":99},
                                                {"name":"john","q":"john","gender":"male","total_names":10855,"probability":100},
                                                {"name":"leyla","q":"leyla","gender":"female","total_names":6908,"probability":99}
                                            ]
                                        }
                                    
                                
Field Data Type Description
status Boolean Result of your request (true or false)
duration String Processing time of your request on server
used_credits Integer Number of credits used on this request
remaining_credits Integer Number of credits remaining on your package
expires Timestamp Expiration date of your package
server String Server that responding to your request
q String Name string that sent
names Array Results get back as JSON object in this string variable

Email Address

We can now determine the gender of the person from the email address. Let's look up to integration.

Request
                                    
                                        GET https://genderapi.io/api/email?email=innamaria@gmail.com&key=<YourAPIKey>
                                    
                                
Field Data Type Description
email String Email address
key String Your API key
Response
                                    
                                        {
                                            "name": "inna",
                                            "q": "innamaria@gmail.com",
                                            "gender": "female",
                                            "total_names": 661,
                                            "probability": 99,
                                            "status": true,
                                            "duration": "0.09s",
                                            "used_credits": 1,
                                            "remaining_credits": 88,
                                            "expires": 1533254400,
                                            "server": "genderapi.io"
                                        }
                                    
                                
Field Data Type Description
email String Email address that sent
q String Name string that sent
gender String Possible values: male, female, null
total_names Integer Number of records that match your request on our server
probability String Determines the trueness of our service. 90 means that the result of gender query is 90% correct
status Boolean Result of your request (true or false)
duration String Processing time of your request on server
used_credits Integer Number of credits used on this request
remaining_credits Integer Number of credits remaining on your package
expires Timestamp Expiration date of your package
server String Server that responding to your request

Detect Gender From Social Media

You can find the gender of Facebook, Instagram and Twitter users by querying their usernames.

Request {Facebook}
                                    
                                        GET https://genderapi.io/facebook/?q=zuck&key=<YourAPIKey>
                                    
                                
Request {Twitter}
                                    
                                        GET https://genderapi.io/twitter/?q=jack&key=<YourAPIKey>
                                    
                                
Request {Instagram}
                                    
                                        GET https://genderapi.io/instagram/?q=kevin&key=<YourAPIKey>
                                    
                                
Field Data Type Description
q String Username, URL or ID
key String Your API key
Response
                                    
                                        {
                                            "gender": "male",
                                            "total_names": 6040,
                                            "probability": 100,
                                            "name": "mark",
                                            "q": "Mark Zuckerberg",
                                            "status": true,
                                            "duration": "1.20s",
                                            "used_credits": 1,
                                            "remaining_credits": 92,
                                            "expires": 1536796800,
                                            "server": "genderapi.io",
                                            "userInfo": {
                                                "name": "Mark Zuckerberg",
                                                "id": "4",
                                                "profile_image": "..."
                                            }
                                        }
                                    
                                
Field Data Type Description
name String Queried name

q String Name string that sent
gender String Possible values: male, female, null
total_names Integer Number of records that match your request on our server
probability String Determines the trueness of our service. 90 means that the result of gender query is 90% correct
status Boolean Result of your request (true or false)
duration String Processing time of your request on server
used_credits Integer Number of credits used on this request
remaining_credits Integer Number of credits remaining on your package
expires Timestamp Expiration date of your package
server String Server that responding to your request
userInfo JSON Some information about the user you are inquiring about

Error Codes

Error codes that get back from your API queries.

Response
                                    
                                        {
                                            "status":false,
                                            "errno":94,
                                            "errmsg":"invalid or missing key",
                                            "server":"genderapi.io/api"
                                        }
                                    
                                
Error No (errno) Error Message (errmsg) Description
10 file content is empty URL file content is empty
11 file is not an image This is not an image file
12 file save error File saving error
13 invalid URL address Invalid URL Address
50 access denied Unauthorized IP Address. Please check your access privileges.
90 invalid country code Look at "admitted country codes"
91 name not set No name found in your request
92 too many names You can do maximum 100 name query at once
93 limit reached Reached to query limit
94 invalid or missing key Your API key is not found
96 user is not found User is not found
97 image file or url are not set URL or Image file is not found
500 null error Internal server error

What's next

Come on create an account now and start to send query. Who is it? A male or female?