Description: Retrieves probabilities for a name's nationality.
API URL:
| Parameter | |
| key | your API key (string, 32) |
| 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) |
Example call to get prediction for Zuly Sanguino Guapacha:
{
"countries":[
{
"jurisdiction":"Colombia",
"percent":"56.35321"
},
{
"jurisdiction":"Venezuela",
"percent":"14.72236"
},
{
"jurisdiction":"Mexico",
"percent":"5.52459"
},
{
"jurisdiction":"Spain",
"percent":"5.42824"
},
{
"jurisdiction":"Bolivia",
"percent":"4.50328"
},
{
"jurisdiction":"Guatemala",
"percent":"2.25460"
},
{
"jurisdiction":"Peru",
"percent":"1.74024"
},
{
"jurisdiction":"United States",
"percent":"1.60535"
},
{
"jurisdiction":"Argentina",
"percent":"1.49566"
},
{
"jurisdiction":"Tajikistan",
"percent":"1.34446"
},
{
"jurisdiction":"Bangladesh",
"percent":"1.08357"
},
{
"jurisdiction":"Ecuador",
"percent":"1.00501"
},
{
"jurisdiction":"Brazil",
"percent":"0.73671"
},
{
"jurisdiction":"Indonesia",
"percent":"0.48916"
},
{
"jurisdiction":"Uruguay",
"percent":"0.33056"
},
{
"jurisdiction":"Honduras",
"percent":"0.32314"
},
{
"jurisdiction":"Panama",
"percent":"0.25792"
},
{
"jurisdiction":"Chile",
"percent":"0.16454"
},
{
"jurisdiction":"Dominican Republic",
"percent":"0.12748"
},
{
"jurisdiction":"France",
"percent":"0.09190"
},
{
"jurisdiction":"Costa Rica",
"percent":"0.07560"
},
{
"jurisdiction":"Canada",
"percent":"0.07115"
},
{
"jurisdiction":"El Salvador",
"percent":"0.04892"
},
{
"jurisdiction":"Ireland",
"percent":"0.02075"
},
{
"jurisdiction":"India",
"percent":"0.02075"
},
{
"jurisdiction":"Italy",
"percent":"0.02075"
},
{
"jurisdiction":"England",
"percent":"0.01482"
},
{
"jurisdiction":"Russia",
"percent":"0.01186"
},
{
"jurisdiction":"Puerto Rico",
"percent":"0.01186"
},
{
"jurisdiction":"Belize",
"percent":"0.01186"
},
{
"jurisdiction":"DRCongo",
"percent":"0.01038"
},
{
"jurisdiction":"Nigeria",
"percent":"0.00889"
},
{
"jurisdiction":"Germany",
"percent":"0.00889"
},
{
"jurisdiction":"Sweden",
"percent":"0.00741"
},
{
"jurisdiction":"Nicaragua",
"percent":"0.00741"
},
{
"jurisdiction":"Paraguay",
"percent":"0.00593"
},
{
"jurisdiction":"China",
"percent":"0.00593"
},
{
"jurisdiction":"United Arab Emirates",
"percent":"0.00445"
},
{
"jurisdiction":"Cuba",
"percent":"0.00445"
},
{
"jurisdiction":"Israel",
"percent":"0.00296"
},
{
"jurisdiction":"Kazakhstan",
"percent":"0.00296"
},
{
"jurisdiction":"Norway",
"percent":"0.00296"
},
{
"jurisdiction":"Armenia",
"percent":"0.00296"
},
{
"jurisdiction":"Trinidad and Tobago",
"percent":"0.00296"
},
{
"jurisdiction":"Kyrgyzstan",
"percent":"0.00296"
},
{
"jurisdiction":"South Africa",
"percent":"0.00296"
},
{
"jurisdiction":"Singapore",
"percent":"0.00296"
},
{
"jurisdiction":"Switzerland",
"percent":"0.00296"
},
{
"jurisdiction":"Azerbaijan",
"percent":"0.00296"
},
{
"jurisdiction":"Australia",
"percent":"0.00296"
},
{
"jurisdiction":"Malaysia",
"percent":"0.00296"
},
{
"jurisdiction":"Netherlands",
"percent":"0.00148"
},
{
"jurisdiction":"Andorra",
"percent":"0.00148"
},
{
"jurisdiction":"Portugal",
"percent":"0.00148"
},
{
"jurisdiction":"Comoros",
"percent":"0.00148"
},
{
"jurisdiction":"Belgium",
"percent":"0.00148"
},
{
"jurisdiction":"Wales",
"percent":"0.00148"
},
{
"jurisdiction":"Yemen",
"percent":"0.00148"
}
],
"spheres":[
{
"sphere":"Hisponosphere",
"percent":"94.38647"
},
{
"sphere":"Other",
"percent":"3.01800"
},
{
"sphere":"Anglonosphere",
"percent":"1.71652"
},
{
"sphere":"Lusonosphere",
"percent":"0.73819"
},
{
"sphere":"Franconosphere",
"percent":"0.09190"
},
{
"sphere":"Italonosphere",
"percent":"0.02075"
},
{
"sphere":"Germanonosphere",
"percent":"0.01186"
},
{
"sphere":"Sinonosphere",
"percent":"0.00889"
},
{
"sphere":"Arabonosphere",
"percent":"0.00741"
}
],
"forename":"Zuly",
"surname":"Sanguino",
"secondSurname":"Guapacha",
"remainingCredits":45237
}
{
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],
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.
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 |
| Code | Message |
|---|---|
| 0008 | Unknown forename supplied | 0009 | Unknown surname supplied |
| 0010 | Unknown second surname supplied |
{
"status":[
{
"type":"error",
"code":"0001",
"message":"API key not supplied"
},
{
"type":"error",
"code":"0002",
"message":"Forename not supplied"
},
{
"type":"error",
"code":"0003",
"message":"Surname not supplied"
}
]
}