Web API: Text Categorization

AlchemyAPI provides easy-to-use facilities for categorizing 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 classify the content by topic. 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.

API Call: URLGetCategory

Description: The URLGetCategory call is utilized to categorize a webpage. AlchemyAPI will download the requested URL, extracting text and other important content from the HTML document structure, and perform document categorization operations.

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

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
rel-tag
rel-tag-raw

(optional parameter)

jsonp

desired JSONP callback

(optional parameter, requires "outputMode" to be set to json)

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)
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.

(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)

baseUrl

rel-tag output base http url

(optional parameter, used with rel-tag or rel-tag-raw outputMode. must be uri-argument encoded)

Response Format (XML):

<results>
    <status>REQUEST_STATUS</status>
    <url>REQUESTED_URL</url>
    <category>DETECTED_CATEGORY</category>
    <score>CATEGORY_SCORE</score>
</results>

Response Format (JSON):

{
    "status": "REQUEST_STATUS",
    "url": "REQUESTED_URL",
    "category": "DETECTED_CATEGORY",
    "score": "CATEGORY_SCORE"
}

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:Language>DOCUMENT_LANGUAGE</aapi:Language>
        <aapi:URL>DOCUMENT_URL</aapi:URL>
        <aapi:DocCateg>DETECTED_CATEGORY</aapi:DocCateg>
        <aapi:CategScore>CATEGORY_SCORE</aapi:CategScore>
    </rdf:Description>
</rdf:RDF>

Response Format (REL-TAG Microformat [raw] ):

<a href="REQUESTED_BASE_URL/DETECTED_CATEGORY" rel="tag">DETECTED_CATEGORY</a>

Response Fields:

field name	field description
status	success / failure status indicating whether the request was processed. Possible values: OK ERROR
url	http url information was requested for.
category	detected category. Possible values: (click to see list)
score	confidence score for the detected category 0.0 .. 1.0 (higher is better).
statusInfo	failure status information (sent only if "status" == "ERROR"). Possible values: invalid-api-key cannot-retrieve page-is-not-html

Example Call:

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

API Notes:

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

Web API