Back to Top

 

Web API

Web API: Sentiment Analysis

AlchemyAPI provides easy-to-use facilities for extracting positive/negative sentiment from your publicly-accessible web-based content. These URL processing calls automatically fetch the desired Internet webpage, normalize/clean it (removing ads, navigation links, and other unimportant content), and extract text sentiment. These API calls may be utilized to process hosted webpages, blogs, and other publicly-accessible Internet content. If you are processing content that is not hosted on a public webserver, use our HTML API calls instead.

URLGetTextSentiment Extract positive/negative sentiment from a given web page.
URLGetTargetedSentiment Extract positive/negative sentiment targeted towards a specific phrase inside the text of a given web page.

API Call: URLGetTextSentiment

Description: The URLGetTextSentiment call is utilized to extract positive/negative sentiment from a given web page. AlchemyAPI will download the requested URL, extracting text from the HTML document structure (ignoring navigation links, advertisements, and other undesireable content), and perform sentiment extraction operations.

Endpoint: http://access.alchemyapi.com/calls/url/URLGetTextSentiment

Parameters:

http argument parameter description
url http url (must be uri-argument encoded)

(required parameter)
apikey your private api key

(required parameter)
outputMode desired API output format

Possible values:
xml (default)
json
rdf


(optional parameter)
jsonp desired JSONP callback

(optional parameter, requires "outputMode" to be set to json)
showSourceText whether to include the original 'source text' the sentiment was extracted from within the API response.

Possible values:
1 - enabled
0 - disabled (default)

(optional parameter)
sourceText where to obtain the text that will be processed by this API call.

AlchemyAPI supports multiple modes of text extraction: web page cleaning (removes ads, navigation links, etc.), raw text extraction (processes all web page text, including ads/nav links), visual constraint queries, and XPath queries.

Possible values:
cleaned_or_raw cleaning enabled, fallback to raw when cleaning produces no text (default)
cleaned operate on 'cleaned' web page text (web page cleaning enabled)
raw operate on raw web page text (web page cleaning disabled)
xpath operate on the results of an XPath query

Note: The 'xpath' http argument must also be set to a valid XPath query.
cleaned_and_xpath operate on 'cleaned' web page text (web page cleaning enabled) combined with the results of an XPath query

Note: The 'xpath' http argument must also be set to a valid XPath query.
xpath_or_raw operate on the results of an XPath query, fallback to raw when XPath no text (default)

Note: The 'xpath' http argument must also be set to a valid XPath query.

(optional parameter)
xpath an XPath query to apply to the web page.

XPath queries enable API operations to be performed on a targeted area of a web page, such as a story title or product description.

(optional parameter, used when sourceText is set to 'xpath'. must be uri-argument encoded)

Response Format (XML):

<results>
    <status>REQUEST_STATUS</status>
    <url>REQUESTED_URL</url>
    <language>DOCUMENT_LANGUAGE</language>
    <text>DOCUMENT_TEXT</text>
    <docSentiment>
        <type>SENTIMENT_LABEL</type>
        <score>DOCUMENT_SENTIMENT</score>
        <mixed>SENTIMENT_MIXED</mixed>
    </docSentiment>
</results>

Response Format (JSON):

{
    "status": "REQUEST_STATUS",
    "url": "REQUESTED_URL",
    "language": "DOCUMENT_LANGUAGE",
    "text": "DOCUMENT_TEXT",
    "docSentiment": {
        "type": "SENTIMENT_LABEL",
        "score": "DOCUMENT_SENTIMENT",
        "mixed": "SENTIMENT_MIXED"
    }
}

Response Format (RDF):

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
                 xmlns:aapi="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#"
                 xml:base="http://rdf.alchemyapi.com/rdf/v1/r/response.rdf">
    <rdf:Description rdf:ID="DOCUMENT_HASH">
        <rdf:type rdf:resource="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#DocInfo"/>
        <aapi:ResultStatus>REQUEST_STATUS</aapi:ResultStatus>
        <aapi:URL>DOCUMENT_URL</aapi:URL>
        <aapi:Language>DOCUMENT_LANGUAGE</aapi:Language>
        <aapi:DocText>DOCUMENT_TEXT</aapi:DocText>
        <aapi:Sentiment>
            <rdf:Description rdf:ID="DOCUMENT_HASH">
                <rdf:type rdf:resource="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#Sentiment"/>
                <aapi:Doc>DOCUMENT_HASH</aapi:Doc>
                <aapi:SentimentType>SENTIMENT_LABEL</aapi:SentimentType>
                <aapi:SentimentScore>DOCUMENT_SENTIMENT</aapi:SentimentScore>
                <aapi:SentimentMixed>SENTIMENT_MIXED</aapi:SentimentMixed>
            </rdf:Description>
        </aapi:Sentiment>
    </rdf:Description>
</rdf:RDF>

Response Fields:

field name field description
status success / failure status indicating whether the request was processed.

Possible values:
OK
ERROR
language the detected language that the source text was written in.
url http url information was requested for.
type sentiment polarity: "positive", "negative", or "neutral"
score sentiment strength (0.0 == neutral)
mixed whether sentiment is mixed (both positive and negative) (1 == mixed)
statusInfo failure status information (sent only if "status" == "ERROR").

Possible values:
invalid-api-key
cannot-retrieve
page-is-not-html
unsupported-text-language

Example Call:

XML: http://access.alchemyapi.com/calls/...
RDF: http://access.alchemyapi.com/calls/...

API Notes:

  1. Calls to URLGetTextSentiment can be made using HTTP GET or POST.
  2. HTTP POST calls should include the Content-Type header: application/x-www-form-urlencoded
  3. URL retrieval is attempted for a maximum of 10 seconds. Requests taking longer than this will result in a "cannot-retrieve" error response.
  4. Requested HTML documents can be a maximum of 600 kilobytes. Larger documents will result in a "content-exceeds-size-limit" error response.
  5. Language detection is performed on the retrieved document before attempting sentiment analysis. A minimum of 15 characters of text must exist within the requested HTTP document to perform language detection.
  6. Documents containing less than 15 characters of text are assumed to be English-language content.

API Call: URLGetTargetedSentiment

Description: The URLGetTargetedSentiment call is utilized to extract positive / negative sentiment targeted towards a specific user-specified target phrase inside the text of a given web page. AlchemyAPI will download the requested URL, extracting text from the HTML document structure (ignoring navigation links, advertisements, and other undesireable content), and perform sentiment extraction operations.

Endpoint: http://access.alchemyapi.com/calls/url/URLGetTargetedSentiment

Parameters:

http argument parameter description
target target phrase (must be uri-argument encoded) - sentiment targeted towards this phrase will be extracted from the text

(required parameter)
url http url (must be uri-argument encoded)

(required parameter)
apikey your private api key

(required parameter)
outputMode desired API output format

Possible values:
xml (default)
json
rdf


(optional parameter)
jsonp desired JSONP callback

(optional parameter, requires "outputMode" to be set to json)
showSourceText whether to include the original 'source text' the sentiment was extracted from within the API response.

Possible values:
1 - enabled
0 - disabled (default)

(optional parameter)
sourceText where to obtain the text that will be processed by this API call.

AlchemyAPI supports multiple modes of text extraction: web page cleaning (removes ads, navigation links, etc.), raw text extraction (processes all web page text, including ads / nav links), visual constraint queries, and XPath queries.

Possible values:
cleaned_or_raw cleaning enabled, fallback to raw when cleaning produces no text (default)
cleaned operate on 'cleaned' web page text (web page cleaning enabled)
raw operate on raw web page text (web page cleaning disabled)
cquery operate on the results of a visual constraints query

Note: The 'cquery' http argument must also be set to a valid visual constraints query.
xpath operate on the results of an XPath query

Note: The 'xpath' http argument must also be set to a valid XPath query.
cleaned_and_xpath operate on 'cleaned' web page text (web page cleaning enabled) combined with the results of an XPath query

Note: The 'xpath' http argument must also be set to a valid XPath query.

(optional parameter)
cquery a visual constraints query to apply to the web page.

Constraint queries enable API operations to be performed on a targeted area of a web page, such as a story title or product description.

(optional parameter, used when sourceText is set to 'cquery'. must be uri-argument encoded)
xpath an XPath query to apply to the web page.

XPath queries enable API operations to be performed on a targeted area of a web page, such as a story title or product description.

(optional parameter, used when sourceText is set to 'xpath'. must be uri-argument encoded)

Response Format (XML):

<results>
    <status>REQUEST_STATUS</status>
    <url>REQUESTED_URL</url>
    <language>DOCUMENT_LANGUAGE</language>
    <text>DOCUMENT_TEXT</text>
    <docSentiment>
        <type>SENTIMENT_LABEL</type>
        <score>DOCUMENT_SENTIMENT</score>
        <mixed>SENTIMENT_MIXED</mixed>
    </docSentiment>
</results>

Response Format (JSON):

{
    "status": "REQUEST_STATUS",
    "url": "REQUESTED_URL",
    "language": "DOCUMENT_LANGUAGE",
    "text": "DOCUMENT_TEXT",
    "docSentiment": {
        "type": "SENTIMENT_LABEL",
        "score": "DOCUMENT_SENTIMENT",
        "mixed": "SENTIMENT_MIXED"
    }
}

Response Format (RDF):

<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
                 xmlns:aapi="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#"
                 xml:base="http://rdf.alchemyapi.com/rdf/v1/r/response.rdf">
    <rdf:Description rdf:ID="DOCUMENT_HASH">
        <rdf:type rdf:resource="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#DocInfo"/>
        <aapi:ResultStatus>REQUEST_STATUS</aapi:ResultStatus>
        <aapi:URL>DOCUMENT_URL</aapi:URL>
        <aapi:Language>DOCUMENT_LANGUAGE</aapi:Language>
        <aapi:DocText>DOCUMENT_TEXT</aapi:DocText>
        <aapi:Sentiment>
            <rdf:Description rdf:ID="DOCUMENT_HASH">
                <rdf:type rdf:resource="http://rdf.alchemyapi.com/rdf/v1/s/aapi-schema#Sentiment"/>
                <aapi:Doc>DOCUMENT_HASH</aapi:Doc>
                <aapi:SentimentType>SENTIMENT_LABEL</aapi:SentimentType>
                <aapi:SentimentScore>DOCUMENT_SENTIMENT</aapi:SentimentScore>
                <aapi:SentimentMixed>SENTIMENT_MIXED</aapi:SentimentMixed>
            </rdf:Description>
        </aapi:Sentiment>
    </rdf:Description>
</rdf:RDF>

Response Fields:

field name field description
status success / failure status indicating whether the request was processed.

Possible values:
OK
ERROR
language the detected language that the source text was written in.
url http url information was requested for.
type sentiment polarity: "positive", "negative", or "neutral"
score sentiment strength (0.0 == neutral)
mixed whether sentiment is mixed (both positive and negative) (1 == mixed)
statusInfo failure status information (sent only if "status" == "ERROR").

Possible values:
invalid-api-key
cannot-retrieve
page-is-not-html
unsupported-text-language
cannot-locate-keyphrase

Example Call:

XML: http://access.alchemyapi.com/calls/...
RDF: http://access.alchemyapi.com/calls/...

API Notes:

  1. Calls to URLGetTargetedSentiment can be made using HTTP GET or POST.
  2. HTTP POST calls should include the Content-Type header: application/x-www-form-urlencoded
  3. Requested HTML documents can be a maximum of 600 kilobytes. The remaining text after HTML tags are cleaned can be no larger than 50 kilobytes in size. Larger documents will result in a "content-exceeds-size-limit" error response.
  4. Language detection is performed on the retrieved document before attempting sentiment analysis. A minimum of 15 characters of text must exist within the requested HTTP document to perform language detection.
  5. Documents containing less than 15 characters of text are assumed to be English-language content.
  6. If the sentiment target is not found, a "cannot-locate-keyphrase" error response will be returned.