API Documentation

Behindthename.com's API is currently limited to three functions. Requests are made via HTTP with parameters passed in the query string. Results are returned in XML format.

In all cases an API access key must be used. Visit the API gateway to get your API key.

This will return information about a given name.

URL: http://www.behindthename.com/api/lookup.php

Parameters:

parameter	required	default	description
key	Y	(none)	your API access key
name	Y	(none)	the name to look up
exact	N	no	whether the name supplied is exact (meaning there are no missing diacritics)

Return value: name details in XML format

Example: http://www.behindthename.com/api/lookup.php?name=mary&key=#key#

This will return a random name.

URL: http://www.behindthename.com/api/random.php

Parameters:

parameter	required	default	description
key	Y	(none)	your API access key
gender	N	(none)	gender to restrict names to (eg. f for feminine names)
usage	N	(none)	usage to restrict names to (eg. eng for English-language names)
number	N	2	number of given names to return (max 6)
randomsurname	N	no	pass yes to generate a random surname as well

Return value: list of names in XML format

Example: http://www.behindthename.com/api/random.php?usage=ita&gender=f&key=#key#

This will return potential aliases for a given name. Please note - this function is only available by request.

URL: http://www.behindthename.com/api/related.php

Parameters:

parameter	required	default	description
key	Y	(none)	your API access key
name	Y	(none)	the name to look up
usage	N	(none)	usage to restrict aliases to (eg. eng for English-language names)
gender	N	(none)	gender to restrict aliases to (eg. f for feminine names)

Return value: list of names in XML format

Example: http://www.behindthename.com/api/related.php?name=richard&usage=eng&key=#key#