Description: Retrieves nationality probabilities 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): fn, sn, ssn, sanitize and id.
| Parameter | |
| fn | forename (string) |
| sn | surname (string) |
| Parameter | |
| ssn | second surname [Spanish/Portugese tradition] (string) |
| 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( 'fn' => 'John2', 'sn' => 'Adams', 'id' => 1, 'sanitize' => 1 ), array( 'fn' => 'Kylie', 'sn' => 'Minogue', 'id' => 2 ), array( 'fn' => 'Vladimir', 'sn' => 'Putin', 'id' => 3 ), array( 'fn' => 'Svetlana', 'sn' => 'Veličković', 'id' => 4 ), array( 'fn' => 'Aleksandar', 'sn' => 'Vučić', 'id' => 5 ), array( 'fn' => 'Googie', 'sn' => 'Withers', 'id' => 6 ), array( 'fn' => 'Carlos', 'sn' => 'Valderrama', 'ssn' => 'Palacio', 'id' => 70 ), array( 'fn' => 'Melanija', 'sn' => 'Knavs', 'id' => 80 ), array( 'fn' => 'Donald', 'sn' => 'Trump', 'id' => 90 ), array( 'fn' => 'Michelle', 'sn' => 'Robinson', 'id' => 1000 ), array( 'fn' => 'Barrack', 'sn' => 'Obama', 'id' => 1100 ), array( 'fn' => 'Tallulah', 'sn' => 'Ormsby-Gore', 'id' => 1200 ), array( 'fn' => 'Thomas', 'sn' => 'Eaton', 'id' => 1300 ), array( 'fn' => 'Julie', 'sn' => 'Bindell', 'id' => 1400 ), array( 'fn' => 'Lianjie', 'sn' => 'Li', 'id' => 1500 ), array( 'fn' => 'Sara', 'sn' => 'Ben-Artzi', 'id' => 1600 ), array( 'fn' => 'Eric', 'sn' => 'Weinstein', 'id' => 1700 ), array( 'fn' => 'Sheikh', 'sn' => 'Hasina', 'id' => 1800 ), array( 'fn' => 'Bob', 'sn' => 'Cratchit', 'id' => 1900 ), array( 'fn' => 'Martha', 'sn' => 'Cratchit', 'id' => 2000 ), array( 'fn' => 'Emmett-Hovhannes', 'sn' => 'Yawners', 'id' => 2100 ), array( 'fn' => 'Владимир', 'sn' => 'Путин', 'id' => 2101, 'sanitize' => 1 ), array( 'fn' => 'VladimirВладимир', 'sn' => 'PutinПутин', 'sanitize' => 1 ), ); $j = json_encode( $src ); $url = 'https://ono.4b.rs/v1/nats?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 . ' ' . mb_strtoupper( $person->surname ); if( isset( $person->secondSurname ) && $person->secondSurname ) echo ' ' . mb_strtoupper( $person->secondSurname ); echo $nl; if( isset( $person->countries[0] ) ) { echo 'Most likely from: '; echo $person->countries[0]->jurisdiction . $nl; } if( isset( $person->countries[1] ) ) { echo '2nd most likely from: '; echo $person->countries[1]->jurisdiction . $nl; } if( !isset( $person->countries[0] ) ) echo 'No data found' . $nl; echo '------------------------------------------------------------------------------------' . $nl; } ?>
Replace $apikey on line 7 with your API key
{
"results":[
{
"countries":[
{
"jurisdiction":"United States",
"percent":"49.73746"
},
{
"jurisdiction":"England",
"percent":"8.02789"
},
{
"jurisdiction":"Nigeria",
"percent":"7.12802"
},
{
result truncated for this example
}
],
"forename":"John",
"surname":"Adams",
"secondSurname":null,
"id":1
},
{
"countries":[
{
"jurisdiction":"Australia",
"percent":"52.61582"
},
{
"jurisdiction":"United States",
"percent":"17.68804"
},
{
"jurisdiction":"England",
"percent":"8.23110"
},
{
result truncated for this example
}
],
"forename":"Kylie",
"surname":"Minogue",
"secondSurname":null,
"id":2
},
{
"countries":[
{
"jurisdiction":"Russia",
"percent":"60.52150"
},
{
"jurisdiction":"Ukraine",
"percent":"15.80883"
},
{
"jurisdiction":"Uzbekistan",
"percent":"5.83457"
},
{
result truncated for this example
}
],
"forename":"Vladimir",
"surname":"Putin",
"secondSurname":null,
"id":3
},
{
"countries":[
{
"jurisdiction":"Serbia",
"percent":"72.42970"
},
{
"jurisdiction":"Russia",
"percent":"13.44453"
},
{
"jurisdiction":"Ukraine",
"percent":"4.56467"
},
{
result truncated for this example
}
],
"forename":"Svetlana",
"surname":"Veli\u010dkovi\u0107",
"secondSurname":null,
"id":4
},
{
"countries":[
{
"jurisdiction":"Serbia",
"percent":"46.94514"
},
{
"jurisdiction":"Bosnia and Herzegovina",
"percent":"24.05671"
},
{
"jurisdiction":"Croatia",
"percent":"12.05470"
},
{
result truncated for this example
}
],
"forename":"Aleksandar",
"surname":"Vu\u010di\u0107",
"secondSurname":null,
"id":5
},
{
"countries":[
{
"jurisdiction":"United States",
"percent":"33.02634"
},
{
"jurisdiction":"England",
"percent":"26.54387"
},
{
"jurisdiction":"Australia",
"percent":"7.29646"
},
{
result truncated for this example
}
],
"forename":"Googie",
"surname":"Withers",
"secondSurname":null,
"id":6
},
{
"countries":[
{
"jurisdiction":"Colombia",
"percent":"27.92171"
},
{
"jurisdiction":"Mexico",
"percent":"8.24558"
},
{
"jurisdiction":"Argentina",
"percent":"7.75041"
},
{
result truncated for this example
}
],
"forename":"Carlos",
"surname":"Valderrama",
"secondSurname":"Palacio",
"id":70
},
{
"countries":[
{
"jurisdiction":"Slovenia",
"percent":"72.29706"
},
{
"jurisdiction":"Serbia",
"percent":"10.15597"
},
{
"jurisdiction":"Lithuania",
"percent":"4.67919"
},
{
result truncated for this example
}
],
"forename":"Melanija",
"surname":"Knavs",
"secondSurname":null,
"id":80
},
{
"countries":[
{
"jurisdiction":"United States",
"percent":"73.61724"
},
{
"jurisdiction":"Germany",
"percent":"6.36045"
},
{
"jurisdiction":"England",
"percent":"5.49194"
},
{
result truncated for this example
}
],
"forename":"Donald",
"surname":"Trump",
"secondSurname":null,
"id":90
},
{
"countries":[
{
"jurisdiction":"United States",
"percent":"56.04764"
},
{
"jurisdiction":"England",
"percent":"11.90038"
},
{
"jurisdiction":"Philippines",
"percent":"5.25999"
},
{
result truncated for this example
}
],
"forename":"Michelle",
"surname":"Robinson",
"secondSurname":null,
"id":1000
},
{
"countries":[
{
"jurisdiction":"Kenya",
"percent":"45.52209"
},
{
"jurisdiction":"Equatorial Guinea",
"percent":"35.07731"
},
{
"jurisdiction":"Cameroon",
"percent":"9.41892"
},
{
result truncated for this example
}
],
"forename":"Barrack",
"surname":"Obama",
"secondSurname":null,
"id":1100
},
{
"countries":[
{
"jurisdiction":"England",
"percent":"62.27848"
},
{
"jurisdiction":"Wales",
"percent":"19.07173"
},
{
"jurisdiction":"United States",
"percent":"12.15190"
},
{
result truncated for this example
}
],
"forename":"Tallulah",
"surname":"Ormsby-Gore",
"secondSurname":null,
"id":1200
}
]
}
{
result:[{
countries: [array of countries with percentage chance name is a national of it],
spheres: [array of naming custom spheres with percentage chance name belongs to it],
forename: forename supplied,
surname: surname supplied,
secondSurname: second surname (if supplied),
sanitizedForename: sanitized forename (if sanitize was enabled),
sanitizedSurname: sanitized surname (if sanitize was enabled),
sanitizedSecondSurname: sanitized second surname (if supplied and sanitize was enabled),
id: id (if supplied),
status: [array of error messages and notices]
}],
status: [array of error messages and notices],
creditsRemaining: number of API credits remaining
}
See the list of countries and onospheres.
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 |
| 0003 | Surname not supplied |
| 0004 | Sanitized forename is empty |
| 0005 | Sanitized surname is empty |
| 0006 | API key not recognised |
| 0007 | Out of credits |
| 0011 | Recognised forename and surname are required |
| 0012 | Names JSON not supplied |
| 0013 | Names JSON is invalid |
| 0014 | Names JSON can't contain more than 1000 queries |
| Code | Message |
|---|---|
| 0008 | Unknown forename supplied |
| 0009 | Unknown surname supplied |
| 0010 | Unknown second surname supplied |
| 0015 | Ran out of queries during execution |
{
"results":[
{
"forename":"Madeup",
"surname":"Unknown-Surname",
"secondSurname":null,
"status":[
{
"type":"notice",
"code":"0009",
"message":"Unknown surname supplied"
},
{
"type":"error",
"code":"0011",
"message":"Recognised forename and surname are required"
}
],
"id":1
},
{
"forename":"runcible",
"surname":"surname",
"secondSurname":null,
"status":[
{
"type":"notice",
"code":"0008",
"message":"Unknown forename supplied"
},
{
"type":"error",
"code":"0011",
"message":"Recognised forename and surname are required"
}
],
"id":2
},
{
"forename":"namethatdoesnotexist",
"surname":"surname-not-in-existance",
"secondSurname":null,
"status":[
{
"type":"notice",
"code":"0008",
"message":"Unknown forename supplied"
},
{
"type":"notice",
"code":"0009",
"message":"Unknown surname supplied"
},
{
"type":"error",
"code":"0011",
"message":"Recognised forename and surname are required"
}
],
"id":3
}
],
"remainingCredits":99301
}