Skip to content

Latest commit

 

History

History
executable file
·
137 lines (106 loc) · 10.2 KB

getting-started.md

File metadata and controls

executable file
·
137 lines (106 loc) · 10.2 KB
Raw
copyright lastupdated subcollection
years
2015, 2019
2019-03-07
personality-insights

{:shortdesc: .shortdesc} {:new_window: target="_blank"} {:tip: .tip} {:important: .important} {:note: .note} {:deprecated: .deprecated} {:pre: .pre} {:codeblock: .codeblock} {:screen: .screen} {:javascript: .ph data-hd-programlang='javascript'} {:go: .ph data-hd-programlang='go'} {:java: .ph data-hd-programlang='java'} {:python: .ph data-hd-programlang='python'} {:swift: .ph data-hd-programlang='swift'} {:download: .download} {:apikey: data-credential-placeholder='apikey'} {:url: data-credential-placeholder='url'} {:hide-dashboard: .hide-dashboard}

Getting started tutorial

{: #gettingStarted}

The {{site.data.keyword.personalityinsightsfull}} service derives insights about personality characteristics from social media, enterprise data, or other digital communications. This tutorial can help you get started quickly with the {{site.data.keyword.personalityinsightsshort}} service. The examples show you how to call the service's POST /v3/profile method with different types of input and how to request different types of output and output formats. {: shortdesc}

The tutorial uses {{site.data.keyword.cloud}} Identity and Access Management (IAM) API keys for authentication. Older service instances might continue to use the {username} and {password} from their existing Cloud Foundry service credentials for authentication. Authenticate by using the approach that is right for your service instance. For more information about the service's use of IAM authentication, see the 30 October 2018 service update in the release notes. {: important}

Before you begin

{: #before-you-begin}

  • {: hide-dashboard} Create an instance of the service:
    1. {: hide-dashboard} Go to the {{site.data.keyword.personalityinsightsshort}} External link icon{: new_window} page in the {{site.data.keyword.cloud_notm}} Catalog.
    2. {: hide-dashboard} Sign up for a free {{site.data.keyword.cloud_notm}} account or log in.
    3. {: hide-dashboard} Click Create.
  • Copy the credentials to authenticate to your service instance:
    1. {: hide-dashboard} From the {{site.data.keyword.cloud_notm}} dashboard External link icon{: new_window}, click on your {{site.data.keyword.personalityinsightsshort}} service instance to go to the {{site.data.keyword.personalityinsightsshort}} service dashboard page.
    2. On the Manage page, click Show to view your credentials.
    3. Copy the API Key and URL values.
  • Make sure that you have the curl command.
    • The examples use the curl command to call methods of the HTTP interface. Install the version for your operating system from curl.haxx.se External link icon{: new_window}. Install the version that supports the Secure Sockets Layer (SSL) protocol. Make sure to include the installed binary file on your PATH environment variable.

When you enter a command, replace {apikey} and {url} with your actual API key and URL. Omit the braces, which indicate a variable value, from the command. An actual value resembles the following example: {: hide-dashboard}

curl -X POST -u "apikey:L_HALhLVIksh1b73l97LSs6R_3gLo4xkujAaxm7i-b9x"
. . .
"https://gateway.watsonplatform.net/personality-insights/api/v3/profile?version=2017-10-13"

{:pre} {: hide-dashboard}

Step 1: Send plain text input and receive basic JSON output

{: #example1}

The first example passes the plain text file profile.txt to the POST /v3/profile method and requests a JSON response.

  1. Download the sample file profile.txt External link icon.

  2. Issue the following command to send the file to the /v3/profile method and request a JSON response.

    • The Content-Type header specifies that the input is plain text, text/plain. The charset parameter included with the header identifies the character encoding of the input text.
    • The Accept header specifies application/json to indicate that JSON output is requested.
    • {: hide-dashboard} Replace {apikey} and {url} with your information.
    • Modify {path_to_file} to specify the location of the profile.txt file.
    curl -X POST -u "apikey:{apikey}"{: apikey} \
--header "Content-Type: text/plain;charset=utf-8" \
--header "Accept: application/json" \
--data-binary @{path_to_file}profile.txt \
"{url}/v3/profile?version=2017-10-13"{: url}

    {: pre}

The service returns a JSON Profile object that includes 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. For more information, see The Profile object.

The profile includes information about the Big Five personality, Needs, and Values characteristics for the author as inferred from the input text. The service reports a percentile, or normalized score, for each characteristic. The service computes the percentile by comparing the author's results with the results from a sample population. For more information, see Personality characteristics output.

Step 2: Send JSON input and receive detailed JSON output

{: #example2}

The second example passes the JSON file profile.json to the /v3/profile method, again requesting a JSON response. The example requests consumption preferences and raw scores for a more detailed analysis of the input.

  1. Download the sample file profile.json External link icon, which contains a collection of Twitter messages.

  2. Issue the following command to send the file to the /v3/profile method. The example specifies application/json for the Content-Type and Accept headers; the charset parameter is not needed for JSON input. The example sets the consumption_preferences and raw_scores query parameters to true.

    curl -X POST -u "apikey:{apikey}"{: apikey} \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data-binary @{path_to_file}profile.json \
"{url}/v3/profile?version=2017-10-13&consumption_preferences=true&raw_scores=true"{: url}

    {: pre}

The service returns a JSON profile that includes the metadata and characteristics returned with the previous 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 on each day of the week and hour of the day. For more information, see Behavioral output.

The service also reports scores for its collection of consumption preferences. The scores indicate the author's likelihood to prefer different products, services, and activities based on the inferred characteristics. For more information, see Consumption preferences output.

Step 3: Send JSON input and receive detailed CSV output

{: #example3}

The third example is 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. It uses 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.

  1. Issue the following command to send the JSON file to the /v3/profile method. The Content-Type header identifies the input content as application/json, and the Accept header requests CSV output, text/csv.

    curl -X POST -u "apikey:{apikey}"{: apikey} \
--header "Content-Type: application/json" \
--header "Accept: text/csv" \
--data-binary @{path_to_file}profile.json \
--output profile.csv \
"{url}/v3/profile?version=2017-10-13&consumption_preferences=true&raw_scores=true&csv_headers=true"{: url}

    {: pre}

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

Next steps

{: #gsns}