Watson Developer Cloud

Menu

Curl Node Java Python

AlchemyLanguage
API Reference

Introduction

The IBM Watson™ AlchemyLanguage service is a collection of text analysis functions that derive semantic information from your content. You can input text, HTML, or a public URL and leverage sophisticated natural language processing techniques to get a quick high-level understanding of your content and obtain detailed insights such as sentiment for detected entities and keywords. See a video overview of the service here.

Before HTML documents or webpages are analyzed, AlchemyLanguage removes ads, headers, and other unwanted text by default, leaving only the most important source text for the analysis.

Maximum size of requested or posted HTML documents: 600 KB
Maximum size of source text after page cleaning: 50 KB

Watson Developer Cloud SDKs:

API Endpoint

https://gateway-a.watsonplatform.net/calls

Important: If you have Bluemix Dedicated, this may not be your service endpoint. Double check your endpoint URL on the Service Credentials page in your instance of the AlchemyLanguage Service on Bluemix.

Node

npm install watson-developer-cloud

Maven

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

Gradle

compile 'com.ibm.watson.developer_cloud:java-sdk:3.0.0-RC1'

Python

pip install --upgrade watson-developer-cloud

Authentication

You authenticate to the AlchemyLanguage API by passing an API key as a query parameter in each call.

To get an API key, you'll need to sign up for IBM Bluemix. After you create an account: 


curl "https://gateway-a.watsonplatform.net/calls/url/URLGetAuthors?apikey=API_KEY&url=www.ibm.com"
            

var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
});
            

AlchemyLanguage service = new AlchemyLanguage();
service.setApiKey("API_KEY");
            

import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')

Methods

Combined Call

HTML URL Text

Analyze an HTML file with multiple text analysis operations.

Analyze a webpage with multiple text analysis operations.

Analyze plain text with multiple text analysis operations.

Analyze text, HTML, or webpage content with multiple text analysis operations.

For example, if you want to get entity and keyword information from the same source, you can do it in a single call. Specify any of the available methods in the extract parameter to enable them in the analysis. Any charges that apply to the individual methods used will be reflected in the combined request.

Any parameters for the extract methods can also be passed. You can refer to their corresponding sections of the reference to see the options that are available. For example, you can enable targeted sentiment information for entities and keywords by passing sentiment=1. Since this parameter incurs additional transaction charges and applies to both entities and keywords, the request will incur 2 additional transaction charges. 

POST /html/HTMLGetCombinedDataGET /url/URLGetCombinedData
POST /url/URLGetCombinedDataPOST /text/TextGetCombinedData
combined(parameters, callback)
combined(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
extract query Comma separated list of any of the following methods:
  • authors
  • concepts (default)
  • dates
  • doc-emotion
  • entities (default)
  • feeds
  • keywords (default)
  • pub-date
  • relations
  • typed-rels
  • doc-sentiment
  • taxonomy (default)
  • title
outputMode query json or xml (default)
showSourceText query Set this to 1 to include the source text in the response
jsonp query Desired JSONP callback (requires outputMode to be set to json)

Example request


  curl -X POST -d "outputMode=json" -d "extract=entities,keywords" -d "sentiment=1" -d "maxRetrieve=1" -d "url=https://www.ibm.com/us-en/" "https://gateway-a.watsonplatform.net/calls/url/URLGetCombinedData?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
extract query Comma separated list of any of the following methods:
  • authors
  • concepts (default)
  • dates
  • doc-emotion
  • entities (default)
  • feeds
  • keywords (default)
  • pub-date
  • relations
  • typed-rels
  • doc-sentiment
  • taxonomy (default)
  • title
outputMode query json or xml (default)
showSourceText query Set this to 1 to include the source text in the response
jsonp query Desired JSONP callback (requires outputMode to be set to json)

Example request


  curl -X POST --data-urlencode html@ibm_site.html -d "outputMode=json" -d "extract=entities,keywords" -d "sentiment=1" -d "maxRetrieve=1" -d "url=https://www.ibm.com/us-en/" "https://gateway-a.watsonplatform.net/calls/html/HTMLGetCombinedData?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
text query (Required) Text content (must be URL encoded)
extract query Comma separated list of any of the following methods:
  • authors
  • concepts (default)
  • dates
  • doc-emotion
  • entities (default)
  • feeds
  • keywords (default)
  • pub-date
  • relations
  • typed-rels
  • doc-sentiment
  • taxonomy (default)
  • title
outputMode query json or xml (default)
showSourceText query Set this to 1 to include the source text in the response
jsonp query Desired JSONP callback (requires outputMode to be set to json)

Example request


  curl -X POST --data-urlencode text@ibm_site.txt -d "outputMode=json" -d "extract=entities,keywords" -d "sentiment=1" -d "maxRetrieve=1" -d "url=https://www.ibm.com/us-en/" "https://gateway-a.watsonplatform.net/calls/text/TextGetCombinedData?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
extract string Comma separated list of any of the following methods:
  • authors
  • concepts (default)
  • dates
  • doc-emotion
  • entities (default)
  • feeds
  • keywords (default)
  • pub-date
  • relations
  • typed-rels
  • doc-sentiment
  • taxonomy (default)
  • title
outputMode string xml or json (default)
showSourceText integer Set this to 1 to include the source text in the response

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  extract: 'entities,keywords',
  sentiment: 1,
  maxRetrieve: 1,
  url: 'https://www.ibm.com/us-en/'
};

alchemy_language.combined(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Parameter Type Description
api_key string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
extract string Comma separated list of any of the following methods:
  • authors
  • concepts (default)
  • dates
  • doc-emotion
  • entities (default)
  • feeds
  • keywords (default)
  • pub-date
  • relations
  • typed-rels
  • doc-sentiment
  • taxonomy (default)
  • title
max_items integer The maximum number of results to return for each applicable extract operation
showSourceText integer Set this to 1 to include the source text in the response

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')

print(json.dumps(
  alchemy_language.combined(
    url='https://www.ibm.com/us-en/',
    extract='entities,keywords',
    sentiment=1,
    max_items=1),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
language Detected language of the source text (text with fewer than 15 characters is assumed to be English)
... Response fields unique to the methods included in the extract parameter will appear here. In the example shown, entities and keywords arrays are present in the response, and they share the same structure as those that are documented in the Entities and Keywords sections of the reference

Example response 


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "http://www.ibm.com/us-en/",
  "totalTransactions": "4",
  "language": "english",
  "keywords": [
    {
      "text": "NoSQL cloud database",
      "relevance": "0.940807",
      "sentiment": {
        "type": "positive",
        "score": "0.46058"
      }
    }
  ],
  "entities": [
    {
      "type": "Company",
      "relevance": "0.805754",
      "sentiment": {
        "type": "positive",
        "score": "0.526551"
      },
      "count": "4",
      "text": "IBM",
      "disambiguated": {
        "subType": [
          "SoftwareLicense",
          "OperatingSystemDeveloper",
          "ProcessorManufacturer",
          "SoftwareDeveloper",
          "CompanyFounder",
          "ProgrammingLanguageDesigner",
          "ProgrammingLanguageDeveloper"
        ],
        "name": "IBM",
        "website": "http://www.ibm.com/",
        "dbpedia": "http://dbpedia.org/resource/IBM",
        "freebase": "http://rdf.freebase.com/ns/m.03sc8",
        "opencyc": "http://sw.opencyc.org/concept/Mx4rvViMoJwpEbGdrcN5Y29ycA",
        "yago": "http://yago-knowledge.org/resource/IBM",
        "crunchbase": "http://www.crunchbase.com/company/ibm"
      }
    }
  ]
}

Authors

HTML URL

Get author names from an HTML document.

Get author names from a webpage.

Get author names from a webpage or HTML content. 

POST /html/HTMLGetAuthorsGET /url/URLGetAuthors
POST /url/URLGetAuthors
authors(parameters, callback)
authors(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
outputMode query json or xml (default)
jsonp query Desired JSONP callback (requires outputMode to be set to json)

Example request


  curl -X POST -d "outputMode=json" -d "url=http://techcrunch.com/2016/01/29/ibm-watson-weather-company-sale/" "https://gateway-a.watsonplatform.net/calls/url/URLGetAuthors?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
url query Input here will appear as the url value in the response.
outputMode query json or xml (default)
jsonp query Desired JSONP callback (requires outputMode to be set to json)

Example request


  curl -X POST -d "outputMode=json" --data-urlencode html@tech_crunch.html -d "url=http://techcrunch.com/2016/01/29/ibm-watson-weather-company-sale/" "https://gateway-a.watsonplatform.net/calls/html/HTMLGetAuthors?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url string One of these is required. Pass HTML content in html or a public facing URL in url
outputMode string xml or json (default)

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var fs = require('fs');
var parameters = {};
fs.readFile('example.html', 'utf8', function (err, data) {
  if (err) {
    return console.log(err);
  }
  parameters = {
    'html': data
  };
  alchemy_language.authors(parameters, function (error, response) {
    if (error)
      console.log('error:', error);
    else
      console.log(JSON.stringify(response, null, 2));
  })
});
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Parameter Type Description
api_key string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
showSourceText integer Set this to 1 to include the source text in the response

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')

print(json.dumps(
  alchemy_language.authors(
    url='https://www.ibm.com/us-en/'),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
authors List of extracted author names
statusInfo In addition to the general error messages, this can contain
author-not-found:cannot-locate

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "http://techcrunch.com/2016/01/29/ibm-watson-weather-company-sale/",
  "authors": {
    "names": [
      "Author Name 1",
      "Author Name 2"
    ]
  }
}

Concepts

HTML URL Text

Extract concepts from an HTML document.

Extract concepts from a webpage.

Extract concepts from plain text.

Extract concepts from a webpage, HTML, or plain text.

Supported languages: English, Spanish

POST /html/HTMLGetRankedConceptsPOST /url/URLGetRankedConceptsPOST /text/TextGetRankedConcepts
concepts(parameters, callback)
concepts(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
url query Input here will appear as the url value in the response.
maxRetrieve query Maximum number of concepts to extract (default = 8, maximum = 50)
outputMode query json, rdf, or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
knowledgeGraph query Set this to 1 to include knowledge graph information in the results
This incurs an additional transaction charge
linkedData query Set this to 0 to hide Linked Data content links in the response
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" -d "knowledgeGraph=1" --data-urlencode html@ibm_watson.html -d "url=http://www.ibm.com/watson/" "https://gateway-a.watsonplatform.net/calls/html/HTMLGetRankedConcepts?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
maxRetrieve query Maximum number of concepts to extract (default = 8, maximum = 50)
outputMode query json, rdf, or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
knowledgeGraph query Set this to 1 to include knowledge graph information in the results
This incurs an additional transaction charge
linkedData query Set this to 0 to hide Linked Data content links in the response
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" -d "knowledgeGraph=1" -d "url=http://www.ibm.com/watson/" "https://gateway-a.watsonplatform.net/calls/url/URLGetRankedConcepts?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
text query (Required) Text content (must be URL encoded)
url query Input here will appear as the url value in the response.
maxRetrieve query Maximum number of concepts to extract (default = 8, maximum = 50)
outputMode query json, rdf, or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
knowledgeGraph query Set this to 1 to include knowledge graph information in the results
This incurs an additional transaction charge
linkedData query Set this to 0 to hide Linked Data content links in the response
showSourceText query Set this to 1 to include the source text in the response

Example request


curl -X POST -d "outputMode=json" -d "knowledgeGraph=1" --data-urlencode text@ibm_watson.txt -d "url=http://www.ibm.com/watson/" "https://gateway-a.watsonplatform.net/calls/text/TextGetRankedConcepts?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
maxRetrieve integer Maximum number of concepts to extract (default = 8, maximum = 50)
outputMode string xml or json (default)
knowledgeGraph integer Set this to 1 to include knowledge graph information in the results
This incurs an additional transaction charge
linkedData integer Set this to 0 to hide Linked Data content links in the response
showSourceText integer Set this to 1 to include the source text in the response
cquery string A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath string An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText string How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  url: 'http://www.ibm.com/watson',
  knowledgeGraph: 1
};

alchemy_language.concepts(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Parameter Type Description
api_key string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
max_items integer Maximum number of concepts to extract (default = 8, maximum = 50)
knowledge_graph integer Set this to 1 to include knowledge graph information in the results
This incurs an additional transaction charge
linked_data integer Set this to 0 to hide Linked Data content links in the response
show_source_text integer Set this to 1 to include the source text in the response

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')

print(json.dumps(
  alchemy_language.concepts(
    url='https://www.ibm.com/watson/',
    knowledgeGraph=1),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
language Detected language of the source text (text with fewer than 15 characters is assumed to be English)
concepts Array of detected concepts
text The detected concept
relevance Relevance score for a detected concept (0.0 - 1.0, 1.0 = most relevant)
knowledgeGraph Path through the knowledge graph to the appropriate keyword. Returned when the knowledgeGraph parameter is set to 1
... Linked data properties will also appear by default. You can hide these properties by setting linkedData to 0

Example response


{
    "status": "OK",
    "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
    "url": "http://www.ibm.com/watson/",
    "totalTransactions": "2",
    "language": "english",
    "concepts": [
        {
            "text": "Thomas J. Watson",
            "relevance": "0.926128",
            "knowledgeGraph": {
                "typeHierarchy": "/people/thomas j. watson"
            },
            "dbpedia": "http://dbpedia.org/resource/Thomas_J._Watson",
            "freebase": "http://rdf.freebase.com/ns/m.07qkt",
            "yago": "http://yago-knowledge.org/resource/Thomas_J._Watson"
        },
        {
            "text": "Science",
            "relevance": "0.902652",
            "knowledgeGraph": {
                "typeHierarchy": "/fields/subjects/science"
            },
            "dbpedia": "http://dbpedia.org/resource/Science",
            "freebase": "http://rdf.freebase.com/ns/m.06mq7",
            "opencyc": "http://sw.opencyc.org/concept/Mx4rwKQK2JwpEbGdrcN5Y29ycA"
        },
        ...
    ]
}

Date Extraction

HTML URL Text

Extract dates from an HTML document.

Extract dates from a webpage.

Extract dates from plain text.

Extract dates from a webpage, HTML, or plain text.

Supported languages: English 

POST /html/HTMLExtractDatesGET /url/URLExtractDates
POST /url/URLExtractDatesPOST /text/TextExtractDates
dates(parameters, callback)
dates(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
anchorDate query The date to use as "today" when interpreting phrases in the text like "next tuesday."
Format: yyyy-mm-dd hh:mm:ss
outputMode query json, rdf, xml (default), rel-tag, or rel-tag-raw
jsonp query JSONP callback (requires outputMode to be set to json)
showSourceText query Set this to 1 to include the source text in the response
url query Input here will appear as the url value in the response.

Example request


        curl -X POST -d "outputMode=json" --data-urlencode html@ibm_press.html "https://gateway-a.watsonplatform.net/calls/html/HTMLExtractDates?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
anchorDate query The date to use as "today" when interpreting phrases in the text like "next tuesday."
Format: yyyy-mm-dd hh:mm:ss
outputMode query json, rdf, xml (default), rel-tag, or rel-tag-raw
jsonp query JSONP callback (requires outputMode to be set to json)
showSourceText query Set this to 1 to include the source text in the response

Example request


        curl -X POST -d "outputMode=json" --data-urlencode "url=ibm.com/press" "https://gateway-a.watsonplatform.net/calls/url/URLExtractDates?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
text query (Required) Text content (must be URL encoded)
anchorDate query The date to use as "today" when interpreting phrases in the text like "next tuesday."
Format: yyyy-mm-dd hh:mm:ss
outputMode query json, rdf, xml (default), rel-tag, or rel-tag-raw
jsonp query JSONP callback (requires outputMode to be set to json)
showSourceText query Set this to 1 to include the source text in the response

Example request


        curl -X POST -d "outputMode=json" -d "text=Set a reminder for my appointment next Tuesday" --data-urlencode "anchorDate=2016-03-22 00:00:00" "https://gateway-a.watsonplatform.net/calls/text/TextExtractDates?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
anchorDate string The date to use as "today" when interpreting phrases in the text like "next tuesday."
Format: yyyy-mm-dd hh:mm:ss
outputMode string xml or json (default)
showSourceText integer Set this to 1 to include the source text in the response

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  text: 'Set a reminder for my appointment next Tuesday',
  anchorDate: '2016-03-22 00:00:00'
};

alchemy_language.dates(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Coming soon.

Example request

Example coming soon.
Parameter Type Description
api_key string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
anchor_date string The date to use as "today" when interpreting phrases in the text like "next tuesday."
Format: yyyy-mm-dd hh:mm:ss
show_source_text integer Set this to 1 to include the source text in the response

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')
print(json.dumps(
  alchemy_language.dates(
    text='Set a reminder for my appointment next Tuesday',
    anchor_date='2016-03-22 00:00:00'),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP url sent in the input
language Detected language of the source text (text with fewer than 15 characters is assumed to be English)
text Source text of the document. Appears when showSourceText is set to 1
dates Array of extracted date objects, each containing a date in yyyymmddThhmmss format and text from the source that corresponds to the date

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "http://www-03.ibm.com/press/us/en/index.wss",
  "totalTransactions": "1",
  "language": "english",
  "dates": [
    {
      "date": "20160318T000000",
      "text": "2016-03-18"
    },
    {
      "date": "20160317T000000",
      "text": "2016-03-17"
    },
    ...
  ]
}

{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "totalTransactions": "1",
  "language": "english",
  "dates": [
    {
      "date": "20160329T000000",
      "text": "next tuesday"
    }
  ]
}
                

{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "totalTransactions": "1",
  "language": "english",
  "dates": [
    {
      "date": "20160329T000000",
      "text": "next tuesday"
    }
  ]
}

Emotion Analysis

HTML URL Text

Detect emotions implied in the text of an HTML document.

Detect emotions implied in the text on a webpage.

Detect emotions implied in plain text.

Detect emotions implied in plain text, on a webpage, or in HTML content.

Supported languages: English 

POST /html/HTMLGetEmotionGET /url/URLGetEmotion
POST /url/URLGetEmotionPOST /text/TextGetEmotion
emotion(parameters, callback)
emotion(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
url query Input here will appear as the url value in the response.
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" --data-urlencode html@chaplin_speech.html -d "url=http://www.charliechaplin.com/en/synopsis/articles/29-The-Great-Dictator-s-Speech" "https://gateway-a.watsonplatform.net/calls/html/HTMLGetEmotion?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" -d "url=http://www.charliechaplin.com/en/synopsis/articles/29-The-Great-Dictator-s-Speech" "https://gateway-a.watsonplatform.net/calls/url/URLGetEmotion?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
text query (Required) Text content (must be URL encoded)
url query Input here will appear as the url value in the response.
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
showSourceText query Set this to 1 to include the source text in the response

Example request


curl -X POST -d "outputMode=json" --data-urlencode text@chaplin_speech.txt -d "url=http://www.charliechaplin.com/en/synopsis/articles/29-The-Great-Dictator-s-Speech" "https://gateway-a.watsonplatform.net/calls/text/TextGetEmotion?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
outputMode string xml or json (default)
showSourceText integer Set this to 1 to include the source text in the response

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  url: 'http://www.charliechaplin.com/en/synopsis/articles/29-The-Great-Dictator-s-Speech'
};

alchemy_language.emotion(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Parameter Type Description
api_key string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
show_source_text integer Set this to 1 to include the source text in the response
constraint_query string A visual constraints query to apply to the web page. Required when source_text is set to cquery
xpath_query integer An XPath query to apply to the web page. Required when source_text is set to one of the XPath values
source_text query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')
print(json.dumps(
  alchemy_language.emotion(
    url='charliechaplin.com/en/synopsis/articles/29-The-Great-Dictator-s-Speech'),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
language Detected language of the source text (text with fewer than 15 characters is assumed to be English)
text Source text of the document. Appears when showSourceText is set to 1
docEmotions Object containing emotion keys and score values (0.0 to 1.0). If a score is above 0.5, then the text can be classified as conveying the corresponding emotion.

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "http://www.charliechaplin.com/en/synopsis/articles/29-The-Great-Dictator-s-Speech",
  "totalTransactions": "0",
  "language": "english",
  "docEmotions": {
    "anger": "0.639028",
    "disgust": "0.009711",
    "fear": "0.037295",
    "joy": "4e-05",
    "sadness": "0.002552"
  }
}

Targeted Emotion

HTML URL Text

Detect emotions directed toward targeted phrases in an HTML document.

Detect emotions directed toward targeted phrases on a webpage.

Detect emotions directed toward targeted phrases in text.

Detect emotions directed toward targeted phrases in your content.

Targeted Emotion searches your content for up to 20 targets, and uses context to analyze emotions associated with each phrase. You can analyze emotions for keywords and entities by passing an emotion=1 parameter when you use the respective API methods, or when you extract keywords and entities in a Combined Call.

Supported languages: English 

POST /html/HTMLGetTargetedEmotionGET /url/URLGetTargetedEmotion
POST /url/URLGetTargetedEmotionPOST /text/TextGetTargetedEmotion
emotion(parameters, callback)

Request

Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
targets query (Required) phrase1|phrase2|...
Pipe delimited list of phrases. The service will analyze emotion for each phrase that is found in the source text. Supports up to 20 phrases.
url query Input here will appear as the url value in the response.
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" --data-urlencode html@cnn_example.html -d "targets=Clinton|Trump" -d "url=http://www.cnn.com" "https://gateway-a.watsonplatform.net/calls/html/HTMLGetTargetedEmotion?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
targets query (Required) phrase1|phrase2|...
Pipe delimited list of phrases. The service will analyze emotion directed toward each phrase that is found in the source text. Supports up to 20 phrases.
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" -d "targets=Clinton|Trump" -d "url=http://www.cnn.com" "https://gateway-a.watsonplatform.net/calls/url/URLGetTargetedEmotion?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
text query (Required) Text content (must be URL encoded)
targets query (Required) phrase1|phrase2|...
Pipe delimited list of phrases. The service will analyze emotion directed toward each phrase that is found in the source text. Supports up to 20 phrases.
url query Input here will appear as the url value in the response.
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
showSourceText query Set this to 1 to include the source text in the response

Example request


curl -X POST -d "outputMode=json" -d "text=I love apples! I don't like bananas." -d "targets=apples|bananas" "https://gateway-a.watsonplatform.net/calls/text/TextGetTargetedEmotion?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
targets string phrase1|phrase2|...
Pipe delimited list of phrases. The service will analyze emotion directed toward each phrase that is found in the source text. Supports up to 20 phrases.
outputMode string xml or json (default)
showSourceText integer Set this to 1 to include the source text in the response

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  text: 'I love apples! I do not like bananas.',
  targets: 'apples|bananas'
};

alchemy_language.emotion(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
language Detected language of the source text (text with fewer than 15 characters is assumed to be English)
text Source text of the document. Appears when showSourceText is set to 1
results Array of result objects. Each result contains the text of the detected target, and an object containing scores for anger, disgust, fear, joy, and sadness. The higher the score, the more likely the emotion is associated with the target phrase.

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http: //www.alchemyapi.com / company / terms.html ",
  "url": "http://www.cnn.com/",
  "totalTransactions": "1",
  "language": "english",
  "results": [
    {
      "emotions": {
        "anger": "0.156846",
        "disgust": "0.299988",
        "fear": "0.367965",
        "joy": "0.250093",
        "sadness": "0.438412"
      },
      "text": "Clinton"
    },
    {
      "emotions": {
        "anger": "0.116643",
        "disgust": "0.309158",
        "fear": "0.367396",
        "joy": "0.22114",
        "sadness": "0.55768"
      },
      "text": "Trump"
    }
  ]
}
              

{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http: //www.alchemyapi.com / company / terms.html ",
  "url": "http://www.example.com",
  "totalTransactions": "1",
  "language": "english",
  "results": [
    {
      "emotions": {
        "anger": "0.314547",
        "disgust": "0.037708",
        "fear": "0.178313",
        "joy": "0.467821",
        "sadness": "0.251207"
      },
      "text": "apples"
    },
    {
      "emotions": {
        "anger": "0.134035",
        "disgust": "0.467529",
        "fear": "0.289981",
        "joy": "0.062265",
        "sadness": "0.559433"
      },
      "text": "bananas"
    }
  ]
}

{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http: //www.alchemyapi.com / company / terms.html ",
  "url": "http://www.example.com",
  "totalTransactions": "1",
  "language": "english",
  "results": [
    {
      "emotions": {
        "anger": "0.314547",
        "disgust": "0.037708",
        "fear": "0.178313",
        "joy": "0.467821",
        "sadness": "0.251207"
      },
      "text": "apples"
    },
    {
      "emotions": {
        "anger": "0.134035",
        "disgust": "0.467529",
        "fear": "0.289981",
        "joy": "0.062265",
        "sadness": "0.559433"
      },
      "text": "bananas"
    }
  ]
}

Entities

HTML URL Text

Extract entities from an HTML document.

Extract entities from a webpage.

Extract entities from plain text.

Extract entities from a webpage, HTML, or plain text.

Get the full list of standard entity types (sheet 1) and subtypes (sheet 2): XLS

To tailor results for your domain, you can create your own custom models for entity extraction with Watson Knowledge Studio.

Supported languages: English, French, German, Italian, Portuguese, Russian, Spanish, Swedish 

POST /html/HTMLGetRankedNamedEntitiesGET /url/URLGetRankedNamedEntities
POST /url/URLGetRankedNamedEntitiesPOST /text/TextGetRankedNamedEntities
entities(parameters, callback)
entities(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
maxRetrieve query Maximum number of entities to return (default = 50)
model query Specify a custom model ID here to override the default Alchemy entity extraction model. You can also choose from the following public models:
  • en-news: trained on English news content
  • es-news: trained on Spanish news content
  • ar-news: trained on Arabic news content
Note: input text is truncated to 5 KB for custom models calls
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
url query Input here will appear as the url value in the response.
coreference query Set this to 0 to treat coreferences as separate entities (coreferences are resolved into detected entities by default)
disambiguate query Set this to 0 to hide entity disambiguation information in the response
knowledgeGraph query Set this to 1 to include knowledge graph information in the results
This incurs an additional transaction charge
linkedData query Set this to 0 to hide Linked Data content links in the response
quotations query Set this to 1 to include quotations that are linked to detected entities
emotion query Set this to 1 to analyze emotions associated with each detected entity
This incurs an additional transaction charge
sentiment query Set this to 1 to analyze the sentiment towards each detected entity
This incurs an additional transaction charge
showSourceText query Set this to 1 to include the source text in the response
structuredEntities query Set this to 0 to ignore structured entities, such as Quantity, EmailAddress, TwitterHandle, Hashtag, and IPAddress
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" --data-urlencode html@ibm_press_release.html -d "url=http://www-03.ibm.com/press/us/en/pressrelease/49384.wss" "https://gateway-a.watsonplatform.net/calls/html/HTMLGetRankedNamedEntities?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
maxRetrieve query Maximum number of entities to return (default = 50)
model query Specify a custom model ID here to override the default Alchemy entity extraction model. You can also choose from the following public models:
  • en-news: trained on English news content
  • es-news: trained on Spanish news content
  • ar-news: trained on Arabic news content
Note: input text is truncated to 5 KB for custom models calls
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
coreference query Set this to 0 to treat coreferences as separate entities (coreferences are resolved into detected entities by default)
disambiguate query Set this to 0 to hide entity disambiguation information in the response
knowledgeGraph query Set this to 1 to include knowledge graph information in the results
This incurs an additional transaction charge
linkedData query Set this to 0 to hide Linked Data content links in the response
quotations query Set this to 1 to include quotations that are linked to detected entities
emotion query Set this to 1 to analyze emotions associated with each detected entity
This incurs an additional transaction charge
sentiment query Set this to 1 to analyze the sentiment towards each detected entity
This incurs an additional transaction charge
showSourceText query Set this to 1 to include the source text in the response
structuredEntities query Set this to 0 to ignore structured entities, such as Quantity, EmailAddress, TwitterHandle, Hashtag, and IPAddress
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" -d "maxRetrieve=3" -d "url=http://www-03.ibm.com/press/us/en/pressrelease/49384.wss" "https://gateway-a.watsonplatform.net/calls/url/URLGetRankedNamedEntities?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
text query (Required) Text content (must be URL encoded)
maxRetrieve query Maximum number of entities to return (default = 50)
model query Specify a custom model ID here to override the default Alchemy entity extraction model. You can also choose from the following public models:
  • en-news: trained on English news content
  • es-news: trained on Spanish news content
  • ar-news: trained on Arabic news content
Note: input text is truncated to 5 KB for custom models calls
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
coreference query Set this to 0 to treat coreferences as separate entities (coreferences are resolved into detected entities by default)
disambiguate query Set this to 0 to hide entity disambiguation information in the response
knowledgeGraph query Set this to 1 to include knowledge graph information in the results
This incurs an additional transaction charge
linkedData query Set this to 0 to hide Linked Data content links in the response
quotations query Set this to 1 to include quotations that are linked to detected entities
emotion query Set this to 1 to analyze emotions associated with each detected entity
This incurs an additional transaction charge
sentiment query Set this to 1 to analyze the sentiment towards each detected entity
This incurs an additional transaction charge
showSourceText query Set this to 1 to include the source text in the response
structuredEntities query Set this to 0 to ignore structured entities, such as Quantity, EmailAddress, TwitterHandle, Hashtag, and IPAddress

Example request


curl -X POST -d "outputMode=json" --data-urlencode text@ibm_press_release.txt -d "url=http://www-03.ibm.com/press/us/en/pressrelease/49384.wss" "https://gateway-a.watsonplatform.net/calls/text/TextGetRankedNamedEntities?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
max_items integer Maximum number of entities to return (default = 50)
model string Specify a custom model ID here to override the default Alchemy entity extraction model. You can also choose from the following public models:
  • en-news: trained on English news content
  • es-news: trained on Spanish news content
  • ar-news: trained on Arabic news content
Note: input text is truncated to 5 KB for custom models calls
coreference integer Set this to 0 to treat coreferences as separate entities (coreferences are resolved into detected entities by default)
showSourceText integer Set this to 1 to include the source text in the response
knowledgeGraph integer Set this to 1 to include knowledge graph information in the results
This incurs an additional transaction charge
linked_data integer Set this to 0 to hide Linked Data content links in the response
quotations integer Set this to 1 to include quotations that are linked to detected entities
emotion integer Set this to 1 to analyze emotions associated with each detected entity
This incurs an additional transaction charge
sentiment integer Set this to 1 to analyze the sentiment towards each detected entity. This incurs an additional transaction charge
structuredEntities integer Set this to 0 to ignore structured entities, such as Quantity, EmailAddress, TwitterHandle, Hashtag, and IPAddress
cquery string A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath string An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText string How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  url: 'http://www-03.ibm.com/press/us/en/pressrelease/49384.wss'
};

alchemy_language.entities(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Parameter Type Description
api_key string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
max_items integer Maximum number of entities to return (default = 50)
model string Specify a custom model ID here to override the default Alchemy entity extraction model. You can also choose from the following public models:
  • en-news: trained on English news content
  • es-news: trained on Spanish news content
  • ar-news: trained on Arabic news content
Note: input text is truncated to 5 KB for custom models calls
outputMode string xml or json (default)
coreference integer Set this to 0 to treat coreferences as separate entities (coreferences are resolved into detected entities by default)
show_source_text integer Set this to 1 to include the source text in the response
linked_data integer Set this to 0 to hide Linked Data content links in the response
quotations integer Set this to 1 to include quotations that are linked to detected entities
emotion integer Set this to 1 to analyze emotions associated with each detected entity
This incurs an additional transaction charge
sentiment integer Set this to 1 to analyze the sentiment towards each detected entity. This incurs an additional transaction charge

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')
print(json.dumps(
  alchemy_language.entities(
    url='http://www-03.ibm.com/press/us/en/pressrelease/49384.wss'),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
language Detected language of the source text (text with fewer than 15 characters is assumed to be English)
entities Array of detected entity objects
type Detected entity type
relevance Relevance score for a detected entity (0.0 - 1,0)
count Number of times the entity was identified within the source text
text The detected entity text
disambiguated Disambiguation information for the detected entity. You can set disambiguate to 0 to hide this information. Set linkedData to 0 to hide the links to Linked Data resources.
quotations Extracted quotations for the detected entity. Set quotations to 1 to return this information
sentiment Sentiment Analysis results for the detected entity. Set sentiment to 1 to return this information
knowledgeGraph Path through the knowledge graph to the appropriate keyword. Set knowledgeGraph to 1 to return this information

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "http://www-03.ibm.com/press/us/en/pressrelease/49384.wss",
  "language": "english",
  "entities": [
    {
      "type": "Company",
      "relevance": "0.89792",
      "count": "12",
      "text": "IBM Cloud"
    },
    {
      "type": "Company",
      "relevance": "0.590382",
      "count": "13",
      "text": "IBM",
      "disambiguated": {
        "subType": [
          "SoftwareLicense",
          "OperatingSystemDeveloper",
          "ProcessorManufacturer",
          "SoftwareDeveloper",
          "CompanyFounder",
          "ProgrammingLanguageDesigner",
          "ProgrammingLanguageDeveloper"
        ],
        "name": "IBM",
        "website": "http://www.ibm.com/",
        "dbpedia": "http://dbpedia.org/resource/IBM",
        "freebase": "http://rdf.freebase.com/ns/m.03sc8",
        "opencyc": "http://sw.opencyc.org/concept/Mx4rvViMoJwpEbGdrcN5Y29ycA",
        "yago": "http://yago-knowledge.org/resource/IBM",
        "crunchbase": "http://www.crunchbase.com/company/ibm"
      }
    },
    {
      "type": "Facility",
      "relevance": "0.252495",
      "count": "1",
      "text": "London Bluemix Garage"
    }
  ]
}

Feed Detection

HTML URL

Extract RSS/ATOM feed links from an HTML document.

Extract RSS/ATOM feed links from a webpage.

Extract RSS/ATOM feed links from a webpage or HTML. 

POST /html/HTMLGetFeedLinksGET /url/URLGetFeedLinks
POST /url/URLGetFeedLinks
feeds(parameters, callback)
feeds(parameter=value,...)
-

Request

Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
url query Input here will appear as the url value in the response.

Example request


curl -X POST -d "outputMode=json" --data-urlencode html@hacker_news.html -d "url=http://news.ycombinator.com/" "https://gateway-a.watsonplatform.net/calls/html/HTMLGetFeedLinks?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)

Example request


curl -X POST -d "outputMode=json" -d "url=http://news.ycombinator.com" "https://gateway-a.watsonplatform.net/calls/url/URLGetFeedLinks?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
outputMode string xml or json (default)

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  url: 'http://news.ycombinator.com'
};

alchemy_language.feeds(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Parameter Type Description
api_key string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')
print(json.dumps(
  alchemy_language.feeds(
    url='news.ycombinator.com'),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
feeds Array of detected feed objects

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "https://news.ycombinator.com/",
  "feeds": [
    {
      "feed": "https://news.ycombinator.com/rss"
    }
  ]
}

Keywords

HTML URL Text

Extract keywords from an HTML document.

Extract keywords from a webpage.

Extract keywords from plain text.

Extract keywords from a webpage, HTML, or plain text.

Supported languages: English, French, German, Italian, Portuguese, Russian, Spanish, Swedish 

POST /html/HTMLGetRankedKeywordsGET /url/URLGetRankedKeywords
POST /url/URLGetRankedKeywordsPOST /text/TextGetRankedKeywords
keywords(parameters, callback)
keywords(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
url query Input here will appear as the url value in the response.
maxRetrieve query Maximum number of keywords to return (default = 50)
knowledgeGraph query Set this to 1 to include knowledge graph information in the results
This incurs an additional transaction charge
emotion query Set this to 1 to analyze emotions associated with each detected entity
This incurs an additional transaction charge
sentiment query Set this to 1 to analyze the sentiment towards each detected entity
This incurs an additional transaction charge
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" --data-urlencode html@watson_twitter.html -d "url=http://mobile.twitter.com/ibmwatson" "https://gateway-a.watsonplatform.net/calls/html/HTMLGetRankedKeywords?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
maxRetrieve query Maximum number of entities to return (default = 50)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
knowledgeGraph query Set this to 1 to include knowledge graph information in the results
This incurs an additional transaction charge
emotion query Set this to 1 to analyze emotions associated with each detected entity
This incurs an additional transaction charge
sentiment query 1 or 0
Whether to perform sentiment analysis for each keyword (default = 0: disabled)
This incurs an additional transaction charge
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" -d "url=http://www.twitter.com/ibmwatson" "https://gateway-a.watsonplatform.net/calls/url/URLGetRankedKeywords?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
text query (Required) Text content (must be URL encoded)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
url query Input here will appear as the url value in the response.
maxRetrieve query Maximum number of entities to return (default = 50)
knowledgeGraph query Set this to 1 to include knowledge graph information in the results
This incurs an additional transaction charge
emotion query Set this to 1 to analyze emotions associated with each detected entity
This incurs an additional transaction charge
sentiment query Set this to 1 to analyze the sentiment towards each detected entity
This incurs an additional transaction charge
showSourceText query Set this to 1 to include the source text in the response

Example request


curl -X POST -d "outputMode=json" --data-urlencode text@watson_twitter.txt -d "url=http://mobile.twitter.com/ibmwatson" "https://gateway-a.watsonplatform.net/calls/text/TextGetRankedKeywords?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
outputMode string xml or json (default)
maxRetrieve integer Maximum number of keywords to return (default = 50)
knowledgeGraph integer Set this to 1 to include knowledge graph information in the results
This incurs an additional transaction charge
emotion integer Set this to 1 to analyze emotions associated with each detected entity
This incurs an additional transaction charge
sentiment integer Set this to 1 to analyze the sentiment towards each detected entity
This incurs an additional transaction charge
showSourceText integer Set this to 1 to include the source text in the response
cquery string A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath string An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText string How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  url: 'http://www.twitter.com/ibmwatson'
};

alchemy_language.keywords(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Parameter Type Description
api_key string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
show_source_text integer Set this to 1 to include the source text in the response
max_items integer Maximum number of keywords to return (default = 50)
emotion integer Set this to 1 to analyze emotions associated with each detected entity
This incurs an additional transaction charge
sentiment integer Set this to 1 to analyze the sentiment towards each detected entity
This incurs an additional transaction charge

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')
print(json.dumps(
  alchemy_language.keywords(
    url='twitter.com/ibmwatson'),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
language Detected language of the source text (text with fewer than 15 characters is assumed to be English)
keywords Array of detected keyword objects
relevance Relevance score for a detected keyword (0.0 - 1.0, 1.0 = most relevant)
text Detected keyword text
knowledgeGraph Path through the knowledge graph to the appropriate keyword. Returned when the knowledgeGraph parameter is set to 1
sentiment Sentiment Analysis results for the detected entity. Set sentiment to 1 to return this information
type Sentiment polarity: positive, negative, or neutral
score Sentiment strength (0.0 == neutral)
mixed 1 indicates that the sentiment is both positive and negative

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "https://mobile.twitter.com/ibmwatson",
  "totalTransactions": "1",
  "language": "english",
  "keywords": [
    {
      "relevance": "0.936546",
      "text": "Watson"
    },
    {
      "relevance": "0.823589",
      "text": "Watson Developer Cloud"
    },
    ...
  ]
}

Language Detection

HTML URL Text

Detect the language of an HTML document.

Detect the language of a webpage.

Detect the language of plain text.

Detect the language of a webpage, HTML, or plain text.

Language detection runs automatically in each API call. This method provides more information about the detected language. For language detection to work best, make sure your source text has at least 100 characters. If you're having trouble with language detection, you can pass the language parameter in any call to manually specify the language of your content.

See the complete list of detectable languages here

POST /html/HTMLGetLanguageGET /url/URLGetLanguage
POST /url/URLGetLanguagePOST /text/TextGetLanguage
language(parameters, callback)
language(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
url query Input here will appear as the url value in the response.
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" --data-urlencode html@ibm.html -d "url=http://www.ibm.com/us-en/" "https://gateway-a.watsonplatform.net/calls/html/HTMLGetLanguage?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" -d "url=http://www.ibm.com/us-en/" "https://gateway-a.watsonplatform.net/calls/url/URLGetLanguage?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
text query (Required) Text content (must be URL encoded)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
url query Input here will appear as the url value in the response.
showSourceText query Set this to 1 to include the source text in the response

Example request


curl -X POST -d "outputMode=json" --data-urlencode text@ibm.txt -d "url=http://www.ibm.com/us-en/" "https://gateway-a.watsonplatform.net/calls/text/TextGetLanguage?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
outputMode string xml or json (default)
showSourceText integer Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  url: 'http://www.ibm.com/us-en'
};

alchemy_language.language(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Parameter Type Description
api_key string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')
print(json.dumps(
  alchemy_language.language(
    url='ibm.com/us-en'),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
language Detected language
iso-639-1 ISO-639-1 code for the detected language
iso-639-2 ISO-639-2 code for the detected language
iso-639-3 ISO-639-3 code for the detected language
ethnologue Link to Ethnologue for additional language information
native-speakers Number of people who natively speak the detected language
wikipedia Link to the wikipedia page for the detected language

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "http://www.ibm.com/us-en/",
  "language": "english",
  "iso-639-1": "en",
  "iso-639-2": "eng",
  "iso-639-3": "eng",
  "ethnologue": "http://www.ethnologue.com/show_language.asp?code=eng",
  "native-speakers": "309-400 million",
  "wikipedia": "http://en.wikipedia.org/wiki/English_language"
}

Microformats

HTML URL

Extract microformats from an HTML document.

Extract microformats from a webpage.

Extract microformats from a webpage or HTML.

Supported microformats

POST /html/HTMLGetMicroformatDataGET /url/URLGetMicroformatData
POST /url/URLGetMicroformatData
microformats(parameters, callback)
microformats(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
url query Input here will appear as the url value in the response.

Example request


curl -X POST -d "outputMode=json" --data-urlencode html@microformats.html -d "url=http://microformats.org/wiki/hcard" "https://gateway-a.watsonplatform.net/calls/html/HTMLGetMicroformatData?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)

Example request


curl -X POST -d "outputMode=json" -d "url=http://microformats.org/wiki/hcard" "https://gateway-a.watsonplatform.net/calls/url/URLGetMicroformatData?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
outputMode string xml or json (default)
showSourceText integer Set this to 1 to include the source text in the response

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  url: 'http://microformats.org/wiki/hcard'
};

alchemy_language.microformats(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Parameter Type Description
api_key string Your API key
html, url string One of these is required. Pass HTML content in html or a public facing URL in url

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')
print(json.dumps(
  alchemy_language.microformats(
    url='http://microformats.org/wiki/hcard'),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
microformats Array of microformats objects
field Microformat field name
data Microformat data

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "http://microformats.org/wiki/hcard",
  "microformats": [
    {
      "field": "RelTagLink",
      "data": "/wiki/Category:Specifications"
    },
    {
      "field": "RelTag",
      "data": "Category:Specifications"
    },
    {
      "field": "NameGivenName",
      "data": "Tantek"
    },
    {
      "field": "NameFamilyName",
      "data": "Çelik"
    },
    {
      "field": "FormattedName",
      "data": "Tantek Çelik"
    },
    {
      "field": "Role",
      "data": "Editor"
    },
    {
      "field": "Role",
      "data": "Author"
    }
  ]
}

Publication Date

HTML URL

Get the publication date of an HTML document.

Get the publication date of a webpage.

Get the publication date of a webpage or HTML document. 

POST /html/HTMLGetPubDateGET /url/URLGetPubDate
POST /url/URLGetPubDate
publicationDate(parameters, callback)
publication_date(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
url query Input here will appear as the url value in the response.

Example request


curl -X POST -d "outputMode=json" --data-urlencode html@court_nomination.html -d "url=https://www.whitehouse.gov/the-press-office/2016/03/19/weekly-address-president-obamas-supreme-court-nomination" "https://gateway-a.watsonplatform.net/calls/url/URLGetPubDate?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)

Example request


curl -X POST -d "outputMode=json" -d "url=https://www.whitehouse.gov/the-press-office/2016/03/19/weekly-address-president-obamas-supreme-court-nomination" "https://gateway-a.watsonplatform.net/calls/url/URLGetPubDate?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
outputMode string xml or json (default)
showSourceText integer Set this to 1 to include the source text in the response

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  url: 'https://www.whitehouse.gov/the-press-office/2016/03/19/weekly-address-president-obamas-supreme-court-nomination'
};

alchemy_language.publicationDate(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Parameter Type Description
api_key string Your API key
html, url string One of these is required. Pass HTML content in html or a public facing URL in url

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')
print(json.dumps(
  alchemy_language.publication_date(
    url='https://www.whitehouse.gov/the-press-office/2016/03/19/weekly-address-president-obamas-supreme-court-nomination'),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
language Detected language of the source text (text with fewer than 15 characters is assumed to be English)
publicationDate Object containing the date in yyyymmddThhmmss format, and a confidence indicator (yes or no)

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "https://www.whitehouse.gov/the-press-office/2016/03/19/weekly-address-president-obamas-supreme-court-nomination",
  "totalTransactions": "1",
  "language": "english",
  "publicationDate": {
    "confident": "yes",
    "date": "20160319T000000"
  }
}

Relations

HTML URL Text

Extract Subject-Action-Object relations from an HTML document.

Extract Subject-Action-Object relations from a webpage.

Extract Subject-Action-Object relations from plain text.

Extract Subject-Action-Object relations from a webpage, HTML, or plain text.

Supported languages: English, Spanish 

POST /html/HTMLGetRelationsGET /url/URLGetRelations
POST /url/URLGetRelationsPOST /text/TextGetRelations
relations(parameters, callback)
relations(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
maxRetrieve query Maximum number of relations to return (default = 50, maximum = 100)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
url query Input here will appear as the url value in the response.
keywords query Set this to 1 to identify keywords in detected relations
This incurs an additional transaction charge
entities query Set this to 1 to identify named entities in detected relations
This incurs an additional transaction charge
requireEntities query Set this to 1 to restrict results to relations that contain at least one named entity
coreference query Set this to 0 to treat coreferences as separate entities (coreferences are resolved into detected entities by default)
disambiguate query Set this to 0 to hide entity disambiguation information in the response
knowledgeGraph query Set this to 1 to include knowledge graph information in the results
This incurs an additional transaction charge
linkedData query Set this to 0 to hide Linked Data content links in the response
sentiment query Set this to 1 to analyze the sentiment towards each result
This incurs an additional transaction charge
sentimentExcludeEntities query Set this to 1 to exclude named entity text from sentiment analysis. For exapmle, do not analyze "New" in "New York"
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "maxRetrieve=1" -d "outputMode=json" --data-urlencode html@nomination.html -d "url=https://www.whitehouse.gov/the-press-office/2016/03/19/weekly-address-president-obamas-supreme-court-nomination" "https://gateway-a.watsonplatform.net/calls/html/HTMLGetRelations?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
maxRetrieve query Maximum number of entities to return (default = 50, maximum = 100)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
keywords query Set this to 1 to identify keywords in detected relations
This incurs an additional transaction charge
entities query Set this to 1 to identify named entities in detected relations
This incurs an additional transaction charge
requireEntities query Set this to 1 to restrict results to relations that contain at least one named entity
coreference query Set this to 0 to treat coreferences as separate entities (coreferences are resolved into detected entities by default)
disambiguate query Set this to 0 to hide entity disambiguation information in the response
knowledgeGraph query Set this to 1 to include knowledge graph information in the results
This incurs an additional transaction charge
linkedData query Set this to 0 to hide Linked Data content links in the response
sentiment query Set this to 1 to analyze the sentiment towards each result
This incurs an additional transaction charge
sentimentExcludeEntities query Set this to 1 to exclude named entity text from sentiment analysis. For exapmle, do not analyze "New" in "New York"
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "maxRetrieve=1" -d "outputMode=json" -d "url=https://www.whitehouse.gov/the-press-office/2016/03/19/weekly-address-president-obamas-supreme-court-nomination" "https://gateway-a.watsonplatform.net/calls/url/URLGetRelations?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
text query (Required) Text content (must be URL encoded)
maxRetrieve query Maximum number of entities to return (default = 50, maximum = 100)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
url query Input here will appear as the url value in the response.
keywords query Set this to 1 to identify keywords in detected relations
This incurs an additional transaction charge
entities query Set this to 1 to identify named entities in detected relations
This incurs an additional transaction charge
requireEntities query Set this to 1 to restrict results to relations that contain at least one named entity
coreference query Set this to 0 to treat coreferences as separate entities (coreferences are resolved into detected entities by default)
disambiguate query Set this to 0 to hide entity disambiguation information in the response
knowledgeGraph query Set this to 1 to include knowledge graph information in the results
This incurs an additional transaction charge
linkedData query Set this to 0 to hide Linked Data content links in the response
sentiment query Set this to 1 to analyze the sentiment towards each result
This incurs an additional transaction charge
sentimentExcludeEntities query Set this to 1 to exclude named entity text from sentiment analysis. For exapmle, do not analyze "New" in "New York"
showSourceText query Set this to 1 to include the source text in the response

Example request


curl -X POST -d "maxRetrieve=1" -d "outputMode=json" --data-urlencode text@nomination.txt -d "url=https://www.whitehouse.gov/the-press-office/2016/03/19/weekly-address-president-obamas-supreme-court-nomination" "https://gateway-a.watsonplatform.net/calls/text/TextGetRelations?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
maxRetrieve integer Maximum number of relations to return (default = 50, maximum = 100)
outputMode string xml or json (default)
showSourceText integer Set this to 1 to include the source text in the response
keywords integer Set this to 1 to identify keywords in detected relations
This incurs an additional transaction charge
entities integer Set this to 1 to identify named entities in detected relations
This incurs an additional transaction charge
requireEntities integer Set this to 1 to restrict results to relations that contain at least one named entity
coreference integer Set this to 0 to treat coreferences as separate entities (coreferences are resolved into detected entities by default)
disambiguate integer Set this to 0 to hide entity disambiguation information in the response
knowledgeGraph integer Set this to 1 to include knowledge graph information in the results
This incurs an additional transaction charge
linkedData integer Set this to 0 to hide Linked Data content links in the response
sentiment integer Set this to 1 to analyze the sentiment towards each result
This incurs an additional transaction charge
sentimentExcludeEntities integer Set this to 1 to exclude named entity text from sentiment analysis. For exapmle, do not analyze "New" in "New York"
cquery string A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath string An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText string How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  url: 'https://www.whitehouse.gov/the-press-office/2016/03/19/weekly-address-president-obamas-supreme-court-nomination'
};

alchemy_language.relations(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Parameter Type Description
api_key string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
max_items integer Maximum number of relations to return (default = 50, maximum = 100)
show_source_text integer Set this to 1 to include the source text in the response
keywords integer Set this to 1 to include the source text in the response
entities integer Set this to 1 to identify named entities in detected relations
This incurs an additional transaction charge
require_entities integer Set this to 1 to restrict results to relations that contain at least one named entity
coreference integer Set this to 0 to treat coreferences as separate entities (coreferences are resolved into detected entities by default)
disambiguate integer Set this to 0 to hide entity disambiguation information in the response
linked_data integer Set this to 0 to hide Linked Data content links in the response
sentiment integer Set this to 1 to analyze the sentiment towards each result
This incurs an additional transaction charge
sentiment_exclude_entities integer Set this to 1 to exclude named entity text from sentiment analysis. For exapmle, do not analyze "New" in "New York"

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')
print(json.dumps(
  alchemy_language.relations(
    url='https://www.whitehouse.gov/the-press-office/2016/03/19/weekly-address-president-obamas-supreme-court-nomination',
    max_items=1),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
language Detected language of the source text (text with fewer than 15 characters is assumed to be English)
relations Array of detected relations
sentence Sentence text associated with the relation
subject The subject of the relation
text Text associated with the detected subject
sentiment Sentiment Analysis information for the subject. Set sentiment to 1 to enable this in the response
entity Entity information for the subject. Set entities to 1 to enable this in the response
action The action of the relation
text Text associated with the detected action
lemmatized Lemmatized text of the action
verb Object containing the text of the base form of the verb and the verb tense. If the verb is negated in the text, there will be a "negated" attribute with value 1.
object The object of the relation
text Text associated with the detected object
sentiment Sentiment Analysis information for the object. Set sentiment to 1 to enable this in the response
sentimentFromSubject Sentiment Analysis data targeted towards the object, from the subject, via the action. Set sentiment to 1 to enable this in the response
entity Entity information for the subject. Set entities to 1 to enable this in the response

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "https://www.whitehouse.gov/the-press-office/2016/03/19/weekly-address-president-obamas-supreme-court-nomination",
  "language": "english",
  "relations": [
    {
      "sentence": " WASHINGTON, DC — In this week's address, the President discussed his decision to nominate Chief Judge Merrick Garland to the Supreme Court of the United States.",
      "subject": {
        "text": "the President"
      },
      "action": {
        "text": "to nominate",
        "lemmatized": "to nominate",
        "verb": {
          "text": "nominate",
          "tense": "future"
        }
      },
      "object": {
        "text": "Merrick Garland"
      }
    }
  ]
}

Typed Relations

HTML URL Text

Use custom models to identify typed relations between detected entities in an HTML document.

Use custom models to identify typed relations between detected entities from a webpage.

Use custom models to identify typed relations between detected entities in plain text.

Use custom models to identify typed relations between detected entities from a webpage, HTML, or plain text.

Typed relations identify different types of connections between detected entities. For example, the entities "Oscar" and "Leonardo DiCaprio" might be linked by an "awardedTo" relation. To tailor results for your domain, you can specify your own custom entities and relations with custom models in Watson Knowledge Studio.

Note: Source text in Typed Relations calls is truncated to 5 KB 

POST /html/HTMLGetTypedRelationsGET /url/URLGetTypedRelations
POST /url/URLGetTypedRelationsPOST /text/TextGetTypedRelations
typedRelations(parameters, callback)
typed_relations(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
model query The unique alphanumeric identifier for your custom model. You can also choose from the following public models:
  • en-news: trained on English news content (default)
  • es-news: trained on Spanish news content
  • ar-news: trained on Arabic news content
outputMode query json or xml (default)
showSourceText query Set this to 1 to include the source text in the response
jsonp query Desired JSONP callback (requires outputMode to be set to json)

Example request


  curl -X POST -d "outputMode=json" -d "url=http://techcrunch.com" "https://gateway-a.watsonplatform.net/calls/url/URLGetTypedRelations?apikey=%API_KEY%&model=en-news"
Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
model query The unique alphanumeric identifier for your custom model. You can also choose from the following public models:
  • en-news: trained on English news content (default)
  • es-news: trained on Spanish news content
  • ar-news: trained on Arabic news content
outputMode query json or xml (default)
showSourceText query Set this to 1 to include the source text in the response
url query Input here will appear as the url value in the response
jsonp query Desired JSONP callback (requires outputMode to be set to json)

Example request


  curl -X POST -d "outputMode=json" --data-urlencode html@ibm_site.html -d "url=http://techcrunch.com" "https://gateway-a.watsonplatform.net/calls/html/HTMLGetTypedRelations?apikey=%API_KEY%&model=en-news"
Parameter Type Description
apikey query (Required) Your API key
text query (Required) Text content (must be URL encoded)
model query The unique alphanumeric identifier for your custom model. You can also choose from the following public models:
  • en-news: trained on English news content (default)
  • es-news: trained on Spanish news content
  • ar-news: trained on Arabic news content
outputMode query json or xml (default)
showSourceText query Set this to 1 to include the source text in the response
url query Input here will appear as the url value in the response
jsonp query Desired JSONP callback (requires outputMode to be set to json)

Example request


  curl -X POST -d "outputMode=json" --data-urlencode text@ibm_site.txt -d "url=http://techcrunch.com" "https://gateway-a.watsonplatform.net/calls/text/TextGetTypedRelations?apikey=%API_KEY%&model=en-news"
Parameter Type Description
apikey string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
model string The unique alphanumeric identifier for your custom model. You can also choose from the following public models:
  • en-news: trained on English news content (default)
  • es-news: trained on Spanish news content
  • ar-news: trained on Arabic news content
outputMode string xml or json (default)
showSourceText integer Set this to 1 to include the source text in the response

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  url: 'http://techcrunch.com'
};

alchemy_language.typedRelations(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Parameter Type Description
api_key string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
model string The unique alphanumeric identifier for your custom model. You can also choose from the following public models:
  • en-news: trained on English news content (default)
  • es-news: trained on Spanish news content
  • ar-news: trained on Arabic news content
show_source_text integer Set this to 1 to include the source text in the response

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')
print(json.dumps(
  alchemy_language.typed_relations(
    url='techcrunch.com'),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
typedRelations array of relation objects
arguments Array of entities involved in the relation. Each entity is assigned a part in the relation, which indicates its position in the relation, and an id, a unique identifier for that entity. The entity type is also displayed.
score Confidence score between 0.0 and 1.0. The higher the score, the greater the confidence
sentence Text from the document where the relation was detected
type The type of relation detected between the entities

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "http://techcrunch.com/",
  "totalTransactions": "1",
  "language": "english",
  "typedRelations": [
    {
      "arguments": [
        {
          "entities": [
            {
              "id": "-E60",
              "text": "five years ago",
              "type": "Date"
            }
          ],
          "part": "first",
          "text": "five years ago"
        },
        {
          "entities": [
            {
              "id": "-E1",
              "text": "Software Is Eating the World",
              "type": "TitleWork"
            }
          ],
          "part": "second",
          "text": "Software Is Eating the World"
        }
      ],
      "score": "0.687956",
      "sentence": "Marc Andreessen penned his famous \"Why Software Is Eating the World\" essay five years ago.",
      "type": "timeOf"
    },
    ...
  ]
}

Sentiment Analysis

HTML URL Text

Analyze the overall sentiment of an HTML document.

Analyze the overall sentiment of a webpage.

Analyze the overall sentiment of plain text.

Analyze the overall sentiment of a webpage, HTML, or plain text.

Supported languages: Arabic, English, French, German, Italian, Portuguese, Russian, Spanish 

POST /html/HTMLGetTextSentimentGET /url/URLGetTextSentiment
POST /url/URLGetTextSentimentPOST /text/TextGetTextSentiment
sentiment(parameters, callback)
sentiment(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
url query Input here will appear as the url value in the response.
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" --data-urlencode html@iphone_review.html -d "url=http://www.huffingtonpost.com/2010/06/22/iphone-4-review-the-worst_n_620714.html" "https://gateway-a.watsonplatform.net/calls/html/HTMLGetTextSentiment?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" -d "url=http://www.huffingtonpost.com/2010/06/22/iphone-4-review-the-worst_n_620714.html" "https://gateway-a.watsonplatform.net/calls/url/URLGetTextSentiment?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
text query (Required) Text content (must be URL encoded)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
showSourceText query Set this to 1 to include the source text in the response

Example request


curl -X POST -d "outputMode=json" --data-urlencode text@iphone_review.txt -d "url=http://www.huffingtonpost.com/2010/06/22/iphone-4-review-the-worst_n_620714.html" "https://gateway-a.watsonplatform.net/calls/text/TextGetTextSentiment?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
outputMode string xml or json (default)
showSourceText integer Set this to 1 to include the source text in the response
cquery string A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath string An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText string How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  url: 'http://www.huffingtonpost.com/2010/06/22/iphone-4-review-the-worst_n_620714.html'
};

alchemy_language.sentiment(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Parameter Type Description
api_key string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')
print(json.dumps(
  alchemy_language.sentiment(
    url='http://www.huffingtonpost.com/2010/06/22/iphone-4-review-the-worst_n_620714.html'),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
language Detected language of the source text (text with fewer than 15 characters is assumed to be English)
docSentiment Object containing document-level sentiment information
mixed 1 indicates that the sentiment is both positive and negative
score Sentiment strength (0.0 == neutral)
type Sentiment polarity: positive, negative, or neutral

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "http://www.huffingtonpost.com/2010/06/22/iphone-4-review-the-worst_n_620714.html",
  "totalTransactions": "1",
  "language": "english",
  "docSentiment": {
    "mixed": "1",
    "score": "-0.24582",
    "type": "negative"
  }
}

Targeted Sentiment

HTML URL Text

Analyze sentiment for targeted phrases in an HTML document.

Analyze sentiment for targeted phrases on a webpage.

Analyze sentiment for targeted phrases in plain text.

Analyze sentiment for targeted phrases in a webpage, HTML, or plain text.

Supported languages: Arabic, English, French, German, Italian, Portuguese, Russian, Spanish 

POST /html/HTMLGetTargetedSentimentGET /url/URLGetTargetedSentiment
POST /url/URLGetTargetedSentimentPOST /text/TextGetTargetedSentiment
sentiment(parameters, callback)
targeted_sentiment(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
targets query (Required) phrase1|phrase2|...
Pipe delimited list of phrases. The service will return sentiment information for each phrase that is found in the source text. Supports up to 20 phrases.
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
url query Input here will appear as the url value in the response.
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" -d "targets=NASDAQ|Dow" --data-urlencode html@stock_market_news.html -d "url=http://www.zacks.com/stock/news/207968/stock-market-news-for-february-19-2016" "https://gateway-a.watsonplatform.net/calls/html/HTMLGetTargetedSentiment?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
targets query (Required) phrase1|phrase2|...
Pipe delimited list of phrases. The service will return sentiment information for each phrase that is found in the source text. Supports up to 20 phrases.
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" -d "targets=NASDAQ|Dow" -d "url=http://www.zacks.com/stock/news/207968/stock-market-news-for-february-19-2016" "https://gateway-a.watsonplatform.net/calls/url/URLGetTargetedSentiment?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
text query (Required) Text content (must be URL encoded)
targets query (Required) phrase1|phrase2|...
Pipe delimited list of phrases. The service will return sentiment information for each phrase that is found in the source text. Supports up to 20 phrases.
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
url query Input here will appear as the url value in the response.
showSourceText query Set this to 1 to include the source text in the response

Example request


curl -X POST -d "outputMode=json" -d "targets=NASDAQ|Dow" --data-urlencode text@stock_market_news.txt -d "url=http://www.zacks.com/stock/news/207968/stock-market-news-for-february-19-2016" "https://gateway-a.watsonplatform.net/calls/text/TextGetTargetedSentiment?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
targets array[string] Array of target phrases. The service will return sentiment information for each phrase that is found in the source text. Supports up to 20 phrases.
outputMode string xml or json (default)
showSourceText integer Set this to 1 to include the source text in the response
cquery string A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath string An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText string How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  url: 'http://www.zacks.com/stock/news/207968/stock-market-news-for-february-19-2016',
  targets: [
    'NASDAQ',
    'Dow'
  ]
};

alchemy_language.sentiment(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Parameter Type Description
api_key string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
targets list List of target phrases. The service will return sentiment information for each phrase that is found in the source text. Supports up to 20 phrases.

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')
print(json.dumps(
  alchemy_language.targeted_sentiment(
    url='http://www.zacks.com/stock/news/207968/stock-market-news-for-february-19-2016',
    targets=['NASDAQ', 'Dow']),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
language Detected language of the source text (text with fewer than 15 characters is assumed to be English)
results Array of sentiment result objects
mixed 1 indicates that the sentiment is both positive and negative
score Sentiment strength (0.0 == neutral)
type Sentiment polarity: positive, negative, or neutral
text The targeted phrase associated with the sentiment information
statusInfo In addition to the generic error messages, this can contain cannot-locate-keyphrase when the sentiment target is not found in the text.

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "http://www.zacks.com/stock/news/207968/stock-market-news-for-february-19-2016",
  "totalTransactions": "1",
  "language": "english",
  "results": [
    {
      "sentiment": {
        "score": "-0.387744",
        "type": "negative"
      },
      "text": "NASDAQ"
    },
    {
      "sentiment": {
        "score": "-0.416076",
        "type": "negative"
      },
      "text": "Dow"
    }
  ]
}

Taxonomy

HTML URL Text

Categorize an HTML document into a 5-level taxonomy.

Categorize a webpage into a 5-level taxonomy.

Categorize plain text into a 5-level taxonomy.

Categorize a webpage, HTML, or plain text into a 5-level taxonomy.

Download the complete list of taxonomy categories: PDF | XLSX | CSV

Supported languages: English 

POST /html/HTMLGetRankedTaxonomyGET /url/URLGetRankedTaxonomy
POST /url/URLGetRankedTaxonomyPOST /text/TextGetRankedTaxonomy
taxonomy(parameters, callback)
taxonomy(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
url query Input here will appear as the url value in the response.
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" --data-urlencode html@cnn.html -d "url=http://www.cnn.com" "https://gateway-a.watsonplatform.net/calls/html/HTMLGetRankedTaxonomy?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" -d "url=http://www.cnn.com" "https://gateway-a.watsonplatform.net/calls/url/URLGetRankedTaxonomy?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
text query (Required) Text content (must be URL encoded)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
showSourceText query Set this to 1 to include the source text in the response
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" --data-urlencode text@cnn.txt -d "url=http://www.cnn.com" "https://gateway-a.watsonplatform.net/calls/text/TextGetRankedTaxonomy?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
outputMode string xml or json (default)
showSourceText integer Set this to 1 to include the source text in the response
cquery string A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath string An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText string How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  url: 'cnn.com'
};

alchemy_language.taxonomy(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Parameter Type Description
api_key string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
show_source_text integer Set this to 1 to include the source text in the response
constraint_query string A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath_query string An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
source_text_type string How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')
print(json.dumps(
  alchemy_language.taxonomy(
    url='cnn.com'),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
language Detected language of the source text (text with fewer than 15 characters is assumed to be English)
taxonomy Array of objects containing information about the detected categories
label Detected category
score Confidence score between 0.0 and 1.0. The higher the score, the greater the confidence

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "http://www.cnn.com/",
  "totalTransactions": "1",
  "language": "english",
  "taxonomy": [
    {
      "label": "/news",
      "score": "0.994385"
    },
    {
      "label": "/art and entertainment/movies and tv/television",
      "score": "0.706355"
    },
    {
      "confident": "no",
      "label": "/sports/football",
      "score": "0.471388"
    }
  ]
}

Text (cleaned)

HTML URL

Extract primary text content from an HTML document.

Extract primary text content from a webpage.

Extract primary text content from a webpage or HTML.

Cleaned page text is obtained by default in other HTML and URL functions. You can view the results of page cleaning in responses from most of the other methods by passing showSourceText=1. 

POST /html/HTMLGetTextGET /url/URLGetText
POST /url/URLGetText
text(parameters, callback)
text(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
extractLinks query Set this to 1 to include hyperlinks in the extracted text
useMetadata query Set this to 0 to ignore description information in webpage metadata
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
url query Input here will appear as the url value in the response.
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" --data-urlencode html@tech_crunch.html -d "url=http://techcrunch.com/2016/01/29/ibm-watson-weather-company-sale/" "https://gateway-a.watsonplatform.net/calls/url/URLGetText?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
extractLinks query Set this to 1 to include hyperlinks in the extracted text
useMetadata query Set this to 0 to ignore description information in webpage metadata
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
cquery query A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath query An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText query How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example request


curl -X POST -d "outputMode=json" -d "url=http://techcrunch.com/2016/01/29/ibm-watson-weather-company-sale/" "https://gateway-a.watsonplatform.net/calls/url/URLGetText?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url string One of these is required. Pass HTML content in html or a public facing URL in url
extractLinks integer Set this to 1 to include hyperlinks in the extracted text
useMetadata integer Set this to 0 to ignore description information in webpage metadata
outputMode string xml or json (default)
showSourceText integer Set this to 1 to include the source text in the response
cquery string A visual constraints query to apply to the web page. Required when sourceText is set to cquery
xpath string An XPath query to apply to the web page. Required when sourceText is set to one of the XPath values
sourceText string How to obtain the source text from the webpage. Possible values:
cleaned_or_raw (default) Removes website elements such as links, ads, etc. If cleaning fails, raw web page text is used
cleaned Removes website elements such as links, ads, etc.
raw Uses raw web page text with no cleaning
cquery Uses the visual constraints query that you specify in the cquery parameter
xpath Uses the XPath query that you specify in the xpath parameter
xpath_or_raw Uses the results of an XPath query that you specify in the xpath parameter, falling back to plain text if the XPath query returns nothing
cleaned_and_xpath Uses the results of an XPath query on cleaned web page text

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  url: 'http://techcrunch.com/2016/01/29/ibm-watson-weather-company-sale'
};

alchemy_language.text(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Parameter Type Description
api_key string Your API key
html, url string One of these is required. Pass HTML content in html or a public facing URL in url
extract_links integer Set this to 1 to include hyperlinks in the extracted text
use_metadata integer Set this to 0 to ignore description information in webpage metadata

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')
print(json.dumps(
  alchemy_language.text(
    url='techcrunch.com/2016/01/29/ibm-watson-weather-company-sale'),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
language Detected language of the source text (text with fewer than 15 characters is assumed to be English)
text The extracted text

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "http://techcrunch.com/2016/01/29/ibm-watson-weather-company-sale/",
  "language": "english",
  "text": "   IBM is taking another step to expand its Watson AI business and build its presence in areas like IoT: today the company announced ... "
}

Text (raw)

HTML URL

Extract the plain text from an HTML document.

Extract the plain text from a webpage.

Extract the plain text from a webpage or HTML. 

POST /html/HTMLGetRawTextGET /url/URLGetRawText
POST /url/URLGetRawText
text(parameters, callback)
// One of the parameters must be "raw: true"
text(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
outputMode query json or xml (default)
url query Input here will appear as the url value in the response.

Example request


curl -X POST -d "outputMode=json" --data-urlencode html@tech_crunch.html -d "url=http://techcrunch.com/2016/01/29/ibm-watson-weather-company-sale/" "https://gateway-a.watsonplatform.net/calls/html/HTMLGetRawText?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)

Example request


curl -X POST -d "outputMode=json" -d "url=http://techcrunch.com/2016/01/29/ibm-watson-weather-company-sale/" "https://gateway-a.watsonplatform.net/calls/url/URLGetRawText?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url string One of these is required. Pass HTML content in html or a public facing URL in url
outputMode string xml or json (default)
showSourceText integer Set this to 1 to include the source text in the response

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  url: 'http://techcrunch.com/2016/01/29/ibm-watson-weather-company-sale',
  raw: true
};

alchemy_language.text(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Parameter Type Description
api_key string Your API key
html, url string One of these is required. Pass HTML content in html or a public facing URL in url

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')
print(json.dumps(
  alchemy_language.raw_text(
    url='techcrunch.com/2016/01/29/ibm-watson-weather-company-sale'),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
text The extracted text

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "http://techcrunch.com/2016/01/29/ibm-watson-weather-company-sale/",
  "text": "IBM Closes Weather Co. Purchase, Names David Kenny New Head Of Watson Platform  |  TechCrunch\n  \t \t\t\n \n  \t \t\t \t\t\t \t\t\t\tMenu \t\t\t\t \t\t\t\tSearch \t\t\t\t  ... "
}

Title Extraction

HTML URL

Extract the page title from an HTML document.

Extract the page title from a webpage.

Extract the page title from a webpage or HTML. 

POST /html/HTMLGetTitleGET /url/URLGetTitle
POST /url/URLGetTitle
title(parameters, callback)
title(parameter=value,...)

Request

Parameter Type Description
apikey query (Required) Your API key
html query (Required) HTML content (must be URL encoded)
useMetadata query 1 or 0
Whether to use title information from the web page metadata (default = 1: enabled)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
url query Input here will appear as the url value in the response.

Example request


curl -X POST -d "outputMode=json" --data-urlencode html@tech_crunch.html -d "url=http://techcrunch.com/2016/01/29/ibm-watson-weather-company-sale/" "https://gateway-a.watsonplatform.net/calls/html/HTMLGetTitle?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
url query (Required) HTTP URL
useMetadata query 1 or 0
Whether to use title information from the web page metadata (default = 1: enabled)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)

Example request


curl -X POST -d "outputMode=json" -d "url=http://techcrunch.com/2016/01/29/ibm-watson-weather-company-sale/" "https://gateway-a.watsonplatform.net/calls/url/URLGetTitle?apikey=%API_KEY%"
Parameter Type Description
apikey query (Required) Your API key
text query (Required) HTML content (must be URL encoded)
useMetadata query 1 or 0
Whether to use title information from the web page metadata (default = 1: enabled)
outputMode query json or xml (default)
jsonp query JSONP callback (requires outputMode to be set to json)
url query Input here will appear as the url value in the response.

Example request


curl -X POST -d "outputMode=json" --data-urlencode "url=http://techcrunch.com/2016/01/29/ibm-watson-weather-company-sale/" "https://gateway-a.watsonplatform.net/calls/url/URLGetAuthors?apikey=%API_KEY%"
Parameter Type Description
apikey string Your API key
html, url, text string One of these is required. Pass HTML content in html, a public facing URL in url, or plain text in text
use_metadata integer Set this to 0 to ignore description information in webpage metadata
outputMode string xml or json (default)
showSourceText integer Set this to 1 to include the source text in the response

Example Request


var watson = require('watson-developer-cloud');
var alchemy_language = watson.alchemy_language({
  api_key: 'API_KEY'
})

var parameters = {
  url: 'http://techcrunch.com/2016/01/29/ibm-watson-weather-company-sale'
};

alchemy_language.title(parameters, function (err, response) {
  if (err)
    console.log('error:', err);
  else
    console.log(JSON.stringify(response, null, 2));
});
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Coming soon.

Example request

Example coming soon.
Parameter Type Description
api_key string Your API key
html, url string One of these is required. Pass HTML content in html or a public facing URL in url
use_metadata integer Set this to 0 to ignore description information in webpage metadata

Example Request


import json
from watson_developer_cloud import AlchemyLanguageV1

alchemy_language = AlchemyLanguageV1(api_key='API_KEY')
print(json.dumps(
  alchemy_language.title(
    url='techcrunch.com/2016/01/29/ibm-watson-weather-company-sale'),
  indent=2))

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
url HTTP URL that was passed in the input
title The extracted title

Example response


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "http://techcrunch.com/2016/01/29/ibm-watson-weather-company-sale/",
  "title": "IBM Closes Weather Co. Purchase, Names David Kenny New Head Of Watson Platform"
}

Custom models

The following methods allow you to manage custom models that are deployed to your AlchemyAPI service instance. With an Advanced pricing plan and access to Watson Knowledge Studio, you can create your own custom model that specializes in understanding entities and relations that are unique to your domain.

Learn more about custom models and how to get started here.

List models

Lists the models available for your AlchemyAPI service instance. The list includes custom models that have been deployed from Watson Knowledge Studio as well as some default models that are available to all AlchemyLanguage users. 

GET /info/models

Request

Parameter Type Description
apikey query (Required) Your API key
outputMode query json or xml (default)

Example request


curl -X GET -d "outputMode=json" "https://gateway-a.watsonplatform.net/calls/info/models?apikey=%API_KEY%"

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
models Array of available models
status The status of the model
model_id The unique model identifier. Use this in supported API calls to override AlchemyLanguage's default model.
language The language that is compatible with the model

Example response


{
  "status": "OK",
  "models": [
    {
      "status": "available",
      "model_id": "en-news",
      "language": "en",
      "description": "English relationship extraction"
    },
    {
      "status": "available",
      "model_id": "MODEL_KEY",
      "language": "en",
      "description": "My custom model deployed from Watson Knowledge Studio"
    }
  ]
}

Delete model

Deletes a custom model that was deployed to your AlchemyAPI service instance from Watson Knowledge Studio. 

DELETE /info/model/{model_id}

Request

Parameter Type Description
apikey query (Required) Your API key
model_id path The unique identifier for the model that you want to delete
outputMode query json or xml (default)

Example request


curl -X DELETE -d "outputMode=json" "https://gateway-a.watsonplatform.net/calls/info/model/MODEL_ID?apikey=%API_KEY%"

Response

Name Description
status OK or ERROR
Indicates whether the request was successful
statusInfo Additional status information. In addition to the general error messages, this can contain:
  • model-deleted:MODEL_ID
  • model-does-not-exist:MODEL_ID

Example response


{
  "status": "OK",
  "statusInfo": "model-deleted:MODEL_ID"
}

Data collection

By default, all Watson services log requests and their results. Logging is done only to improve the services for future users. The logged data is not shared or made public. To prevent IBM from accessing your data for general service improvements, set the X-Watson-Learning-Opt-Out header parameter to true for all requests. (Any value other than false or 0 disables request logging for that call.) You must set the header on each request that you do not want IBM to access.

Error handling

When an error occurs, the status attribute of the response will read ERROR, and the statusInfo attribute will contain a string that describes the error.

Error information

statusInfo Description
invalid-api-key Value of the apikey parameter is invalid
cannot-retrieve Cannot retrieve the webpage. Contains additional information depending on the reason (see example)
page-is-not-html Input content is not HTML
unsupported-text-language The method you are using does not support the language of the source text. If the detected language isn't correct (it usually is for text > 100 characters), you can manually specify the language in the language query parameter.

Example: inputting a bad URL


              curl -X POST -d "outputMode=json" -d "url=http://www.ibmc.om" "https://gateway-a.watsonplatform.net/calls/url/URLGetTitle?apikey=%API_KEY%"

Example error response


{
  "status": "ERROR",
  "statusInfo": "cannot-retrieve:operation-timeout:cannot-resolve-dns",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "http://www.ibmc.om",
  "title": ""
}

Language support

The following languages are detectable automatically in each API call, or manually through the Language Detection method. For automatic language detection to work best, it is recommend that you use source text with at least 100 characters.

To override language detection, pass the language query parameter with your desired language name in lowercase.

Afrikaans ISO-639-3: afr
Albanian ISO-639-3: sqi
Amharic ISO-639-3: amh
Amuzgo Guerrero ISO-639-3: amu
Arabic ISO-639-3: ara
Armenian ISO-639-3: hye
Azerbaijani ISO-639-3: aze
Basque ISO-639-3: eus
Breton ISO-639-3: bre
Bulgarian ISO-639-3: bul
Catalan ISO-639-3: cat
Cebuano ISO-639-3: ceb
Central K'iche' ISO-639-3: qut
Central Mam ISO-639-3: mvc
Chamorro ISO-639-3: cha
Cherokee ISO-639-3: chr
Chinese ISO-639-3: zho
Comaltepec Chinantec ISO-639-3: cco
Croatian ISO-639-3: hrv
Cubulco Achi' ISO-639-3: acc
Czech ISO-639-3: ces
Dakota ISO-639-3: dak
Danish ISO-639-3: dan
Dutch ISO-639-3: nld
English ISO-639-3: eng
Esperanto ISO-639-3: epo
Estonian ISO-639-3: est
Faroese ISO-639-3: fao
Fijian ISO-639-3: fij
Finnish ISO-639-3: fin
French ISO-639-3: fra
Fulfulde Adamawa ISO-639-3: fub
Georgian ISO-639-3: kat
German ISO-639-3: deu
Greek ISO-639-3: ell
Guerrero Nahuatl ISO-639-3: ngu
Gujarti ISO-639-3: guj
Haitian Creole ISO-639-3: hat
Hausa ISO-639-3: hau
Hawaiian ISO-639-3: haw
Hebrew ISO-639-3: heb
Hiligaynon ISO-639-3: hil
Hindi ISO-639-3: hin
Hungarian ISO-639-3: hun
Icelandic ISO-639-3: isl
Indonesian ISO-639-3: ind
Irish ISO-639-3: gle
Italian ISO-639-3: ita
Jacalteco ISO-639-3: jac
Japanese ISO-639-3: jpn
Kabyle ISO-639-3: kab
Kaqchikel ISO-639-3: cak
Kirghiz ISO-639-3: kir
Kisongye ISO-639-3: sop
Korean ISO-639-3: kor
Latin ISO-639-3: lat
Latvian ISO-639-3: lav
Lithuanian ISO-639-3: lit
Low Saxon ISO-639-3: nds
Macedonian ISO-639-3: mkd
Malay ISO-639-3: msa
Maltese ISO-639-3: mlt
Maori ISO-639-3: mri
Micmac ISO-639-3: mic
Mòoré ISO-639-3: mos
Ndebele ISO-639-3: nde
Nepali ISO-639-3: nep
Norwegian ISO-639-3: nor
Ojibwa ISO-639-3: oji
Pashto ISO-639-3: pus
Persian ISO-639-3: fas
Polish ISO-639-3: pol
Portuguese ISO-639-3: por
Q'eqchi' ISO-639-3: kek
Romanian ISO-639-3: ron
Romani ISO-639-3: rom
Russian ISO-639-3: rus
Serbian ISO-639-3: srp
Shona ISO-639-3: sna
Shuar ISO-639-3: jiv
Slovak ISO-639-3: slk
Slovenian ISO-639-3: slv
Spanish ISO-639-3: spa
Swahili ISO-639-3: swa
Swedish ISO-639-3: swe
Tagalog ISO-639-3: tgl
Thai ISO-639-3: tha
Todos Santos Cuchumatan Mám ISO-639-3: mvj
Turkish ISO-639-3: tur
Ukrainian ISO-639-3: ukr
Urdu ISO-639-3: urd
Uspanteco ISO-639-3: usp
Vietnamese ISO-639-3: vie
Welsh ISO-639-3: cym
Wolof ISO-639-3: wol
Xhosa ISO-639-3: xho
Zarma ISO-639-3: ssa

Overriding language detection 

curl -X POST -d "language=spanish" ...

Linked data

Linked data connects the people, places and things in your content to knowledge databases around the web. AlchemyLanguage supports the following linked data resources in Entity, Concept, and Relation extraction calls.

  • DBpedia - a crowd-sourced community effort to extract structured information from Wikipedia and make this information available on the Web.
  • Freebase - a community-curated database of well-known people, places and things.
  • US Census - quick, easy access to facts about people, business, and geography.
  • GeoNames - the GeoNames geographical database covers all countries and contains over eight million placenames that are available for download free of charge.
  • UMBEL - the "Upper Mapping and Binding Exchange Layer," it's designed to help content interoperate on the Web.
  • OpenCyc - the gateway to the full power of Cyc, the world's largest and most complete general knowledge base and commonsense reasoning engine.
  • YAGO - a huge semantic knowledge base containing more than 120 million facts about more than 10 million entities.
  • MusicBrainz - an open music encyclopedia that collects music metadata and makes it available to the public.
  • CIA Factbook - provides information on the history, people, government, economy, geography, communications, transportation, military, and transnational issues for 267 world entities.
  • CrunchBase - the free database of technology companies, people, and investors that anyone can edit.

In the example entity extraction response shown, "Barack Obama" is identified in DBpedia, Freebase, and YAGO, so the links to those entries appear in the response.

Entity extraction response with linked data 


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "",
  "language": "english",
  "entities": [
    {
      "type": "Person",
      "relevance": "0.33",
      "count": "1",
      "text": "Barack Obama",
      "disambiguated": {
        "subType": [
          "Politician",
          "President",
          "Appointer",
          "AwardWinner",
          "Celebrity",
          "PoliticalAppointer",
          "U.S.Congressperson",
          "USPresident",
          "TVActor"
        ],
        "name": "Barack Obama",
        "website": "http://www.whitehouse.gov/",
        "dbpedia": "http://dbpedia.org/resource/Barack_Obama",
        "freebase": "http://rdf.freebase.com/ns/m.02mjmr",
        "yago": "http://yago-knowledge.org/resource/Barack_Obama"
      }
    }
  ]
}

Supported microformats

The AlchemyLanguage Microformats function recognizes and extracts the following microformats data standards:

hCard
  • FormattedName
  • NameFamilyName
  • NameGivenName
  • NamePrefix
  • NameSuffix
  • OrgName
  • Role
  • Telephone
  • Title
  • Url
  • all supported geo properties listed below
  • all supported adr properties listed below
geo
  • GeoLatitude
  • GeoLongitude
adr
  • AddrStreetAddress
  • AddrExtendedAddress
  • AddrPostOfficeBox
  • AddrLocality
  • AddrPostalCode
  • AddrCountry
rel-tag
  • RelTag
  • RelTagLink
rel-license
  • RelLicense

Example response with microformats data 


{
  "status": "OK",
  "usage": "By accessing AlchemyAPI or using information generated by AlchemyAPI, you are agreeing to be bound by the AlchemyAPI Terms of Use: http://www.alchemyapi.com/company/terms.html",
  "url": "http://microformats.org/wiki/hcard",
  "microformats": [
    {
      "field": "RelTagLink",
      "data": "/wiki/Category:Specifications"
    },
    {
      "field": "RelTag",
      "data": "Category:Specifications"
    },
    {
      "field": "NameGivenName",
      "data": "Tantek"
    },
    {
      "field": "NameFamilyName",
      "data": "Çelik"
    },
    {
      "field": "FormattedName",
      "data": "Tantek Çelik"
    },
    {
      "field": "Role",
      "data": "Editor"
    },
    {
      "field": "Role",
      "data": "Author"
    }
  ]
}
Curl Node Java Python