Description: Retrieves gender probabilities (male, female) for up to 1,000 names.
API URL:
| Parameter | |
| key | your API key (string, 32) |
| 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.
| Parameter | |
| forename | forename (string) |
| 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:
<?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
{
"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
}
{
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
}
{
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.
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.
| 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 |
| Code | Message |
|---|---|
| 0008 | Unknown forename supplied |
| 0015 | Ran out of queries during execution |
| 0023 | No results for selected jurisdiction |
{
"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
}