Technical Documentation

Integration Overview

In order to integrate with the API, one needs to:

  • Obtain a relevant digital footprint (i.e. Facebook likes)
  • Authenticate with Prediction API to obtain an access token
  • Use the access token to call prediction method relevant to the type of footprint (i.e. /like_ids for Facebook likes)

Example scenario: using Facebook Application to obtain like ids and make prediction

  • Create Facebook Application
  • Use Facebook SDK for the language of your choice in order to:
  • Make a call to Prediction API /authendpoint to obtain the access token.
  • With access token call Prediction API /like_ids endpoint to get prediction results.

Best Practices

  • Access token returned by /auth endpoint should be re-used for subsequent calls. There's absolutely no need to call for it every time the prediction is made as it only slows things down.
  • It's possible (although rare) for the access token to expire before the expected expiration time. Whenever calling prediction methods one should handle 403 response by obtaining a fresh one.
  • No prediction is a valid outcome when there's not enough digital footprint to predict anything, so this needs to be handled by your application.
  • Use traits parameter to get predictions only relevant to you. This speeds up things considerably.
  • Don't attempt to communicate with Prediction API from client side, but rather use your server-side backend. It will not be allowed by client's browser anyway and also puts your api key at risk of being exposed to the public.

RESTful API

Authentication

To authenticate with the service one needs to pass customer_id and api_key obtained during registration and obtain a valid auth token.

Validity of the token is limited to approximately 1 hour. You should try not to repeat this call before every prediction - rather only when you get token invalid response (code 403) after prediction call. Don't take timestamp provided for granted as the token sometimes might expire earlier.

Since this call contains your api_key you should consider security, i.e. this should not be attempted on client side.

POST https://api.applymagicsauce.com/auth

Request headers:

Content-type: application/json
Accept: application/json

Request body:

{
    "customer_id": [integer],
    "api_key": "[string]"
}

Expected response body:

{
  "token": "[your auth token, string]",
  "customer_id”: [your customer id],
  "expires": [timestamp when the token expires, integer],
  "permissions": [any special permissions granted if applicable, list of strings],
  "usage_limits":[
    {
      "method": "[prediction method, string]",
      "callsLimit": [call limit per month, integer],
      "callsAvailable": [calls left in current period, integer],
      "callsAvailableSince": [date and time of last reset, unix timestamp ms],
      "callsRenewal": [whether calls renew after period of time, boolean],
      "callsRenewalDays": [call renewal period in days, integer]
    },

    ...
  ]
}

Possible response status codes:

  • 200 - OK, authenticated
  • 400 - request was bad, see the returned message
  • 403 - authentication failure
  • 404 - check the url you’re sending the request to
  • 500 - Error on the API side (temporary not available, maintenance, etc.)

Getting a prediction from Facebook Like IDS

It is advisable to use traits parameter to limit the number of traits predicted as it will improve overall performance.

Clients should expect and handle 'no prediction' outcome (code 204), as a situation may occur when provided like ids were not sufficient to make an accurate prediction.

POST https://api.applymagicsauce.com/like_ids?traits=...

Request headers:

X-Auth-Token: [token obtained from /auth call]
Content-type: application/json
Accept: application/json

Request URL parameters:

  • traits=trait1,trait2,... - comma-separated list of traits to predict (eg. BIG5_Openess, Female). Optional, all traits are returned by default, but limiting increases performance.
  • interpretations=true|false - whether to include additional interpretations of the prediction result. Optional, not returned by default.
  • contributors=true|false - whether to include information about contributors. Optional, not returned by default.

Request body:

JSON array of like ids (strings).

["1","2","3","4","5","6"]

Expected response body:

{
    "input_used": [number of like ids used in the prediction],

    "predictions": [
        {
            "trait": "[trait name]",
            "value": [predicted value, float]
        },

        ...

    ],
    "interpretations": [
        {
            "trait": "[trait name]",
            "value": [intepreted value, any]
        },

        ...
    ]

    "contributors": [
        {
            "trait": "[trait name]",
            "positive": [list of like ids that are influencing prediction in positive direction, strongest come first]
            "negative": [list of like ids that are influencing prediction in negative direction, strongest come first]
        },

        ...
    ]
}

Possible response status codes:

  • 200 - response should contain prediction
  • 204 - no prediction could be made based on like ids provided. This is a valid outcome, not an error.
  • 400 - check the request, see the returned message for errors
  • 403 - access token problem, see the returned message for details
  • 404 - check the url you’re sending the request to
  • 429 - usage limit was exceeded for your account, verify that the message is present
  • 500 - Error on the API side (temporary not available, maintenance, etc.)

Getting a prediction from text

It is advisable to use traits parameter to limit the number of traits predicted as it will improve overall performance.

POST https://api.applymagicsauce.com/text?traits=...

Request headers:

X-Auth-Token: [token obtained from /auth call]
Content-type: application/json
Accept: application/json

Request URL parameters:

  • source=WEBSITE|EMAIL|BROCHURE|STATUS_UPDATE|TWEET|CV|OTHER - type of the text used to make a prediction. Required, results may differ if source is not set correctly.
  • traits=trait1,trait2,... - comma-separated list of traits to predict (eg. BIG5_Openess, Female). Optional, all traits are returned by default, but limiting increases performance.
  • interpretations=true|false - whether to include additional interpretations of the prediction result. Optional, not returned by default.

Request body:

Text to predict from, for non ASCII characters UTF-8 encoding is expected.

Expected response body:

{
    "input_used": [currently it's a size of text sent to make a prediction],

    "predictions": [
        {
            "trait": "[trait name]",
            "value": [predicted value, float]
        },

        ...

    ],
    "interpretations": [
        {
            "trait": "[trait name]",
            "value": [intepreted value, any]
        },

        ...
    ]
}

Possible response status codes:

  • 200 - response should contain prediction
  • 400 - check the request, see the returned message for errors
  • 403 - access token problem, see the returned message for details
  • 404 - check the url you’re sending the request to
  • 429 - usage limit was exceeded for your account, verify that the message is present
  • 500 - Error on the API side (temporary not available, maintenance, etc.)

Example Client Code

We are maintaining Example Prediction API repository on GitHub.

You are welcome to take a look or use it. It will be updated with more programming languages if there's sufficient demand for it.

Changelog

  • 2.4.x

    • Deprecated http://api-v2.applymagicsauce.com, it will keep working for now, but clients are encouraged to switch to https://api.applymagicsauce.com
    • The following traits: Gay, Lesbian now require special permission granted and ethic approval in order to be used by clients
    • The /auth endpoint returns more information regarding usage limits and method calls expiration