Curl Node Java

Personality Insights

API Reference
IBM Watson Personality Insights API reference

Introduction

The IBM Watson™ Personality Insights service enables applications to derive insights from social media, enterprise data, or other digital communications. The service uses linguistic analytics to infer individuals' intrinsic personality characteristics, including Big Five, Needs, and Values, from digital communications such as email, text messages, tweets, and forum posts. The service can automatically infer, from potentially noisy social media, portraits of individuals that reflect their personality characteristics.

API endpoint


https://gateway.watsonplatform.net/personality-insights/api

The code examples on this tab use the client-side library that is provided for Node.js rather than the REST calls.

Node


npm install watson-developer-cloud

The code examples on this tab use the client-side library that is provided for Java rather than the REST calls.

Maven


<dependency>
  <groupId>com.ibm.watson.developer_cloud</groupId>
  <artifactId>java-wrapper</artifactId>
  <version>2.10.0</version>
</dependency>

Gradle


compile 'com.ibm.watson.developer_cloud:java-sdk:2.10.0'

More information

An interactive tool for testing calls to the API and viewing live responses from the service is available in the Personality Insights API explorer.

Descriptions of Node classes referred to in this reference are available in the Node documentation for the Watson Developer Cloud Node.js SDK.

Descriptions of Java classes referred to in this reference are available in the Javadoc for the Watson Developer Cloud Java SDK.

Authentication

You authenticate to the Personality Insights API by providing the username and password that are provided in the service credentials for the service instance that you want to use. The API uses HTTP basic authentication.

After creating an instance of the Personality Insights service, select Service Credentials from the navigation on the left side of its dashboard page to see the username and password that are associated with the instance. For more information, see Obtaining credentials for Watson services.

Applications can also use tokens to establish authenticated communications with Watson services without embedding their service credentials in every call. You write an authentication proxy in IBM Cloud to obtain a token for your client application, which can then use the token to call the service directly. You use your service credentials to obtain a token for that service. For more information, see Using tokens with Watson services.

Replace {username} and {password} with your service credentials.


curl -u "{username}":"{password}"
"https://gateway.watsonplatform.net/personality-insights/api/v2/{method}"

var watson = require('watson-developer-cloud');
var personality_insights = watson.personality_insights({
  username: '{username}',
  password: '{password}',
  version: 'v2'
});

PersonalityInsights service = new PersonalityInsights();
service.setUsernameAndPassword("{username}", "{password}");

Request logging

By default, IBM Cloud collects data from all requests and uses the data to improve the Watson services. If you do not want to share your data, set the header parameter X-Watson-Learning-Opt-Out to true for each request. Data is collected for any request that omits this header. For more information, see Controlling request logging for Watson services.

Response handling

The Personality Insights service uses standard HTTP response codes to indicate whether a method completed successfully. A 200-level response always indicates success. A 400-level response indicates some sort of failure. And a 500-level response typically indicates an internal system error.

Equivalent exceptions are returned by the Java SDK. The exceptions typically include the error message returned by the service.

Response codes

Status Description
200 OK The call succeeded.
400 Bad Request The request JSON is not properly formatted, fewer than 100 words are provided, or the requested language is not supported.
401 Unauthorized Access is denied due to invalid service credentials.
429 Too Many Requests The service is currently processing too many requests for the content language. Wait a short time and try the request again. If you are submitting many requests for the language, consider throttling the rate at which you submit requests.
500 Server Error The service encountered an internal server error.
504 Gateway Timeout The request timed out or took too long to process. Wait a short time and try the request again. If the input contained a large number of words (for example, more than 20,000), consider reducing the number of words while maintaining the guidelines for meaningful input.

Exceptions thrown

Exception Description
IllegalArgumentException An illegal argument was passed to a method that accepts one or more arguments.
BadRequestException A required input parameter is null or a specified input parameter or header value is invalid or not supported. (HTTP response code 400.)
UnauthorizedException Access is denied due to invalid service credentials. (HTTP response code 401.)
TooManyRequestsException The service is currently processing too many requests for the content language. Wait a short time and try the request again. If you are submitting many requests for the language, consider throttling the rate at which you submit requests. (HTTP response code 429.)
InternalServerErrorException The service experienced an internal error. (HTTP response code 500.)
ServiceResponseException The request timed out or took too long to process. Wait a short time and try the request again. If the input contained a large number of words (for example, more than 20,000), consider reducing the number of words while maintaining the guidelines for meaningful input. (HTTP status code 504.)

Error format

Name Description
code integer HTTP status code.
error string Description of the error.
help string A URL to documentation explaining the cause and possibly solutions for the error.

Example error


{
  "code": 400,
  "error": "No text provided"
}

Methods

Get profile

Generates a personality profile for the author of the input text. The service accepts a maximum of 20 MB of input data. You can provide plain text, HTML, or JSON input. The service returns output in JSON format by default, but you can request the output in CSV format. Use the text parameter to provide plain text or HTML input; provide JSON input as a contentItems object. The service returns output in JSON format by default, but you can request the output in CSV format. You can provide plain text as input with any of the methods; you can provide HTML or JSON input only with the methods that accept a Java ProfileOptions object. The getProfile methods return output in JSON format; the getProfileAsCSV method returns output in CSV format.


POST /v2/profile

profile(params, callback())

Profile getProfile(String text)
Profile getProfile(ProfileOptions options)
String getProfileAsCSV(ProfileOptions options, Boolean includeHeaders)

Request

Parameter Type Description
Content-Type header string The content type of the request:
  • text/plain for plain text (the default)
  • text/html for text in HTML
  • application/json for text in JSON format
When specifying a content type of plain text or HTML, include the charset parameter to indicate the character encoding of the input text; for example, Content-Type: text/plain; charset=utf-8. Per the JSON specification, the default character encoding for JSON content is effectively always UTF-8; per the HTTP specification, the default encoding for plain text and HTML is ISO-8859-1 (effectively, the ASCII character set).
Content-Language header string The language of the input text for the request:
  • ar (Arabic)
  • en (English, the default)
  • es (Spanish)
  • ja (Japanese)
Regional variants are treated as their parent language; for example, en-US is interpreted as en. The effect of the Content-Language header depends on the Content-Type header:
  • When Content-Type is text/plain or text/html, Content-Language is the only way to specify the language.
  • When Content-Type is application/json, Content-Language overrides a language specified with the language parameter of a ContentItem object; content items that specify a different language are ignored. Omit this header to base the language on the specification of the content items.
You can specify any combination of languages for Content-Language and Accept-Language.
Accept header string The desired content type of the response:
  • application/json for JSON output (the default)
  • text/csv for CSV output
CSV output includes a fixed number of columns and optional headers.
Accept-Language header string The desired language of the response:
  • ar (Arabic)
  • de (German)
  • en (English, the default)
  • es (Spanish)
  • fr (French)
  • it (Italian)
  • ja (Japanese)
  • ko (Korean)
  • pt-br (Brazilian Portuguese)
  • zh-cn (Simplified Chinese)
  • zh-tw (Traditional Chinese)
Regional variants are treated as their parent language; for example, en-US is interpreted as en. You can specify any combination of languages for the input text and the response.
include_raw query boolean Indicates whether a raw score and a raw sampling error in addition to normalized statistics are to be returned for each characteristic. Raw scores are not compared with a sample population. If true, raw statistics are returned; if false (the default), only normalized percentiles and sampling errors are returned.
headers query boolean Indicates whether column labels are returned with a CSV response. If true, column labels are returned; if false (the default), they are not. Applies only when the Accept header is set to text/csv.
body body string A maximum of 20 MB of content to be analyzed. For JSON input, provide an object of type ContentListContainer.
Parameter Type Description
text string The text to be analyzed, plain text (the default) or HTML. You must specify either the text or contentItems parameter.
contentItems object A ContentListContainer object that provides a maximum of 20 MB of JSON content to be analyzed.
content_type string If you specify the text parameter, the content type of the text:
  • text/plain for plain text (the default)
  • text/html for text in HTML
Include the charset parameter to indicate the character encoding of the input text; for example, Content-Type: text/plain; charset=utf-8. Per the HTTP specification, the default encoding for plain text and HTML is ISO-8859-1 (effectively, the ASCII character set).

If you specify the contentItems parameter, omit the content_type. Per the JSON specification, the default character encoding for JSON content is effectively always UTF-8.
language string The language of the input text for the request:
  • ar (Arabic)
  • en (English, the default)
  • es (Spanish)
  • ja (Japanese)
Regional variants are treated as their parent language; for example, en-US is interpreted as en. The effect of the language parameter depends on the type of input text:
  • If you specify the text parameter, the language parameter is the only way to specify the language of the content.
  • If you specify the contentItems parameter, the language parameter overrides a language specified with the language field of a ContentItem object; content items that specify a different language are ignored. Omit this parameter to base the language on the specification of the content items.
You can specify any combination of languages for language and accept_language.
accept_language string The desired language of the response:
  • ar (Arabic)
  • en (English, the default)
  • es (Spanish)
  • ja (Japanese)
Regional variants are treated as their parent language; for example, en-US is interpreted as en. You can specify any combination of languages for the input text and the response.
include_raw boolean Indicates whether a raw score is to be returned for each characteristic; raw scores are not compared with a sample population. A raw sampling error for each characteristic is also returned. If true, a raw score is returned in addition to a normalized score; if false (the default), only a normalized score is returned.
csv boolean Indicates whether to provide CSV output that includes a fixed number of columns and optional headers. If true, the service returns CSV output; if false (the default), the service returns JSON output.
csv_headers boolean Indicates whether column labels are returned with a CSV response. If true, column labels are returned; if false (the default), they are not. Applies only when the csv parameter is set to true.
ContentListContainer
Parameter Description
contentItems object[ ] An array of ContentItem objects that provides the input text for the request.
ContentItem
Parameter Description
content string A maximum of 20 MB of content (combined across all ContentItem objects) to be analyzed.
id string A unique identifier for this content item.
userid string A unique identifier for the author of this content.
sourceid string An identifier for the source of this content; for example, blog123 or twitter.
created integer A timestamp that identifies when this content was created. Specify a value in milliseconds since the UNIX Epoch (January 1, 1970, at 0:00 UTC). Required only for results that include temporal behavior data.
updated integer A timestamp that identifies when this content was last updated. Specify a value in milliseconds since the UNIX Epoch (January 1, 1970, at 0:00 UTC). Required only for results that include temporal behavior data.
contenttype string The MIME type of the content:
  • text/plain for plain text (the default)
  • text/html for HTML content
The tags are stripped from HTML content before it is analyzed; other MIME types are processed as is.
charset string (Deprecated) This field is ignored. Character encoding for JSON data is assumed to be in UTF-8 format per the JSON specification.
language string The language of the content as a two-letter ISO 639-1 identifier:
  • ar (Arabic)
  • en (English, the default)
  • es (Spanish)
  • ja (Japanese)
Regional variants are treated as their parent language; for example, en-US is interpreted as en. A language specified with the Content-Type header language parameter of the request overrides the value of this parameter; content items that specify a different language are ignored. Omit the Content-Type header language parameter of the request to base the language on the most prevalent specification among the content items; again, content items that specify a different language are ignored. You can specify any combination of languages for the input text and the response.
parentid string The unique ID of the parent content item for this item. Used to identify hierarchical relationships between posts/replies, messages/replies, and so on.
reply boolean Indicates whether this content item is a reply to another content item.
forward boolean Indicates whether this content item is a forwarded/copied version of another content item.
Parameter Type Description
text string Plain text to be analyzed. Pass a maximum of 20 MB of text.
options object A Java ProfileOptions object that specifies the parameters of the request. Use this object to pass plain text, HTML, or JSON input.
includeHeaders boolean Indicates whether column labels are returned with a CSV response. If true, column labels are returned; if false (the default), they are not.
Java ProfileOptions object
Parameter Type Description
acceptLanguage string The desired language of the response:
  • AcceptLanguage.ENGLISH (the default)
  • AcceptLanguage.SPANISH
Specified by a method of the Java ProfileOptions class.You can specify any combination of languages for acceptLanguage and language.
language string The language of the input text for the request:
  • Language.ENGLISH (the default)
  • Language.SPANISH
The effect of the language parameter depends on the type of input:
  • For plain text and HTML input, this parameter is the only way to specify the language.
  • For JSON input, this parameter overrides a language that is specified with the language parameter of a Java ContentItem object; content items that specify a different language are ignored. Omit this parameter to base the language on the specification of the content items.
Specified by a method of the Java ProfileOptions class.You can specify any combination of languages for language and acceptLanguage.
contentItems List<ContentItem> A List of Java ContentItem objects that provide JSON input to be analyzed. You must provide one of plain text, HTML, or JSON input. You can specify elements of the List individually or as a List with methods of the Java ProfileOptions class. Optionally, you can also define a List of Java ContentItem objects by using a Java Content object.
text string Plain text input to be analyzed. Pass a maximum of 20 MB of text. You must provide one of plain text, HTML, or JSON input. Specified by a method of the Java ProfileOptions class.
html string HTML input to be analyzed. Pass a maximum of 20 MB of text. You must provide one of plain text, HTML, or JSON input. Specified by a method of the Java ProfileOptions class.
includeRaw boolean Indicates whether a raw score is to be returned for each characteristic; raw scores are not compared with a sample population. A raw sampling error for each characteristic is also returned. If true, a raw score is returned in addition to a normalized score; if false (the default), only a normalized score is returned. Specified by a method of the Java ProfileOptions class.
Constructor:
Java Content object
Parameter Description
contentItems List<ContentItem> A List of Java ContentItem objects that provide JSON input to be analyzed. You can specify elements of the List individually or as a List with methods of the Java Content class.

This object is useful for reading content from a JSON source file that is provided in the format consumed by the HTTP REST and Node APIs. Its use is optional; you can add Java ContentItem objects directly to a Java ProfileOptions object with methods of that class.
Constructor:
Java ContentItem object
Parameter Description
content string A maximum of 20 MB of content (combined across all Java ContentItem objects) to be analyzed. Specified by methods of the Java ContentItem class.
id string A unique identifier for this content item. Specified by methods of the Java ContentItem class.
userid string A unique identifier for the author of this content. Specified by methods of the Java ContentItem class.
sourceid string An identifier for the source of this content; for example, blog123 or twitter. Specified by methods of the Java ContentItem class.
created object A Java Date object (typically created as a value in milliseconds since the UNIX Epoch) that identifies when this content was created. Required only for results that include temporal behavior data. Specified by methods of the Java ContentItem class.
updated object A Java Date object (typically created as a value in milliseconds since the UNIX Epoch) that identifies when this content was last updated. Required only for results that include temporal behavior data. Specified by methods of the Java ContentItem class.
contentType string The MIME type of the content:
  • text/plain for plain text (the default)
  • text/html for HTML content
The tags are stripped from HTML content before it is analyzed; other MIME types are processed as is. Specified by methods of the Java ContentItem class.
charset string Specifies the character encoding of the content, for example, UTF-8. The encoding for JSON data is assumed to be in UTF-8 format per the JSON specification. Specified by methods of the Java ContentItem class.
language string The language of the content as a two-letter ISO 639-1 identifier:
  • en (English, the default)
  • es (Spanish)
Regional variants are treated as their parent language; for example, en-US is interpreted as en. Specified by methods of the Java ContentItem class.

A language specified with the language parameter of the Java ProfileOptions object overrides the value of this parameter; content items that specify a different language are ignored. Omit the language parameter of the Java ProfileOptions object to base the language on the most prevalent specification among the content items; again, content items that specify a different language are ignored. You can specify any combination of languages for the input text and the response.
parentid string The unique ID of the parent content item for this item. Used to identify hierarchical relationships between posts/replies, messages/replies, and so on. Specified by methods of the Java ContentItem class.
reply boolean Indicates whether this content item is a reply to another content item. Specified by methods of the Java ContentItem class.
forward boolean Indicates whether this content item is a forwarded/copied version of another content item. Specified by methods of the Java ContentItem class.
Constructor:

Example request


curl -X POST -u "{username}:{password}"
--header "Content-Type: application/json"
--data-binary @profile.json
"https://gateway.watsonplatform.net/personality-insights/api/v2/profile"

var watson = require('watson-developer-cloud');
var personality_insights = watson.personality_insights({
  username: '{username}',
  password: '{password}',
  version: 'v2'
});

var params = require('profile.json');

personality_insights.profile(params, function(error, response) {
  if (error)
    console.log('error:', error);
  else
    console.log(JSON.stringify(response, null, 2));
  }
);

PersonalityInsights service = new PersonalityInsights();
service.setUsernameAndPassword("{username}", "{password}");

try {
  JsonReader jReader = new JsonReader(new FileReader("profile.json"));
  Content content = GsonSingleton.getGson().fromJson(jReader, Content.class);
  ProfileOptions options = new ProfileOptions().contentItems(content.getContentItems());
  Profile profile = service.getProfile(options);
  System.out.println(profile);
} catch (FileNotFoundException e) {
  e.printStackTrace();
}

Response

Profile
Name Description
id string The unique user identifier for which these characteristics were computed. The value is derived from the userid field of the input ContentItem Java ContentItem objects. The field is passed as-is from JSON input; sanitize the contents of the field before displaying them to prevent cross-site scripting attacks. For plain text and HTML input, the field contains the string *UNKNOWN*.
source string The source identifier for which these characteristics were computed. The value is derived from the sourceid field of the input ContentItem Java ContentItem objects. The field is passed as-is from JSON input; sanitize the contents of the field before displaying them to prevent cross-site scripting attacks. For plain text and HTML input, the field contains the string *UNKNOWN*.
processed_lang string The language model that was used to process the input; for example, en.
word_count integer The number of words that were found in the input.
word_count_message string When guidance is appropriate, a message that indicates the number of words found and where that value falls in the range of required or suggested number of words.
warnings object[ ] An array of Warning objects that provide messages associated with the input text submitted with the request. The array is empty if the input generated no warnings.
tree object A TraitTreeNode object that provides detailed results for a specific characteristic of the input text.
TraitTreeNode
Name Description
id string The unique identifier of the characteristic to which the results pertain.
name string The user-visible name of the characteristic.
category string The category of the characteristic:
  • personality for Big File personality characteristics
  • needs for Needs
  • values for Values
  • behavior for temporal data
percentage number For personality, needs, and values characteristics, the normalized percentile score for the characteristic. The range is 0 to 1. For example, if the percentage for Openness is 0.25, the author scored in the 25th percentile; the author is more open than 24% of the population and less open than 74% of the population. For behavior characteristics, the percentage of timestamped data that occurred during that day or hour.
sampling_error number For personality, needs, and values characteristics, the sampling error of the percentage based on the number of words in the input text. The range is 0 to 1. The number defines a 95% confidence interval around the percentage. For example, if the sampling error is 4% and the percentage is 61%, it is 95% likely that the actual percentage value is between 57% and 65% if more words are given.
raw_score number For personality, needs, and values characteristics, the raw score for the characteristic. A positive or negative score indicates more or less of the characteristic; zero indicates neutrality or no evidence for a score. The raw score is computed based on the input and the service model; it is not normalized or compared with a sample population. The raw score enables comparison of the results against a different sampling population and with a custom normalization approach.
raw_sampling_error number For personality, needs, and values characteristics, the sampling error of the raw score based on the number of words in the input. The practical range is 0 to 1. The number defines a 95% confidence interval around the raw score. For example, if the raw sampling error is 5% and the raw score is 65%, it is 95% likely that the actual raw score is between 60% and 70% if more words are given.
children object[ ] A recursive array of TraitTreeNode objects that provides more detailed characteristics inferred from the input text.
Warning
Name Description
id string The identifier of the warning message, one of WORD_COUNT_MESSAGE, JSON_AS_TEXT, or PARTIAL_TEXT_USED.
message string The message associated with the id.
  • WORD_COUNT_MESSAGE: There were number words in the input. We need a minimum of 600, preferably 1,200 or more, to compute statistically significant estimates.
  • JSON_AS_TEXT: Request input was processed as text/plain as indicated, however detected a JSON input. Did you mean application/json?
  • PARTIAL_TEXT_USED: The text provided to compute the profile was trimmed for performance reasons. This action does not affect the accuracy of the output, as not all of the input text was required. This message applies only when Arabic input text exceeds a threshold at which additional words do not contribute to the accuracy of the profile.

Example response

Note: The ordering of the fields in the JSON output from the Java SDK might differ from the example. The contents are structurally equivalent.


{
  "id": "@Oprah",
  "source": "Twitter API",
  "word_count": 15961,
  "processed_lang": "en",
  "tree": {
    "id": "r",
    "name": "root",
    "children": [
      {
        "id": "personality",
        "name": "Big 5",
        "children": [
          {
            "id": "Agreeableness_parent",
            "name": "Agreeableness",
            "category": "personality",
            "percentage": 0.9236001790723337,
            "children": [
              {
                "id": "Openness",
                "name": "Openness",
                "category": "personality",
                "percentage": 0.4436175847676207,
                "sampling_error": 0.04462713392,
                "children": [
                  {
                    "id": "Adventurousness",
                    "name": "Adventurousness",
                    "category": "personality",
                    "percentage": 0.5532854151651387,
                    "sampling_error": 0.04010701756
                  },
                  . . .
                ]
              },
              {
                "id": "Conscientiousness",
                "name": "Conscientiousness",
                "category": "personality",
                "percentage": 0.7953785021598482,
                "sampling_error": 0.058016039,
                "children": [
                  {
                    "id": "Achievement striving",
                    "name": "Achievement striving",
                    "category": "personality",
                    "percentage": 0.6523027025711667,
                    "sampling_error": 0.08080605176
                  },
                  . . .
                ]
              },
              {
                "id": "Extraversion",
                "name": "Extraversion",
                "category": "personality",
                "percentage": 0.9146865456005568,
                "sampling_error": 0.04312390508,
                "children": [
                  {
                    "id": "Activity level",
                    "name": "Activity level",
                    "category": "personality",
                    "percentage": 0.19908143626750582,
                    "sampling_error": 0.060655533399999996
                  },
                  . . .
                ]
              },
              {
                "id": "Agreeableness",
                "name": "Agreeableness",
                "category": "personality",
                "percentage": 0.9236001790723337,
                "sampling_error": 0.07963770056,
                "children": [
                  {
                    "id": "Altruism",
                    "name": "Altruism",
                    "category": "personality",
                    "percentage": 0.9096245650638992,
                    "sampling_error": 0.05499027136
                  },
                  . . .
                ]
              },
              {
                "id": "Neuroticism",
                "name": "Emotional range",
                "category": "personality",
                "percentage": 0.19453067367849702,
                "sampling_error": 0.07456209915999999,
                "children": [
                  {
                    "id": "Anger",
                    "name": "Fiery",
                    "category": "personality",
                    "percentage": 0.2470213218738412,
                    "sampling_error": 0.07631745072
                  },
                  . . .
                ]
              }
            ]
          }
        ]
      },
      {
        "id": "needs",
        "name": "Needs",
        "children": [
          {
            "id": "Structure_parent",
            "name": "Structure",
            "category": "needs",
            "percentage": 0.026328691945597192,
            "children": [
              {
                "id": "Challenge",
                "name": "Challenge",
                "category": "needs",
                "percentage": 0.09375138505532467,
                "sampling_error": 0.06323989104
              },
              . . .
            ]
          }
        ]
      },
      {
        "id": "values",
        "name": "Values",
        "children": [
          {
            "id": "Self-enhancement_parent",
            "name": "Self-enhancement",
            "category": "values",
            "percentage": 0.13904934867653226,
            "children": [
              {
                "id": "Conservation",
                "name": "Conservation",
                "category": "values",
                "percentage": 0.5381417013177039,
                "sampling_error": 0.06348028232
              },
              . . .
            ]
          }
        ]
      },
      {
        "id": "sbh",
        "name": "Social Behavior",
        "category": "behavior",
        "children": [
          {
            "id": "sbh_parent",
            "name": "Mon. Midnight",
            "category": "behavior",
            "children": [
              {
                "id": "Monday_parent",
                "name": "Mon.",
                "category": "behavior",
                "percentage": 0.42157842157842157,
                "children": [
                  {
                    "id": "Sunday",
                    "name": "Sunday",
                    "category": "behavior",
                    "percentage": 0.2217782217782218
                  },
                  . . .
                ]
              },
              {
                "id": "0:00 am_parent",
                "name": "Midnight",
                "category": "behavior",
                "percentage": 0.4515484515484515,
                "children": [
                  {
                    "id": "0:00 am",
                    "name": "0:00 am",
                    "category": "behavior",
                    "percentage": 0.4515484515484515
                  },
                  . . .
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "warnings": []
}