Curl Node Java Python

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. The service can infer consumption preferences based on the results of its analysis and, for JSON content that is timestamped, can report temporal behavior.

For information about the meaning of the models that the service uses to describe personality characteristics, see Personality models. For information about the meaning of the consumption preferences, see Consumption preferences.

API endpoint


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

The code examples on this tab use the client library that is provided for Node.js.

GitHub

https://github.com/watson-developer-cloud/node-sdk

Node Package Manager


npm install watson-developer-cloud

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

GitHub

https://github.com/watson-developer-cloud/java-sdk

Maven


<dependency>
  <groupId>com.ibm.watson.developer_cloud</groupId>
  <artifactId>java-sdk</artifactId>
  <version>3.7.2</version>
</dependency>

Gradle


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

The code examples on this tab use the client-side library that is provided for Python.

GitHub

https://github.com/watson-developer-cloud/python-sdk

Python


pip install --upgrade watson-developer-cloud

easy_install --upgrade watson-developer-cloud

Synchronous and asynchronous requests

The Java SDK supports both synchronous (blocking) and asynchronous (non-blocking) execution of all methods. All methods are called with the Java ServiceCall interface.

  • To call a method synchronously, use the execute method of the ServiceCall interface. You can also call the execute method directly from an instance of the service, as shown in Get profile. Note that the method can return an unchecked RuntimeException.

  • To call a method asynchronously, use the enqueue method of the ServiceCall interface to receive a callback when the response arrives. The ServiceCallback interface of the method's argument provides onResponse and onFailure methods that you override to handle the callback.

Example synchronous request


ServiceCall call = service.getProfile(options);
Profile profile = call.execute();

Example asynchronous request


ServiceCall call = service.getProfile(options);
call.enqueue(new ServiceCallback<Profile>() {
  @Override public void onResponse(Profile profile) {
    . . .
  }
  @Override public void onFailure(Exception e) {
    . . .
  }
});

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. Descriptions of Python modules referred to in this reference are available in the Python documentation for the Watson Developer Cloud Python SDK. Detailed information about using the service is available at About Personality Insights.

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 Service 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 Bluemix 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 Tokens for authentication.

Replace {username} and {password} with your service credentials. Replace {version} with the version of the API you want to use (for example, 2016-10-20). Use either of the two constructors shown.


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

var PersonalityInsightsV3 = require('watson-developer-cloud/personality-insights/v3');
var personality_insights = new PersonalityInsightsV3({
  username: '{username}',
  password: '{password}',
  version_date: '{version}'
});

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

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

personality_insights = PersonalityInsightsV3(
  version='{version}',
  username='{username}',
  password='{password}'
)

Request logging

By default, Bluemix collects data from all requests and uses the data to improve the Watson services. If you do not want to share your data, you can disable request logging by setting the X-Watson-Learning-Opt-Out header to true for each request. Data is not collected for any request that includes this header. setting the X-Watson-Learning-Opt-Out parameter to true when you create the service instance. Data is not collected for any calls by that instance of the service. setting the X-Watson-Learning-Opt-Out header to true when you create the service instance. Data is not collected for any calls by that instance of the service. setting the x-watson-learning-opt-out parameter to True when you create the service instance. Data is not collected for any calls by that instance of the service. For more information, see Controlling request logging for Watson services.


curl -u "{username}":"{password}"
--header "X-Watson-Learning-Opt-Out: true"
"https://gateway.watsonplatform.net/personality-insights/api/v3/{method}"

var PersonalityInsightsV3 = require('watson-developer-cloud/personality-insights/v3');
var personality_insights = new PersonalityInsightsV3({
  username: '{username}',
  password: '{password}',
  version_date: '{version}'
  headers: {
    'X-Watson-Learning-Opt-Out': 'true'
  }
});

Map<String, String> headers = new HashMap<String, String>();
headers.put("X-Watson-Learning-Opt-Out", "true");

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

personality_insights = PersonalityInsightsV3(
  version='{version}',
  username='username}',
  password='{password}',
  x-watson-learning-opt-out=True
)

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.

Response codes that indicate success are not readily available with the Node.js SDK. In general, the lack of an error response indicate a 200-level success response. For errors, response codes are indicated in the error object that is returned.

The Java SDK raises equivalent exceptions. The exceptions include the error message returned by the service.

The Python SDK raises exceptions. The exceptions include the error message returned by the service.

Response codes

Status Description
200 OK The request succeeded.
400 Bad Request The request JSON is not properly formatted, fewer than 100 words are provided, the requested language is not supported, or the version is missing or malformed. Specific messages include
  • No version provided
  • Invalid version format
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 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.)

Exceptions thrown

Exception Description
WatsonInvalidArgument The call to the Python method was invalid; for example, the call passed an invalid argument. The Python module raises this exception without calling the service.
WatsonException The service returned an error in response to the call. The Python module raises this exception to report the error from the service.

Error format

Name Description
code integer HTTP status code.
error string A description of the error.
sub_code string A service-specific error code.
help string A URL to documentation explaining the cause and possibly solutions for the error.
Name Description
Exception string The name of the exception that was raised.
status integer The HTTP status code.
error string A description of the error.
Name Description
Exception string The name of the exception that was raised.
Error string A description of the error.
Code integer The HTTP status code.

Example error


{
  "code": 400,
  "sub_code": "S00005",
  "error": "Invalid JSON input at line 4, column 21"
}

{
  Error: Invalid version format
  . . .
  code: 400,
  sub_code: 'S00017',
  error: 'Invalid version format'
}

SEVERE: POST https://gateway.watsonplatform.net/personality-insights/api/v3/profile?version=2016-10-20, status: 401, error: Not Authorized
Exception in thread "main" com.ibm.watson.developer_cloud.service.exception.UnauthorizedException: Unauthorized: Access is denied due to invalid credentials
  . . .

Traceback (most recent call last):
  . . .
    raise WatsonException(error_message)
watson_developer_cloud.watson_developer_cloud_service.WatsonException:
  Error: Invalid JSON input at line 4, column 21, Code: 400

Methods

Get profile

Generates a personality profile for the author of the input text. The service accepts a maximum of 20 MB of input content, but it requires much less text to produce an accurate profile; for more information, see Guidelines for providing sufficient input. The service can analyze text in Arabic, English, Japanese, or Spanish and return its results in a variety of languages. You can provide plain text, HTML, or JSON input. Use the text parameter to provide plain text or HTML input; use the content_items parameter for JSON input. The service returns output in JSON format by default, but you can request the output in CSV format.

You call the service via an instance of the PersonalityInsights class. You can provide plain text as input with any of the class's 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.

For detailed information about calling the service and the responses it can generate, including the meaning of the numeric results, see Input: Requesting a profile and Output: Understanding a profile.


POST /v3/profile

profile(params, callback())

ServiceCall<Profile> getProfile(String text)
ServiceCall<Profile> getProfile(ProfileOptions options)
ServiceCall<String> getProfileAsCSV(ProfileOptions options, boolean includeHeaders)

profile(text, content_type='text/plain', content_language=None,
  accept='application/json', accept_language=None, raw_scores=False,
  consumption_preferences=False, csv_headers=False)

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
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). 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.
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)
For two-character arguments, 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 request and the response.
raw_scores query boolean Indicates whether a raw score in addition to a normalized percentile is to be returned for each characteristic; raw scores are not compared with a sample population. The default is false; only normalized percentiles are returned.
consumption_preferences query boolean Indicates whether consumption preferences are to be returned with the results. The default is false; no consumption preferences are returned.
csv_headers query boolean Indicates whether column labels are to be returned with a CSV response. The default is false; no column labels are returned. Applies only when the Accept header is set to text/csv.
version query string The requested version of the response format as a date in the form YYYY-MM-DD; for example, specify 2016-10-20 for October 20, 2016. The parameter allows the service to update its response format for new versions without breaking existing clients.

The date that you specify does not need to match a version of the service exactly; the service replies with the response format whose version is no later than the date you provide. If you specify a date that is earlier than the initial release of version 3, the service returns the response format for that version. If you specify a date that is in the future or otherwise later than the most recent version, the service returns the response format for the latest version.
body body string A maximum of 20 MB of content to be analyzed, though the service requires much less input; for more information, see Guidelines for providing sufficient input. For JSON input, provide an object of type ContentListContainer.
Arguments for params
Parameter Description
text string The text to be analyzed, plain text (the default) or HTML. Provide a maximum of 20 MB of content to be analyzed, though the service requires much less input; for more information, see Guidelines for providing sufficient input. You must specify either the text or content_items parameter.
content_items object A ContentListContainer object that provides the JSON content to be analyzed. Provide a maximum of 20 MB of content across all content items, though the service requires much less input; for more information, see Guidelines for providing sufficient input. You must specify either the text or content_items parameter.
raw_scores boolean Indicates whether a raw score in addition to a normalized percentile is to be returned for each characteristic; raw scores are not compared with a sample population. The default is false; only normalized percentiles are returned.
consumption_preferences boolean Indicates whether consumption preferences are to be returned with the results. The default is false; no consumption preferences are returned.
csv_headers boolean Indicates whether column labels are to be returned with a CSV response. The default is false; no column labels are returned. Applies only when the accept header is set to text/csv.
headers object Parameters equivalent to the request headers of the HTTP REST method.
Arguments for headers
Parameter Description
content-type 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
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). 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.
content-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 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 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 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)
For two-character arguments, 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 request and the response.
Parameter Description
text string A maximum of 20 MB of content to be analyzed, though the service requires much less input; for more information, see Guidelines for providing sufficient input. For JSON input, provide an object of type ContentListContainer.
content_type 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
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). 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.
content_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 content_language parameter depends on the content_type parameter:
  • 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 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 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)
For two-character arguments, 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 request and the response.
raw_scores boolean Indicates whether a raw score in addition to a normalized percentile is to be returned for each characteristic; raw scores are not compared with a sample population. The default is false; only normalized percentiles are returned.
consumption_preferences boolean Indicates whether consumption preferences are to be returned with the results. The default is false; no consumption preferences are returned.
csv_headers boolean Indicates whether column labels are to be returned with a CSV response. The default is false; no column labels are returned. Applies only when the accept header is set to text/csv.
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.
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; plain text is processed as submitted.
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-Language header language parameter content_language parameter of the request overrides the value of this parameter; content items that specify a different language are ignored. Omit the Content-Language header language parameter content_language parameter 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 Description
text string Plain text to be analyzed. Pass a maximum of 20 MB of text, though the service requires much less input; for more information, see Guidelines for providing sufficient input.
options object A Java ProfileOptions object that specifies the parameters of the request. Use this object to pass a maximum of 20 MB of plain text, HTML, or JSON content to be analyzed, though the service requires much less input; for more information, see Guidelines for providing sufficient input. To create an instance of the object, use the ProfileOptions.Builder static nested class.
includeHeaders boolean Indicates whether column labels are to be returned with a CSV response. The default is false; no column headers are returned.
Java ProfileOptions object
Parameter Description
text string Plain text input to be analyzed. You must provide one of the text, html, or contentItems parameters.
html string HTML input to be analyzed. You must provide one of the text, html, or contentItems parameters.
contentItems List A List of Java ContentItem objects that provide JSON input to be analyzed. You can specify content items individually or you can define a List of Java ContentItem objects by using a Java Content object. You must provide one of the text, html, or contentItems parameters.
language string The language of the input text for the request:
  • Language.ARABIC
  • Language.ENGLISH (the default)
  • Language.JAPANESE
  • 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.
You can specify any combination of languages for language and acceptLanguage.
acceptLanguage string The desired language of the response:
  • Language.ARABIC
  • Language.ENGLISH (the default)
  • Language.JAPANESE
  • Language.SPANISH
  • Language.BRAZILIAN_PORTUGUESE
  • Language.FRENCH
  • Language.GERMAN
  • Language.ITALIAN
  • Language.KOREAN
  • Language.SIMPLIFIED_CHINESE
  • Language.TRADITIONAL_CHINESE
You can specify any combination of languages for acceptLanguage and language.
rawScores boolean Indicates whether a raw score is to be returned for each characteristic; raw scores are not compared with a sample population. The default is false; only normalized percentiles are returned.
consumptionPreferences boolean Indicates whether consumption preferences are to be returned with the results. The default is false; no consumption preferences are returned.
Constructor: ProfileOptions.Builder
Java Content object
Parameter Description
contentItems List A List of Java ContentItem objects that provide JSON input to be analyzed. 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 the ProfileOptions.Builder class.
Constructor: Content
Java ContentItem object
Parameter Description
content string A maximum of 20 MB of content (combined across all Java ContentItem objects) to be analyzed.
id string A unique identifier for this content item.
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.
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.
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; plain text is processed as submitted.
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 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 request 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.
Constructor: ContentItem

Example request


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

var PersonalityInsightsV3 = require('watson-developer-cloud/personality-insights/v3');
var personality_insights = new PersonalityInsightsV3({
  username: '{username}',
  password: '{password}',
  version_date: '2016-10-20'
});

var params = {
  // Get the content items from the JSON file.
  content_items: require('./profile.json').contentItems,
  consumption_preferences: true,
  raw_scores: true,
  headers: {
    'accept-language': 'en',
    'accept': 'application/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("2016-10-20");
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.Builder()
    .contentItems(content.getContentItems())
    .consumptionPreferences(true)
    .rawScores(true)
    .build();
  Profile profile = service.getProfile(options).execute();
  System.out.println(profile);
} catch (FileNotFoundException e) {
  e.printStackTrace();
}

personality_insights = PersonalityInsightsV3(
  version='2016-10-20',
  username='{username}',
  password='{password}')

with open(join(dirname(__file__), './profile.json')) as profile_json:
  profile = personality_insights.profile(
    profile_json.read(), content_type='application/json',
    raw_scores=True, consumption_preferences=True)

print(json.dumps(profile, indent=2))

Response

The getProfileAsCSV method returns CSV results as a string. The getProfile methods returns Java objects whose contents are structurally equivalent to the JSON objects returned by the REST interface.

The ordering of the fields in the JSON output might differ from the example response. The contents are equivalent to the results returned by the REST interface.

Profile (Java Profile object)
Name Description
word_count integer The number of words from the input that were used to produce the profile.
processed_language string The language model that was used to process the input; for example, en.
personality object[ ] A recursive array of TraitTreeNode objects that provides detailed results for the Big Five personality characteristics (dimensions and facets) inferred from the input text.
needs object[ ] An array of TraitTreeNode objects that provides detailed results for the Needs characteristics inferred from the input text.
values object[ ] An array of TraitTreeNode objects that provides detailed results for the Values characteristics inferred from the input text.
behavior object[ ] For JSON content that is timestamped, an array of BehaviorNode objects that provides detailed results about the social behavior disclosed by the input in terms of temporal characteristics. The results include information about the distribution of the content over the days of the week and the hours of the day.
consumption_preferences object[ ] If the consumption_preferences query parameter is true, an array of ConsumptionPreferencesCategoryNode objects that provides detailed results for each category of consumption preferences. Each element of the array provides information for the individual preferences of that category.
warnings object[ ] An array of Warning objects that provides messages associated with the input text submitted with the request. The array is empty if the input generated no warnings.
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.
TraitTreeNode (Java Trait object)
Name Description
trait_id string The unique identifier of the characteristic to which the results pertain. IDs have the following form:
  • big5_characteristic for Big Five personality dimensions
  • facet_characteristic for Big Five personality facets
  • need_characteristic for Needs
  • value_characteristic for Values
name string The user-visible name of the characteristic.
category string The category of the characteristic:
  • personality for Big Five personality characteristics
  • needs for Needs
  • values for Values
percentile number The normalized percentile score for the characteristic. The range is 0 to 1. For example, if the percentile for Openness is 0.60, the author scored in the 60th percentile; the author is more open than 59 percent of the population and less open than 39 percent of the population.
raw_score number If you request raw scores, the raw score for the characteristic. The range is 0 to 1. A higher score generally indicates a greater likelihood that the author has that characteristic, but raw scores must be considered in aggregate: The range of values in practice might be much smaller than 0 to 1, so an individual score must be considered in the context of the overall scores and their range.

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.
children object[ ] For personality (Big Five) dimensions, an array of TraitTreeNode objects that provides more detailed results for the facets of each dimension as inferred from the input text.
BehaviorNode (Java Behavior object)
Name Description
trait_id string The unique identifier of the characteristic to which the results pertain. IDs have the form behavior_value.
name string The user-visible name of the characteristic.
category string The category of the characteristic: behavior for temporal data.
percentage number For JSON content that is timestamped, the percentage of timestamped input data that occurred during that day of the week or hour of the day. The range is 0 to 1.
ConsumptionPreferencesCategoryNode (Java ConsumptionPreferences object)
Name Description
consumption_preference_category_id string The unique identifier of the consumption preferences category to which the results pertain. IDs have the form consumption_preferences_category.
name string The user-visible name of the consumption preferences category.
consumption_preferences object[ ] An array of ConsumptionPreferencesNode objects that provides detailed results inferred from the input text for the individual preferences of the category.
ConsumptionPreferencesNode (Java ConsumptionPreferences.ConsumptionPreference object)
Name Description
consumption_preference_id string The unique identifier of the consumption preference to which the results pertain. IDs have the form consumption_preferences_preference.
name string The user-visible name of the consumption preference.
score number The score for the consumption preference:
  • 0.0 (unlikely)
  • 0.5 (neutral)
  • 1.0 (likely)
The scores for some preferences are binary and do not allow a neutral value. The score is an indication of preference based on the results inferred from the input text, not a normalized percentile.
Warning (Java Profile.Warning object)
Name Description
warning_id string The identifier of the warning message, one of WORD_COUNT_MESSAGE, JSON_AS_TEXT, CONTENT_TRUNCATED, or PARTIAL_TEXT_USED.
message string The message associated with the warning_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?
  • CONTENT_TRUNCATED: For maximum accuracy while also optimizing processing time, only the first 250KB of input text (excluding markup) was analyzed. Accuracy levels off at approximately 3,000 words so this did not affect the accuracy of the profile.
  • 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


{
  "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": "facet_adventurousness",
          "name": "Adventurousness",
          "category": "personality",
          "percentile": 0.89755869047319,
          "raw_score": 0.54990704031219
        },
        . . .
      ]
    },
    {
      "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.64980796071382,
      "raw_score": 0.56817738781166,
      "children": [
        {
          "trait_id": "facet_activity_level",
          "name": "Activity level",
          "category": "personality",
          "percentile": 0.88220584913965,
          "raw_score": 0.60106995926143
        },
        . . .
      ]
    },
    {
      "trait_id": "big5_agreeableness",
      "name": "Agreeableness",
      "category": "personality",
      "percentile": 0.94786124793821,
      "raw_score": 0.80677815631809,
      "children": [
        {
          "trait_id": "facet_altruism",
          "name": "Altruism",
          "category": "personality",
          "percentile": 0.99241983824205,
          "raw_score": 0.79028406290747
        },
        . . .
      ]
    },
    {
      "trait_id": "big5_neuroticism",
      "name": "Emotional range",
      "category": "personality",
      "percentile": 0.5008224041628,
      "raw_score": 0.46748200007024,
      "children": [
        {
          "trait_id": "facet_anger",
          "name": "Fiery",
          "category": "personality",
          "percentile": 0.17640022058508,
          "raw_score": 0.48490315691802
        },
        . . .
      ]
    }
  ],
  "needs": [
    {
      "trait_id": "need_challenge",
      "name": "Challenge",
      "category": "needs",
      "percentile": 0.67362332054511,
      "raw_score": 0.75196348037675
    },
    {
      "trait_id": "need_closeness",
      "name": "Closeness",
      "category": "needs",
      "percentile": 0.83802834041813,
      "raw_score": 0.83714327329724
    },
    . . .
  ],
  "values": [
    {
      "trait_id": "value_conservation",
      "name": "Conservation",
      "category": "values",
      "percentile": 0.89268222856139,
      "raw_score": 0.72135308187423
    },
    {
      "trait_id": "value_openness_to_change",
      "name": "Openness to change",
      "category": "values",
      "percentile": 0.85759916388086,
      "raw_score": 0.82551308431323
    },
    . . .
  ],
  "behavior": [
    {
      "trait_id": "behavior_sunday",
      "name": "Sunday",
      "category": "behavior",
      "percentage": 0.21392532795156
    },
    {
      "trait_id": "behavior_monday",
      "name": "Monday",
      "category": "behavior",
      "percentage": 0.42583249243189
    },
    . . .
    {
      "trait_id": "behavior_0000",
      "name": "0:00 am",
      "category": "behavior",
      "percentage": 0.4561049445005
    },
    {
      "trait_id": "behavior_0100",
      "name": "1:00 am",
      "category": "behavior",
      "percentage": 0.12209889001009
    },
    . . .
  ],
  "consumption_preferences": [
    {
      "consumption_preference_category_id": "consumption_preferences_shopping",
      "name": "Purchasing Preferences",
      "consumption_preferences": [
        {
          "consumption_preference_id": "consumption_preferences_automobile_ownership_cost",
          "name": "Prefers automobile ownership cost",
          "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": "Prefers to eat out",
          "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": "Entreprenuership Preferences",
      "consumption_preferences": [
        {
          "consumption_preference_id": "consumption_preferences_start_business",
          "name": "Likely to start 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": "Reading frequency",
          "score": 0
        },
        . . .
      ]
    },
    {
      "consumption_preference_category_id": "consumption_preferences_volunteering",
      "name": "Volunteering Preferences",
      "consumption_preferences": [
        {
          "consumption_preference_id": "consumption_preferences_volunteer",
          "name": "Have volunteering experience",
          "score": 0
        }
      ]
    }
  ],
  "warnings": []
}