About
Documentation
GatewayBehindthename.com's API is currently limited to three functions. Requests are made via HTTPS with parameters passed in the query string. Results are returned in XML or JSON format.
In all cases an API access key must be used. Visit the API gateway to get your API key.
Look up
This will return information about a given name.
XML URL: https://www.behindthename.com/api/lookup.xml
JSON URL: https://www.behindthename.com/api/lookup.json
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
XML example: https://www.behindthename.com/api/lookup.xml?name=mary&key=#key#
JSON example: https://www.behindthename.com/api/lookup.json?name=mary&key=#key#
Random Name
This will return a random name.
XML URL: https://www.behindthename.com/api/random.xml
JSON URL: https://www.behindthename.com/api/random.json
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
XML example: https://www.behindthename.com/api/random.xml?usage=ita&gender=f&key=#key#
JSON example: https://www.behindthename.com/api/random.json?usage=ita&gender=f&key=#key#
Related Names
This will return potential aliases for a given name.
XML URL: https://www.behindthename.com/api/related.xml
JSON URL: https://www.behindthename.com/api/related.json
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
XML example: https://www.behindthename.com/api/related.xml?name=richard&usage=eng&key=#key#
JSON example: https://www.behindthename.com/api/related.json?name=richard&usage=eng&key=#key#