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: 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:
    • Allow users to authenticate, asking for user_likes permission.
    • Make a call to Facebook Graph API to obtain the list of like ids. Likes returned by Facebook in this call are paginated (around 25 per page by default), so it's possible it will need multiple calls to get all of it.
  • Make a call to Prediction API /authendpoint to obtain the access token. Store the token for further use if you can.
  • 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. When 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.

Troubleshooting / FAQ

Getting 204 response from prediction method

This is a normal response, indicating that digital footprint provided as an input is insufficient to make accurate prediction.

For /like_ids method we currently need at least 10 from which at least 5 should be recognised as 'predictive'. The solution to this is to send us more like ids to increase the likelihood of success. Though of course some Facebook users can have unpopular, not predictive, or just not enough likes altogether.

For testing purposes you can try the following like ids that are know to yield prediction:

[5845317146,6460713406,22404294985,35312278675,105930651606,171605907303,199592894970,274598553922,340368556015,100270610030980]

Getting 429 response from prediction method

This is indicating that your monthly usage limit was exceeded for your Prediction API account. Consider contacting us to talk about increasing it.

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 http://api-v2.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]",
    "expires": [timestamp when the token expires, 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 http://api-v2.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 object containing array if like ids (either strings or integers).

[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]
    },

    ...

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

    ...
    ]

    "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 http://api-v2.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]
    },

    ...

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

    ...
    ]
}

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.)