Getting started

The IBM Watson™ Personality Insights service allows applications to derive insights about personality characteristics from social media, enterprise data, or other digital communications. This cURL-based tutorial can help you get started quickly with the Personality Insights service. The examples show you how to call the service's POST profile method with different types of input and how to request different types of output and output formats. For more information, see Input: Requesting a profile and Output: Understanding a profile.

Prerequisites

Before starting the tutorial, make sure that you meet the following prerequisites:

  • Obtain Bluemix® credentials: For information about obtaining service credentials for working with a Watson service in Bluemix, see Service credentials for Watson services.
  • Install the cURL executable: cURL is a popular command-line tool for calling methods of HTTP interfaces. If you have not already downloaded the curl executable, you can install the version for your operating system from curl.haxx.se. You must install the version that supports the Secure Sockets Layer (SSL) protocol. Make sure to include the installed binary file on your PATH environment variable.

Basics

The examples share a few basic elements:

  • The examples use the cURL --user option to pass valid credentials for the Personality Insights service. In the examples, replace {username}:{password} with the values of the username and password from your service credentials. Note that you must use your service credentials, not your Bluemix ID and password.

  • The examples use the cURL --data-binary option to pass the contents of a file to the service. The option sends the content as it exists, with no additional processing. Each example sends one of two input files to the service for analysis:

    • A plain text file, profile.txt:

      Vice President Johnson, Mr. Speaker, Mr. Chief Justice, President Eisenhower, Vice President Nixon,
      President Truman, Reverend Clergy, fellow citizens:
      
      We observe today not a victory of party but a celebration of freedom -- symbolizing an end as well
      as a beginning -- signifying renewal as well as change. For I have sworn before you and Almighty
      God the same solemn oath our forbears prescribed nearly a century and three-quarters ago.
      
      . . .
      
    • A JSON file, profile.json:

      {
        "contentItems": [
          {
            "content": "Wow, I liked @TheRock before, now I really SEE how special he is. The daughter story was IT for me. So great! #MasterClass",
            "contenttype": "text/plain",
            "created": 1447639154000,
            "id": "666073008692314113",
            "language": "en"
          },
          {
            "content": ".@TheRock how did you Know to listen to your gut and Not go back to football? #Masterclass",
            "contenttype": "text/plain",
            "created": 1447638226000,
            "id": "666069114889179136",
            "language": "en"
          },
          . . .
        ]
      }
      
  • The examples use the version query parameter of the profile method to indicate the version of the interface to use for the request, 2016-10-20. For more information about specifying a version, see Interface version.

Plain text input with basic JSON output

The first example passes the plain text file profile.txt to the profile method and implicitly requests the default JSON response. The example uses the charset parameter with the Content-Type header to specify the character encoding of the input text.

curl -X POST --user {username}:{password}
--header "Content-Type: text/plain;charset=utf-8"
--data-binary "@<path>profile.txt"
"https://gateway.watsonplatform.net/personality-insights/api/v3/profile?version=2016-10-20"

The service returns a JSON profile that includes information about the Big Five personality, Needs, and Values characteristics for the author as inferred from the input text. The percentile returned for each characteristic reports the author's normalized score for that characteristic; the service computes the percentile by comparing the author's results with the results from a sample population. The service also reports basic metadata such as the number of words in the input, the language model with which the input was processed, and any warnings associated with the input.

{
  "word_count": 1365,
  "processed_language": "en",
  "personality": [
    {
      "trait_id": "big5_openness",
      "name": "Openness",
      "category": "personality",
      "percentile": 0.99708142449829,
      "children": [
        {
          "trait_id": "facet_adventurousness",
          "name": "Adventurousness",
          "category": "personality",
          "percentile": 0.78974535615104
        },
        . . .
      ]
    },
    {
      "trait_id": "big5_conscientiousness",
      "name": "Conscientiousness",
      "category": "personality",
      "percentile": 0.81001753184176,
      "raw_score": 0.66899984888815,
      "children": [
        {
          "trait_id": "facet_achievement_striving",
          "name": "Achievement striving",
          "category": "personality",
          "percentile": 0.84613299226628,
          "raw_score": 0.74240118454888
        },
        . . .
      ]
    },
    {
      "trait_id": "big5_extraversion",
      "name": "Extraversion",
      "category": "personality",
      "percentile": 0.085300585565483,
      "children": [
        {
          "trait_id": "facet_activity_level",
          "name": "Activity level",
          "category": "personality",
          "percentile": 0.96240163134159
        },
        . . .
      ]
    },
    {
      "trait_id": "big5_agreeableness",
      "name": "Agreeableness",
      "category": "personality",
      "percentile": 0.18753528603195,
      "children": [
        {
          "trait_id": "facet_altruism",
          "name": "Altruism",
          "category": "personality",
          "percentile": 0.97133020063318
        },
        . . .
      ]
    },
    {
      "trait_id": "big5_neuroticism",
      "name": "Emotional range",
      "category": "personality",
      "percentile": 0.94385641645805,
      "children": [
        {
          "trait_id": "facet_anger",
          "name": "Fiery",
          "category": "personality",
          "percentile": 0.013938100678609
        },
        . . .
      ]
    }
  ],
  "needs": [
    {
      "trait_id": "need_challenge",
      "name": "Challenge",
      "category": "needs",
      "percentile": 0.003254653691494
    },
    {
      "trait_id": "need_closeness",
      "name": "Closeness",
      "category": "needs",
      "percentile": 0.37022781101807
    },
    . . .
  ],
  "values": [
    {
      "trait_id": "value_conservation",
      "name": "Conservation",
      "category": "values",
      "percentile": 0.50659292186185
    },
    {
      "trait_id": "value_openness_to_change",
      "name": "Openness to change",
      "category": "values",
      "percentile": 0.62875169494626
    },
    . . .
  ],
  "warnings": []
}

JSON input with detailed JSON output

The second example passes JSON content from the file profile.json to the profile method, again accepting the default JSON response. The example specifies application/json for the Content-Type header; the charset parameter is not needed for JSON input. The example sets the consumption_preferences and raw_scores query parameters to true to request a more detailed analysis of the input.

curl -X POST --user {username}:{password}
--header "Content-Type: application/json"
--data-binary "@<path>profile.json"
"https://gateway.watsonplatform.net/personality-insights/api/v3/profile?version=2016-10-20&consumption_preferences=true&raw_scores=true"

The service returns a JSON profile that includes the characteristics and metadata returned with the first example. For each characteristic, the service also includes a raw_score, which represents the author's score for the characteristic based solely on the input text, without comparing the results to a sample population.

Because the input content includes timestamps, the service also reports behavioral characteristics. These are temporal characteristics that indicate the percentage of the content items that were created each day of the week and hour of the day. The service also reports a score for a collection of consumption preferences. For each preference, the service provides a score that indicates the author's likelihood to prefer different products, services, and activities based on the inferred characteristics.

{
  "word_count": 15223,
  "processed_language": "en",
  "personality": [
    {
      "trait_id": "big5_openness",
      "name": "Openness",
      "category": "personality",
      "percentile": 0.8011555009553,
      "raw_score": 0.77565404255038,
      "children": [
        . . .
      ]
    },
    {
      "trait_id": "big5_conscientiousness",
      "name": "Conscientiousness",
      "category": "personality",
      "percentile": 0.81001753184176,
      "raw_score": 0.66899984888815,
      "children": [
        . . .
      ]
    },
    {
      "trait_id": "big5_extraversion",
      "name": "Extraversion",
      "category": "personality",
      "percentile": 0.64980796071382,
      "raw_score": 0.56817738781166,
      "children": [
        . . .
      ]
    },
    {
      "trait_id": "big5_agreeableness",
      "name": "Agreeableness",
      "category": "personality",
      "percentile": 0.94786124793821,
      "raw_score": 0.80677815631809,
      "children": [
        . . .
      ]
    },
    {
      "trait_id": "big5_neuroticism",
      "name": "Emotional range",
      "category": "personality",
      "percentile": 0.5008224041628,
      "raw_score": 0.46748200007024,
      "children": [
        . . .
      ]
    }
  ],
  "needs": [
    {
      "trait_id": "need_challenge",
      "name": "Challenge",
      "category": "needs",
      "percentile": 0.67362332054511,
      "raw_score": 0.75196348037675
    },
    . . .
  ],
  "values": [
    {
      "trait_id": "value_conservation",
      "name": "Conservation",
      "category": "values",
      "percentile": 0.89268222856139,
      "raw_score": 0.72135308187423
    },
    . . .
  ],
  "behavior": [
    {
      "trait_id": "behavior_sunday",
      "name": "Sunday",
      "category": "behavior",
      "percentage": 0.21392532795156
    },
    . . .
    {
      "trait_id": "behavior_saturday",
      "name": "Saturday",
      "category": "behavior",
      "percentage": 0.077699293642785
    },
    {
      "trait_id": "behavior_0000",
      "name": "0:00 am",
      "category": "behavior",
      "percentage": 0.4561049445005
    },
    . . .
    {
      "trait_id": "behavior_2300",
      "name": "11:00 pm",
      "category": "behavior",
      "percentage": 0.12310797174571
    }
  ],
  "consumption_preferences": [
    {
      "consumption_preference_category_id": "consumption_preferences_shopping",
      "name": "Purchasing Preferences",
      "consumption_preferences": [
        {
          "consumption_preference_id": "consumption_preferences_automobile_ownership_cost",
          "name": "Likely to be sensitive to ownership cost when buying automobiles",
          "score": 0
        },
        . . .
      ]
    },
    {
      "consumption_preference_category_id": "consumption_preferences_health_and_activity",
      "name": "Health & Activity Preferences",
      "consumption_preferences": [
        {
          "consumption_preference_id": "consumption_preferences_eat_out",
          "name": "Likely to eat out frequently",
          "score": 1
        },
        . . .
      ]
    },
    {
      "consumption_preference_category_id": "consumption_preferences_environmental_concern",
      "name": "Environmental Concern Preferences",
      "consumption_preferences": [
        {
          "consumption_preference_id": "consumption_preferences_concerned_environment",
          "name": "Likely to be concerned about the environment",
          "score": 0
        }
      ]
    },
    {
      "consumption_preference_category_id": "consumption_preferences_entrepreneurship",
      "name": "Entrepreneurship Preferences",
      "consumption_preferences": [
        {
          "consumption_preference_id": "consumption_preferences_start_business",
          "name": "Likely to consider starting a business in next few years",
          "score": 1
        }
      ]
    },
    {
      "consumption_preference_category_id": "consumption_preferences_movie",
      "name": "Movie Preferences",
      "consumption_preferences": [
        {
          "consumption_preference_id": "consumption_preferences_movie_romance",
          "name": "Likely to like romance movies",
          "score": 1
        },
        . . .
      ]
    },
    {
      "consumption_preference_category_id": "consumption_preferences_music",
      "name": "Music Preferences",
      "consumption_preferences": [
        {
          "consumption_preference_id": "consumption_preferences_music_rap",
          "name": "Likely to like rap music",
          "score": 1
        },
        . . .
      ]
    },
    {
      "consumption_preference_category_id": "consumption_preferences_reading",
      "name": "Reading Preferences",
      "consumption_preferences": [
        {
          "consumption_preference_id": "consumption_preferences_read_frequency",
          "name": "Likely to read often",
          "score": 0
        },
        . . .
      ]
    },
    {
      "consumption_preference_category_id": "consumption_preferences_volunteering",
      "name": "Volunteering Preferences",
      "consumption_preferences": [
        {
          "consumption_preference_id": "consumption_preferences_volunteer",
          "name": "Likely to volunteer for social causes",
          "score": 0
        },
        . . .
      ]
    }
  ],
  "warnings": []
}

JSON input with detailed CSV output

The third example is very similar to the second: it passes the same JSON content and requests the same results. But this example specifies text/csv for the Accept header to request the response in comma-separated values (CSV) format, using the --output option of the cURL command to direct the results to a file named profile.csv. The example sets the csv_headers query parameter to true to request that column headers be returned with the output.

curl -X POST --user {username}:{password}
--header "Content-Type: application/json"
--header "Accept: text/csv"
--data-binary "@<path>profile.json"
--output profile.csv
"https://gateway.watsonplatform.net/personality-insights/api/v3/profile?version=2016-10-20&consumption_preferences=true&raw_scores=true&csv_headers=true"

For a detailed description of the CSV response and headers, see CSV response content.