Categorization: Web API
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. AlchemyGrid 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) |
||||||
| 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:
(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 [XML-embedded] ):
<results>
<status>REQUEST_STATUS</status>
<url>REQUESTED_URL</url>
<score>CATEGORY_SCORE</score>
<microformats>
<a href="REQUESTED_BASE_URL/DETECTED_CATEGORY" rel="tag">DETECTED_CATEGORY</a>
</microformats>
</results>
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:
- 1. Calls to URLGetCategory 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 categorization. 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.
- return to top of page -
