Contents

Gender API: Single Request Documentation

Description: Retrieves probabilities for a forename's gender (male, female).

API URL:

https://ono.4b.rs/v1/gen
Required parameters passed by GET:
Parameter
key your API key (string, 32)
forename forename (string)
Optional parameters passed by GET:
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)

Example call to get prediction for Meredith:

https://ono.4b.rs/v1/gen?key=[YOUR_API_KEY]&forename=Meredith
Result:
{
   "world":{
      "gender":"f",
      "percent":99,
      "sample":53887
   },
   "jurisdictions":[
      {
         "jurisdiction":"United States",
         "iso":"us",
         "gender":"f",
         "percent":"100",
         "sample":"49032"
      },
      {
         "jurisdiction":"France",
         "iso":"fr",
         "gender":"f",
         "percent":"100",
         "sample":"933"
      },
      {
         "jurisdiction":"Philippines",
         "iso":"ph",
         "gender":"f",
         "percent":"97",
         "sample":"787"
      }
   ],
   "forename":"Meredith",
   "remainingCredits":810153
}
The structure of the JSON result is:
{
	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
}
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 bearers with the aforementioned gender,
     sample: number of records denoting name-gender relationships the percent was calculated from
}

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

There is a limit of three results for jurisdictions (if no jurisdiction was supplied in the GET request) and four (if one was).

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.

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
0019 Jurisdiction is not recognized
0022 Recognized forename is required
Notices
Code Message
0023 No results for selected jurisdiction
Example:
{
   "status":[
      {
         "type":"error",
         "code":"0001",
         "message":"API key not supplied"
      },
      {
         "type":"error",
         "code":"0002",
         "message":"Forename not supplied"
      },
      {
         "type":"error",
         "code":"0023",
         "message":"No results for selected jurisdiction"
      }
   ]
}