Request parameters

Request URL

This is the easiest way to parse a name into it useful components. Each response is JSON encoded so easy to use. You can copy past the request URL in the address bar of your browser to see the response.

https://api.parser.name/?api_key=YOUR_KEY&endpoint=parse&name=John%20Smith

If you know the country code of the name then you can add the country code parameter. By specifying the country code the accuracy of the gender will increase. All endpoints use the ISO 3166-2 for country codes. Check our list of countries to see all supported country codes.

https://api.parser.name/?api_key=YOUR_KEY&endpoint=parse&name=John%20Smith&country_code=US

It is possible to query multiple names in a single request. You can send a maximum array of 25 names in the same request. For the rate limit this counts as a single request making it ideal of you want to process high volumes of names. If you also use the country_code then you have to make an array of that as well.

https://api.parser.name/?api_key=YOUR_KEY&endpoint=parse&name[]=John%20Smith&name[]=Sarah%20Jones

Code examples

To make it extra easy to get started we prepared a few code examples. Choose a programming language below and copy the code to get started. Don't forget to replace the YOUR_KEY with the API key your API key.

• PHP
• Python
• Javascript
• C#

<?php

function parseName($name){

    //Create variables (don't forget your API key).
    $api_key = "YOUR_KEY";
    $name = urlencode($name);
    $url = "https://api.parser.name/?api_key=".$api_key."&endpoint=parse&name=".$name;

    //Do some cURL magic here.
    $handle = curl_init();
    curl_setopt($handle, CURLOPT_URL, $url);
    curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($handle);
    if($response != false) {
        $output = json_decode($response, true);
    } else {
        return false;
    }

    //Return the complete name object.
    return $output['data'][0]['name'];
}

//Parse a name into an object.
$object = parseName("John Smith");

//Print out the data.
print_r($object['firstname']); //Returns firstname object.
print_r($object['firstname']['name']); //Return the firstname "John".
print_r($object['firstname']['gender']); //Returns the gender: "m".
print_r($object['lastname']); //Returns firstname object.

?>

Coming soon

Coming soon

Coming soon

Response object

{
    results: 1,
    error: null,
    data: [
        {
            salutation: {
                salutation: "Mr.",
                initials: "J.",
                lastname: "Smith"
            },
            title: null,
            name: {
                nickname: null,
                firstname: {
                    name: "John",
                    name_ascii: "John",
                    validated: true,
                    gender: "m",
                    gender_formatted: "male",
                    unisex: false,
                    gender_deviation: 0,
                    country_code: "US",
                    country_certainty: 60,
                    country_rank: 3,
                    alternative_countries: {
                        GB: 13,
                        CA: 3
                    }
                },
                middlenames: null,
                lastname: {
                    name: "Smith",
                    name_ascii: "Smith",
                    validated: true,
                    country_code: "US",
                    country_certainty: 62,
                    country_rank: 1,
                    alternative_countries: {
                        GB: 24,
                        CA: 3,
                        AU: 3
                    }
                }
            },
            country: {
                country_code: "US",
                country_certainty: 63,
                country_code_alpha: "USA",
                name: "United States",
                continent: "North America",
                demonym: "American",
                primary_language_code: "en",
                primary_language: "English",
                currency: "USD",
                alternative_countries: {
                    GB: 19,
                    CA: 3,
                    AU: 3
                }
            }
        }
    ]
}

Response parameters

Most response parameters are self-explanatory. However, there are a few fields that need an additional explanation. These fields are listed in the table below. If you're looking for is a response parameter that is not in this list, please contact us and we'll add it to this list.