Gender API: Batch Request Documentation

Description: Retrieves gender probabilities (male, female) for up to 1,000 names.

API URL:

https://ono.4b.rs/v1/gens
Required parameters passed by GET:
Parameter
key your API key (string, 32)
Required parameters passed by POST
Parameter
names a JSON encoded array of names (up to 1,000)

The names POST parameter is an array of names that accepts the following properties (with the same function as the single request API): forename, jurisdiction, jurisdictionRequired, sanitize and id.

Required parameters for batch requests:
Parameter
forename forename (string)
Optional parameters for batch requests:
Parameter
jurisdiction iso jurisdiction code to get regional statistics from (string); see jurisdictions appendix for codes
jurisdictionRequired only returns results when the specified jurisdiction is included (int, 0 = off, 1 = on, defaults to off)
sanitize whether to sanitize name inputs (int, 0 = off, 1 = on, defaults to off); documenation
id an id to keep track of your requests (mixed)

An example names POST property:

[{"forename":"John","id":1,"sanitize":1},{"forename":"Michelle","id":1000}]
A working PHP example of a batch request:
<?php

error_reporting( E_ALL );
ini_set( 'display_errors', 1 );
setlocale( LC_CTYPE, 'en_US.UTF-8' );
mb_regex_encoding( 'UTF-8' );

$apikey = 'YOUR_API_KEY';

$src = array(
	array( 'forename' => 'John2', 'id' => 1, 'sanitise' => 1 ),
	array( 'forename' => 'Kylie', 'id' => 2 ),
	array( 'forename' => 'Vladimir', 'id' => 3 ),
	array( 'forename' => 'Svetlana', 'id' => 4 ),
	array( 'forename' => 'Aleksandar', 'id' => 5 ),
	array( 'forename' => 'Googie', 'id' => 6 ),
	array( 'forename' => 'Carlos', 'id' => 70 ),
	array( 'forename' => 'Melanija', 'id' => 80 ),
	array( 'forename' => 'Donald','id' => 90 ),
	array( 'forename' => 'Michelle', 'id' => 1000 ),
	array( 'forename' => 'Barrack', 'id' => 1100 ),
	array( 'forename' => 'Tallulah', 'id' => 1200 ),
	array( 'forename' => 'Thomas', 'id' => 1300 ),
	array( 'forename' => 'Julie', 'id' => 1400 ),
	array( 'forename' => 'Lianjie', 'id' => 1500 ),
	array( 'forename' => 'Sara', 'id' => 1600 ),
	array( 'forename' => 'Eric', 'id' => 1700 ),
	array( 'forename' => 'Sheikh', 'id' => 1800 ),
	array( 'forename' => 'Bob', 'id' => 1900 ),
	array( 'forename' => 'Martha', 'id' => 2000 ),
	array( 'forename' => 'Emmett-Hovhannes', 'id' => 2100 ),
	array( 'forename' => 'Владимир', 'id' => 2101, 'sanitise' => 1 ),
	array( 'forename' => 'VladimirВладимир', 'sanitise' => 1 ),
);
$j = json_encode( $src );

$url = 'https://ono.4b.rs/v1/gens?key=';

$c = curl_init();
curl_setopt( $c, CURLOPT_URL, $url . $apikey );
curl_setopt( $c, CURLOPT_POST, 1 );
curl_setopt( $c, CURLOPT_POSTFIELDS, 'names=' . $j );
curl_setopt( $c, CURLOPT_RETURNTRANSFER, true );
$out = curl_exec( $c );
curl_close( $c );

$nl = ( php_sapi_name() == 'cli' ) ? "\n" : '<br />';
$j = json_decode( $out );

foreach( $j->results as $person )
{
	if( isset( $person->id ) )
		echo '(' . $person->id . ') ';
	echo $person->forename;
	echo $nl;
	if( isset( $person->jurisdictions[0] ) )
	{
		echo $person->jurisdictions[0]->percent . '% chance of being a ' . ( ( $person->jurisdictions[0]->gender == 'm' ) ? 'male' : 'female' ) . ' in ';
		echo $person->jurisdictions[0]->jurisdiction . $nl;
		echo $person->world->percent . '% chance of being a ' . ( ( $person->world->gender == 'm' ) ? 'male' : 'female' ) . ' in the world' . $nl;
	}
	if( !isset( $person->jurisdictions[0] ) )
		echo 'No data found' . $nl;
	echo  '------------------------------------------------------------------------------------' . $nl;
}

?>

Replace $apikey on line 7 with your API key

Result:
{
	"results":[
		{
			"world":{
				"gender":"m",
				"percent":100,
				"sample":5963995
			},
			"jurisdictions":[
				{
					"jurisdiction":"United States",
					"iso":"us",
					"gender":"m",
					"percent":"100",
					"sample":"3772273"
				},
				{
					"jurisdiction":"England",
					"iso":"gb-eng",
					"gender":"m",
					"percent":"100",
					"sample":"438168"
				},
				{
					"jurisdiction":"Philippines",
					"iso":"ph",
					"gender":"m",
					"percent":"99",
					"sample":"412346"
				}
			],
			"forename":"John",
			"id":1
		},
		{
			"world":{
				"gender":"f",
				"percent":100,
				"sample":9707
			},
			"jurisdictions":[
				{
					"jurisdiction":"United States",
					"iso":"us",
					"gender":"f",
					"percent":"100",
					"sample":"6029"
				},
				{
					"jurisdiction":"England",
					"iso":"gb-eng",
					"gender":"f",
					"percent":"100",
					"sample":"2295"
				},
				{
					"jurisdiction":"Canada",
					"iso":"ca",
					"gender":"f",
					"percent":"100",
					"sample":"259"
				}
			],
			"forename":"Kylie",
			"id":2
		},
		{
		   result truncated for this example
		}
	],
	"remainingCredits":7647162
}
The structure of the JSON result is:
{
	result:[{
		world: name's global gender distribution,
		jurisdictions: [array of jurisdictions with the name's gender distribution],
		forename: forename supplied,
		sanitizedForename: sanitized forename (if sanitize was enabled),
		id: id (if supplied),
		status: [array of error messages and notices],
		creditsRemaining: number of API credits remaining
	}],
	status: [array of error messages and notices],
	creditsRemaining: number of API credits remaining
}
The structure of the jurisdiction result is:
{
     jurisdiction: name of jurisdiction name occurs in,
     iso: unique identifier of the jurisdiction, usually an ISO code,
     gender: most common gender of the name in the jurisdiction (m = male, f = female),
     percent: percent of people wo bear the name with the aforementioned gender,
     sample: number of records denoting name-gender relationships the percent was calculated from
}

For example, in the above result for Kylie, the first result means: in The United States 100% of people with the name Kylie are female (f); and this was calculated from 6,029 records denoting the gender of people named Kylie.

See the list of jurisdictions.

Errors and Notices

A number of errors and notices are provided in the JSON result. They appear in the root of the JSON and in the root of each name response.

Errors and notices have three properties: type, code and message.

Errors
Code Message
0001 API key not supplied
0002 Forename not supplied
0004 Sanitized forename is empty
0006 API key not recognised
0007 Out of credits
0012 Names JSON not supplied
0013 Names JSON is invalid
0014 Names JSON can't contain more than 1000 queries
0019 Jurisdiction is not recognized
0022 Recognized forename is required
Notices
Code Message
0008 Unknown forename supplied
0015 Ran out of queries during execution
0023 No results for selected jurisdiction
Example:
{
	"results":[
		{
			"forename":"Non-Existent-Name",
			"status":[
				{
					"type":"error",
					"code":"0022",
					"message":"Recognized forename is required"
				}
			],
			"id":1
		},
		{
			"forename":"This-Does-Not-Exist",
			"status":[
				{
					"type":"error",
					"code":"0022",
					"message":"Recognized forename is required"
				}
			],
			"id":1
		}
	],
	"remainingCredits":7647162
}