Example GET Request

An example GET request we can make to use the Sentiment Analysis API looks like this (replace # with API key):

Pretty intimidating, right? While the URL may look like esoteric gibberish, it’s actually packed with meaningful information we can use to make calls to the API.

Let’s break it down into its individual components:

GET Request Components

• https://watson-api-explorer.mybluemix.net: this is the protocol and hostname of the API URL.


• /alchemy-api: this is the name of the specific API we want to access.


• /calls: every time we want to access data from an application, we make calls to the API. After /calls, we specify the source of that data.


• /url: we must specify the source of the sentiment information we will be analyzing (a webpage, HTML document, or plain text) by appending either url, html, or text after /calls/. In our example, we will be analyzing an article at a particular URL, so we will append /url to /calls.


• /URLGetTextSentiment: In order to construct an API call, we must first decide which API Endpoint we want. An endpoint is the URL where your service can be accessed by the client application. Our operation consists of analyzing the sentiment of an article at a given URL. Befittingly, the endpoint for our API call is called URLGetTextSentiment. The URLGetTextSentiment call is utilized to extract positive/negative sentiment from a given web page. AlchemyLanguage will download the requested URL, extracting text from the HTML document structure (ignoring navigation links, advertisements, and other undesirable content), and perform sentiment extraction operations.
  
  

  Immediately after the endpoint URL, we append a query string containing relevant parameters:

• ?apikey=#: your API key


• &url= http%3A%2F%2Fwww.theatlantic.com%2Fmagazine%2Farchive%2F2016%2F11%2F
  the-case-for-hillary-clinton-and-against-donald-trump%2F501161%2F:

  the URL of the source content to be analyzed.

  You may be wondering what %3A and %2F mean. URLs can only be sent over the Internet using the ASCII character-set. Since URLs often contain characters outside the ASCII set, the URL has to be converted into a valid ASCII format. URL encoding replaces unsafe ASCII characters with a "%" followed by two hexadecimal digits. In this case, the colon and slashes in the original link http://www.theatlantic.com/magazine/archive/2016/11/the-case-for-hillary-clinton-and-against-donald-trump/501161/ were replaced by a %3A and %2F’s, respectively. This encoding ensures that the URL can be used in the preparation of data with a Content-Type of application/x-www-form-urlencoded, as is often used in the submission of HTML form data in HTTP requests.

Now that we have our source URL and API key in the query string, we have all the required parameters necessary to send a valid GET request.

But wait. What about &outputMode=json and &showSourceText=0 ?

These are optional parameters. Optional parameters can be appended to our GET request, allowing us to further customize what data gets accessed and how. In order to use any of these parameters, we simply add the parameter key-value pair to the GET request as such: &key=value

Optional Parameters

Optional parameters include:

• outputMode: desired response format. xml or json (default).


• showSourceText: set this to 1 to include the source text in the response.


• cquery: a visual constraints query to apply to the web page.


• sourceText: how to obtain the source text from the webpage (default cleaned_or_raw). Read the Parameters section of this article for more info.

In our example GET request, we have &outputMode=json and &showSourceText=0. Based off the values of our optional parameters, we now know that we will be receiving a response in JSON format and the source text will not be included in the response