Frequently Asked Questions

General questions

Should I register to use the API?

Only if you plan to create an application that will use the API. There's no registration required just to use the demo on this website.

'I work for X company and want to use your API for internal research but I don't plan to make money from it yet...'

Apply Magic Sauce API is for non-profit academic or educational projects only, so it is unlikely that a company project would qualify for authorisation to use our models. However, there are many other ways to potentially collaborate, like building new models from your data, so please get in touch describing your proposed project and we'll see what we can do.

I'm conducting academic research, can I use the API for my project?

Absolutely, please sign up and tell us more about your project. We want to know that your participants or users have consented, or will consent, to their data being used for the purpose of prediction. We may also ask for additional information before activating your account, such as asking to see a copy of the consent form shown to your participants and a copy of your ethics approval. We can also offer advice on how to design your study or application based on our research experience that you may find useful, so don't be shy to get in touch.

I've registered, where do I log in?

You don't. The purpose of the registration is to get a Customer ID and API key to authenticate calls made from your application. If you haven't saved your access credentials when you registered you can use Account Information Reminder to see them again.

I've signed up, but the API key does not work...

There's an approval process involved before your API key is activated. Please note that this is a free service without dedicated staff to handle the process, so please allow some time for the process to be completed.

Does Apply Magic Sauce have anything to do with Cambridge Analytica, Facebook or IBM?

Absolutely not. Please read this statement from the Psychometrics Centre for further detail. We have been publishing papers since 2013 that warn against exactly the kinds of techniques made infamous by Cambridge Analytica, and we continue to raise awareness of these issues through the Apply Magic Sauce project. We have no relationship with Facebook nor have we ever received or shared any data from them - all our data was collected via opt in from participants directly. We also have nothing to do with IBM Watson.

Demo prediction on this website

When will the Facebook log in button work?

This is up to Facebook so we don't know, sorry. You can use the Data Portability Tool to generate a prediction from a download of your Facebook data instead of logging in. Please note that the API is unaffected by this and you can still make Facebook predictions with your own Facebook app.

How do I get a prediction from a download of my Facebook or Twitter data?

Check out the tutorials showing you how to get a copy of your social media data, and how to analyse those files using our Data Portability tool and obtain a prediction without having to log in

I would like to disconnect my Facebook or Twitter account after using demo prediction

Any access granted to social media accounts is temporary and within the scope of permissions granted.

That means we read your data, but it doesn't give us the ability to access you entire social media account nor make any changes to it. Moreover, our read-only access is valid only for a period of time. We currently automatically remove any access tokens after 5 minutes. After that time we're technically prevented from any further access without the user re-connecting.

You can also expire any existing tokens by doing it yourself. This can be accomplished by:

Please remove all of my personal data, such as my email or my name

The demo prediction does not currently store any personally identifiable information, whether that be your name or email.

Please use My Data @ Apply Magic Sauce Tool to learn what is stored by us and for what purpose. The tool allows you to view and, if you wish, delete all the data collected by us during a session of you using the demo. We do not collect any data other than what you opt in to submit by using the demo.

If you signed up to use our API then we notified that we would use your email to communicate with you regarding your use of the API. If you opted in to marketing emails then you can opt out of these by clicking the Unsubscribe link in any email sent by us. For anything else, please contact us.

The predictions you have made about me are inaccurate, it says I'm [...], while in fact I know I'm [...]

Like any psychometric test, the results produced may not always correspond with your own estimation of your self. Our tool is intended to help people understand that your digital footprint contains psychological information, and that anyone with access to view your online persona has the ability to form judgments about you that go deeper than the surface. It's not just that you liked or clicked something, it's that liking or clicking a certain pattern of things reveals intimate attributes that you might not have intended to share. We hope that using our prediction enables a moment of self-reflection about how much you share by using the internet, and a moment of realisation that your data has value so you should think carefully about which corporations you allow to use it for their own ends.

In other words, we hope that enabling citizens to better understand the psychological significance of their behaviour on social media can make them better equipped to interpret the potential impact of this behaviour on themselves and on others.

API

Can I send you a user's Facebook ID, Twitter handle or email address to get a prediction?

No. Our algorithms take like ids, names and text written by the user as an input and are provided anonymously. It is your responsibility to obtain the digital footprint of the user or participant for whom you are providing a prediction using our API, and to do so in an ethical manner that follows the need to obtain specific and informed consent from the data subject. .

Getting an empty response (status code 204) from API method

This is a normal response, indicating that the digital footprint provided as an input is insufficient to make an 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 a prediction:

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

Getting 429 response from API method

This indicates that your monthly usage limit was exceeded for your API account. Please contact us to discuss whether it can be increased and how this could help your research project.

How can I know how much API calls I have left?

While we don't currently offer a dedicated customer panel, they are returned every time from /auth method of the API. Please see the relevant part in Technical Documentation

I cannot connect to the API from my client-side JavaScript application

This is because browsers prevent making request across different domains for security reasons.

If we'd allow for these requests anyways, i.e. by setting Cross-Origin Resource Sharing (CORS) policy, we would encourage leaking api keys to the public. It's in your best interest to keep it secret from anyone else.

How I'm supposed to know my application gets 'good' predictions?

Just try the demo on this website and compare the results. If they significantly differ, it means something is wrong with your application.

The most common cause for it was customers not getting all of the user's likes from Facebook, because Facebook returns them in pages, 25 per page. Even with likes per page limit increased it takes multiple calls to get all of them. Please refer to Facebook Graph API documentation for details.

The demo here is just an ordinary client application and it's not treated differently, except it has all available permissions to use sensitive or experimental traits.

API Documentation

Introduction

Apply Magic Sauce (AMS) is a service that predicts users psycho-demographic traits based on their digital footprints.

Using the API we make predictions available for:

  • Personality
  • Satisfaction with life
  • Intelligence
  • Age
  • Gender
  • Interest in given area
  • Political views
  • Religion
  • Relationship status

We can also provide additional interpretation of the prediction results, such as:

  • Leadership potential
  • Jungian personality type

Predicted Traits

From Like IDs and Like Names

Linear Traits

  • The scores are expressed as percentiles (ranging from 0 to 1) relative to the general population. A percentile indicates the position of a given score in the context of other scores. For example, the Extraversion score of .2 (or the 20th percentile) indicates that .2 (or 20%) of the people in general population have a lower score and .8 (80%) have a higher score. Score of .5 (or 50th percentile) indicates an average score.
  • Prediction accuracy is expressed as the correlation between the AMS prediction and the actual score. Accuracy of 1 indicates a perfect accuracy, whereas the accuracy of 0 indicates a random guess.
  • If there are more traits in a group, using the group name as a Trait ID will calculate predictions for all traits in the group. E.g. BIG5, Religion, Politics.
Trait IDDescriptionPrediction Accuracy (correlation)
  • BIG5
  • BIG5_Openness
  • BIG5_Conscientiousness
  • BIG5_Extraversion
  • BIG5_Agreeableness
  • BIG5_Neuroticism

Original scores estimated using 100-item long International Personality Item Pool Five Factor Model questionnaire, arguably the most popular personality questionnaire used at the moment.

The model was built (and the accuracy validated) using a sample of 260,000 participants.

Between .35 and .50

(comparable with a short BIG 5 personality questionnaire).

  • Satisfaction_Life

Original scores estimated using Diener's Satisfaction With Life Scale. The model was built (and the accuracy validated) using a sample of 55,000 people.

.17

The test-retest reliability of Diener’s SWL scale is .44

  • Intelligence

Original scores estimated using our proxy for Raven's Standard Progressive Matrices - one of the most popular general intelligence questionnaires The model was built (and the accuracy validated) using a sample of 39,000 participants.

Note that the percentile scores can be easily be translated into the IQ scale. For example, a score of .5 equals IQ100, a score of .84 equals IQ115, and a score of .16 equals IQ85.

.47
  • Age
Reported as an actual age and not a percentile. We aim to predict the user's real age, but if they have mature or immature Likes on Facebook, then we may be out by a few years. .75

Categories

  • The scores are expressed as probabilities (ranging from 0 to 1). For example the score of .2 for trait female, indicates that given user is female with 20% of probability and male with 80% of probability.
  • Prediction accuracy is expressed as the Area Under the receiver operating Curve (AUC) which is an equivalent of the probability of correctly classifying two randomly selected users one from each class, such as males and females. AUC of 1 indicates a perfect accuracy, whereas AUC of .5 indicates a random guess.
  • If there are more traits in a group, using the group name as a Trait ID will calculate predictions for all traits in the group. E.g. BIG5, Religion, Politics.
Trait IDDescriptionPrediction Accuracy (AUC)
  • Female

Probability of being a female. Importantly, it is a reversed probability of being male. This means that the probability of being male equals to (1-Female). The model was built (and the accuracy validated) using a sample of 243,000 people.

For example, the score of .2 indicates that given user has 20% probability of being female and 80% probability of being male.

.93

This means that in 93 out of 100 cases the prediction matches the individual’s self-reported gender

  • Concentration
  • Concentration_Art
  • Concentration_Biology
  • Concentration_Business
  • Concentration_IT
  • Concentration_Education
  • Concentration_Engineering
  • Concentration_Journalism
  • Concentration_Finance
  • Concentration_History
  • Concentration_Law
  • Concentration_Nursing
  • Concentration_Psychology

Probability of having an interest in a given area. For a given user the predictions sum up to 1.

Note that the 12 concentrations are among the most popular and have differing prevalence in the general population. The model was built (and the accuracy validated) using a sample of 33,000 people and their concentration reported on Facebook profile. Note that a higher accuracy score can be achieved when considering 2 or more most probable conentrations selected for a given user.

.72
  • Politics
  • Politics_Conservative
  • Politics_Liberal
  • Politics_Uninvolved
  • Politics_Libertanian

Probability of exhibiting a preference for a given political view. For a given user the predictions sum up to 1. The model was built (and the accuracy validated) using a sample of 73,000 people and their political views reported on Facebook profile.

.79
  • Religion
  • Religion_None
  • Religion_Christian_Other
  • Religion_Catholic
  • Religion_Jewish
  • Religion_Lutheran
  • Religion_Mormon

Probability of having a given religious view. For a given user the predictions sum up to 1. The range of religious views for which predictions are made is based on the sample used to train the algorithm.

Category "None" includes atheists, agnostics, pastafarians and jedi. "Christian Other" includes several christian denominations. Note that a higher accuracy score can be achieved when considering 2 or more of the most probable concentrations selected for a given user.

.76
  • Relationship
  • Relationship_None
  • Relationship_Yes
  • Relationship_Married
Probability of being in a relationship. For a given user the predictions sum up to 1. .67

From text

Linear Traits

  • The scores are expressed as percentiles (ranging from 0 to 1) relative to the general population. A percentile indicates the position of a given score in the context of other scores. For example, the Extraversion score of .2 (or the 20th percentile) indicates that .2 (or 20%) of the people in general population have a lower score and .8 (80%) have a higher score. Score of .5 (or 50th percentile) indicates an average score.
  • If there are more traits in a group, using the group name as a Trait ID will calculate predictions for all traits in the group. E.g. BIG5, Religion, Politics.
Trait IDDescriptionPrediction Accuracy (correlation)
  • BIG5
  • BIG5_Openness
  • BIG5_Conscientiousness
  • BIG5_Extraversion
  • BIG5_Agreeableness
  • BIG5_Neuroticism

Original scores estimated using 100-item long International Personality Item Pool Five Factor Model questionnaire or 336-item IPIP proxies for Costa and McCrae’s NEO-PI-R domains.

The model was built (and the accuracy validated) using a sample of 14 million status updates from 69,000 Facebook users.

  • Openness = .41
  • Conscientiousness = .4
  • Extraversion = .3
  • Agreeableness = .23
  • Neuroticism = .31
  • Age
 Reported as an actual age and not a percentile..76
  • Female

Probability of being a female. Importantly, it is a reversed probability of being male. This means that the probability of being male equals to (1-Female).

For example, the score of .2 indicates that given user has 20% probability of being female and 80% probability of being male.

.78

This means that in 78 out of 100 cases the prediction matches the individual’s self-reported gender

References

  1. Goldberg, L. R. (1999). A broad-bandwidth, public domain, personality inventory measuring the lower-level facets of several five-factor models. In I. Mervielde, I. Deary, F. De Fruyt, & F. Ostendorf (Eds.), Personality Psychology in Europe, 7: 7-28. Tilburg, The Netherlands: Tilburg University Press
  2. Diener, E. D., et al. (1985) "The satisfaction with life scale." Journal of personality assessment 49.1: 71-75.

Interpretations

Interpretations are additional traits derived from prediction results regardless of the prediction method used. They can appear alongside prediction results when requested.

From personality

These are available when prediction was made about personality (BIG5)

Trait ID Description
  • Leadership

Prediction is based on the Psychometrics Centre’s multidimensional study of 2,019 entrepreneurs and employees from the technology, retail and finance sectors around the world.

Leadership potential is a compound of the BIG5 personality traits exhibited by business owners, as distinguished from employees.

  • Jungian

Jungian type is mapped from BIG5 personality based on the univariate correlations reported in McCrae, R. & Costa, P. (1989).

References

  1. McCrae, R. & Costa, P. (1989). Reinterpretting the Myers-Briggs Type Indicator from the perspective of the five-factor model of personality. Journal of Personality 57

Contributors

Contributors tell precisely what part of digital footprint that was provided contributed to given prediction results most significantly. This information can appear alongside prediction results when requested.

Like IDs

List of 3 like ids that were most strongly influencing the prediction in either direction is provided. The list is sorted by 'strength', so the strongest contributors appear first in the list.

Like Names

Same as for Like IDs, except it's a list of 3 like names.

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]",
    "calls_limit": [call limit per month, integer],
    "calls_available": [calls left in current period, integer],
    "calls_available_since": [date and time of last reset, unix timestamp ms],
    "calls_renewal": [whether calls renew after period of time, boolean],
    "calls_renewal_days": [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 names 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 liked Facebook pages

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_names?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 names 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 names that are influencing prediction in positive direction, strongest come first]
          "negative": [list of names 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:

  • 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.6.x

    • Introduced /like_names prediction method.
    • Removed source request parameter from /text prediction method. It will be ignored if present.

  • 2.5.x

    • Any userId parameters are ignored.

  • 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