Utilities API Documentation

This API contains tools used for data normalization and deduction.

Utilities

Authentication

You need to have a working Rapleaf Personalization API key to make queries against the Utilities API. Sign up for a Rapleaf API Key. There are two ways to pass your key in a request:

  • Append api_key=[YOUR_API_KEY] to your request, like so:

    http://api.rapleaf.com/v4/util/name_deducer/dummy@rapleaf.com?api_key=[YOUR_API_KEY]
  • Set the Authentication parameter in your request header to the value of your API key.

Name to Gender

This function takes a name and returns a gender, with a likelihood percentage.

http://api.rapleaf.com/v4/util/name_to_gender/<name>?api_key=[YOUR_API_KEY]
  • Name: The name you wish to search
  • The name must be URL encoded.
    • For instance, "dum+my" would be encoded as "dum%2Bmy"
    Example Response
    "answer" : {
      "gender" : "Male",
      "likelihood" : "0.80"
    }

    Note: Gender can be "male", "female" or "unknown"

Name Deducer

This function deduces a name from an email address or username.

http://api.rapleaf.com/v4/util/name_deducer/<email>?api_key=[YOUR_API_KEY]
  • Email: The email you wish to search
  • The email must be URL encoded.
    • For instance, "dum+my@rapleaf.com" would be encoded as "dum%2Bmy%40rapleaf.com"
    Example Response
    "answer" : {
      "first" : "Bob",
      "last" : "Dole",
      "middle" : "J",
      "prefix" : null,
      "suffix" : null
    }
    

Name Normalization

This function normalizes part of name for a name string.

http://api.rapleaf.com/v4/util/name_normalizer/<name>?api_key=[YOUR_API_KEY]
  • Name: The name you wish to search
  • The name must be URL encoded.
    • For instance, "dum+my" would be encoded as "dum%2Bmy"
    Example Response
    "answer" : {
      "first" : "Bob",
      "last" : "Dole",
      "middle" : "J",
      "prefix" : null,
      "suffix" : null
    }
    

Requests and Responses

Requests

The API can be queried with HTTP GET requests.

GET http://api.rapleaf.com/v4/util/name_to_gender/james?api_key=[YOUR_API_KEY] HTTP/1.1

Responses

Responses are in json format (see each api call for specific schema) and can return the following response codes:

HTTP Status Codes
Status Code Description
200 OK Request processed successfully.
400 Bad Request Some part of the request was invalid. The response body will give further explanation as to what the problem is.
403 Forbidden Your query limit has been exceeded, or the API key is not associated
with any available response section.

Contact developer@rapleaf.com
if you would like to increase your limit or add available response sections.
500 Internal Server Error There was an unexpected error on our server.
This should be very rare and if you see it please contact
developer@rapleaf.com.

Note: This list does not cover all possible HTTP Status Codes that could be returned,
only those returned specifically from our API. For example, if the request cannot make
it to our API you will likely get a "503 Service Unavailable" response.
With this in mind do not code exclusively to handle the response codes listed above.

Help

You can learn more about the basic principles of REST on Wikipedia.

For a more in depth understanding we recommend RESTful Web Services by Leonard Richardson and Sam Ruby.

Please email questions to Rapleaf Developer Support.

1,000 free queries. Get Your API Key