Here's an example of how to find names that satisfy the following requirements:
The example returns Page 1 of the results, where each page has 10 results, and sorts the results according to the popularity of the name, in descending order (with the most popular names appearing at the top of the results), and formats the result as JSON.
GET /api/names?regex=^mi.*a$&sort=freq-desc&page-size=10&page=1&gender=female&format=json
That call returns JSON that looks like this:
{"time":"0.023s",
"total-matches":12,
"page":1,
"page-size":10,
"regex":"^mi.*a$",
"starts-with":null,
"ends-with":null,
"contains-string":null,
"contains-letters":null,
"min-length":null,
"max-length":null,
"format":"json",
"sort":"freq-desc",
"results":[
{"name":"Mina", "freq":479, "gender":"female", "length":4},
{"name":"Mia", "freq":223, "gender":"female", "length":3},
{"name":"Miranda", "freq":183, "gender":"female", "length":7},
{"name":"Michaela", "freq":69, "gender":"female", "length":8},
{"name":"Mikayla", "freq":11, "gender":"female", "length":7},
{"name":"Mikala", "freq":10, "gender":"female", "length":6},
{"name":"Mila", "freq":7, "gender":"female", "length":4},
{"name":"Micaela", "freq":6, "gender":"female", "length":7},
{"name":"Migdalia", "freq":5, "gender":"female", "length":8},
{"name":"Mira", "freq":5, "gender":"female", "length":4}
]
}
The regex parameter accepts a regular expression and causes the API to return results where the name matches the regular expression. You should url-encode special regular expression characters. The API interprets the regex parameter value as a Perl-compatible regular expression.
The starts-with parameter causes the API to return names that start with the given string of letters. Calling the API with this parameter is computationally less expensive and faster than using the regex parameter with a value that does the same thing.
The ends-with parameter causes the API to return names that end with the given string of letters. Calling the API with this parameter is computationally less expensive and faster than using the regex parameter with a value that does the same thing.
The contains-letters parameter accepts a string of letters that the API uses to filter results. The API returns names that contain all the letters in the contains-letters string, in any order, and without regard for how many times each letter in the contains-letters string appears in the name, except that each letter in the contains-letters string must appear at least once in the name.
The contains-string parameter works like the contains-letter parameter, but is more strict: the name must contain the letters in the same order as they appear in the given string. For example, the value “ROB” will return results that include the name “Robert” but not “Boris”. Calling the API with this parameter is computationally less expensive and faster than using the regex parameter with a value that does the same thing.
This parameter tells the API how to sort the results. You can pass one (and only one) of the following values with this parameter:
alpha
or alpha-asc
This is the default. Returns results in alphabetical order of the name.
alpha-desc
Returns results in reverse alphabetical order.
freq
or freq-asc
Returns results in order of the popularity of the name.
freq-desc
Returns results in descending order of the popularity of the name
length
Returns results in order of ascending length of the name. In other words, the shorter names will appear at the top of the results.
length-desc
Returns results such that the longer names appear near the top of the results.
This parameter tells the API to include names in the given gender categories only. You can provide multiple gender categories with this parameter. Just separate the categories with a comma. If you don’t provide this parameter, the API returns names without regard for gender category. You can use the following gender categories:
If you're looking for a name for a boy, you might want to look in the categories male, mostly-male, and gender neutral. The gender parameter would look like this in that case:
gender=male,mostly-male,gender-neutral
The API can often return thousands of results. For efficiency, the API breaks up the results into pages of 50 results each. You can use the page parameter to specify the page that you want. Page numbers begin at 1.
Although the API defaults to a page size of 50, you can specify a different page size using the page-size parameter.
The API provides the format parameter so that you can easily specify a format when calling the API from a browser. This allows for easier experimentation and troubleshooting. Allowed values for this parameter are text, and json. The default is text.
The minimum number of letters that the name you want should have. The default is to ignore the length of the name when choosing it. If you provide this parameter, the value must be a positive integer. If the max-length parameter is provided as well, then the value for the min-length parameter must be equal to or smaller than the value for the max-length parameter.
The maximum number of letters that the name you want should have. The default is to ignore the length of the name when choosing it. If you provide this parameter, the value must be a positive integer. If the min-length parameter is provided as well, then the value for the min-length parameter must be equal to or smaller than the value for the max-length parameter.