Category Call

Service Call:
http://api.semantichacker.com/TOKEN/category[/ConfigurationID]?

Overview

The category service call returns subject categories for text or a URL submission. From one to five category codes and optional category labels are returned for each category service call. The 759 category labels were created through modifications of the Open Directory Project classification scheme.

The API can return either Long or equivalent Short category labels to provide more granularity when classifying your text. The Long Label is the default label. For example:

Long category labels for the input URL http://www.classical.com/label/concertessentials include Arts/Music/Classical and Arts/Music/Composition.
Equivalent short category labels for the same input URL include Music/Classical and Music/Composition.

The Categorization API uses the 2010 semantic dictionary: odp_2010_categorization. This is the default configuration and is the only supported configuration. There is no need to specify a configuration ID to use the default configuration.

A note about the use of previous categorization configurations or older dictionary configurations:
The category service allows for an optional configuration ID to be provided at the end of the request path. While it is possible to specify an older configuration, this is discouraged as it may produce less accurate results. Also, you will NOT be able to replicate older category results simply by specifying an earlier configuration. View the Service Configurations page for more information. A 2010 Category Mapping document is available to assist you in moving to the latest configuration. Also, the noisy Regional categories have been removed in the 2010 configuration.

Category Call Parameters

In addition to the common request parameters, the category call has the following optional parameters.

Name Value Required
(Yes/No)		 Usage Notes
showLabels 'true' or 'false' No Can be used to indicate whether or not the response should include category labels for each numeric category ID. The default is 'false' and the response will only have numeric category IDs. Using numeric IDs and extracting labels locally from a labels file can save a significant amount of bandwidth and is highly recommended. Labels files for all configurations can be found on our Service Configurations page.
useShortLabels 'true' or 'false' No If set to 'true' a short version of the category label will be used instead of the default long label. An example short label is 'Software/Operating_Systems' instead of 'Computers/Software/Operating_Systems'. This parameter is set to 'false' by default. The 'useShortLabels' parameter is ignored unless the 'showLabels' parameter is set to 'true' and the service configuration ID provides short labels.
nCategories An integer > 0 and <= 5 No The number of categories to return. The default value is 2. Note that any value greater than the current upper limit of 5 will automatically be set to the upper limit by the system.
noThresholds 'true' or 'false' No If set to 'true' the system will not apply any cutoffs to the final set of results, possibly returning more results than normal. The default is 'false'. Note that these extra results may not be as accurate as the results that are returned when this parameter is set to 'false'.
format 'xml','json', 'tagcloud', 'jsontagcloud', 'javascripttagcloud', or 'rdf' No In addition to JSON and XML, the category service supports Tag Cloud Formats ('tagcloud', 'jsontagcloud', 'javascripttagcloud'), and RDF ('rdf') output formats. NOTE: the 'externalId' parameter is required when using the RDF output format.
linkBase http://www.somedomain.com/ No An optional parameter that is recognized if the format is 'tagcloud', 'jsontagcloud', or 'javascripttagcloud'. When specified, the href attribute for each returned <a> contained in the tag cloud will be set to <linkBase>/<conceptTag>.
linkTarget <windowName> No An optional parameter that is recognized if the format is 'tagcloud', 'jsontagcloud', or 'javascripttagcloud'. When specified, the target attribute for each returned <a> contained in the tag cloud will be set to the provided value.

XML Response Example

http://api.semantichacker.com/TOKEN/category?uri=http%3a%2f%2fwww.kernel.org&showLabels=true

<?xml version="1.0" encoding="UTF-8"?>
<response xmlns="http://www.semantichacker.com/api">
        <about>
                <requestId>FB0A0B4DAAF7A64B0D7EFE28736376BB</requestId>
                <docId>C0B1E02C7E06323EA312CC7288F865BE</docId>
                <systemType>category</systemType>
                <configId>odp_2010_categorization</configId>
                <contentType>text/html</contentType>
                <contentDigest>01D5A1DD26A2E013CDD9C3BEF0A89F86</contentDigest>
                <requestDate>2011-08-30T19:55:35+00:00</requestDate>
                <systemVersion>2.1</systemVersion>
                <sourceUri>http://www.kernel.org</sourceUri>
        </about>
        <categorizer>
                <categorizerResponse>
                        <categories>
                                <category id="293" weight="0.99999994" label="Computers/Software/Operating_Systems" />
                        </categories>
                </categorizerResponse>
        </categorizer>
</response>

JSON Response Example

http://api.semantichacker.com/TOKEN/category?uri=http%3a%2f%2fwww.kernel.org&showLabels=true&useShortLabels=true&format=json

{
    "about":     {
        "requestId": "D4BF2147257E088D62AC1D8901582DE9",
        "docId": "C0B1E02C7E06323EA312CC7288F865BE",
        "systemType": "category",
        "configId": "odp_2010_categorization",
        "contentType": "text/html",
        "contentDigest": "01D5A1DD26A2E013CDD9C3BEF0A89F86",
        "requestDate": "2011-08-30T19:56:47+00:00",
        "systemVersion": "2.1",
        "sourceUri": "http://www.kernel.org"
    },
    "categorizer": {"categorizerResponse": {"categories": [    {
        "id": "293",
        "weight": "0.99999994",
        "label": "Software/Operating_Systems"
    }]}}
}

TagCloud Response Example

http://api.semantichacker.com/TOKEN/category?uri=http%3a%2f%2fen.wikipedia.org%2fwiki%2fElectric_guitar&format=tagcloud

  <ul class="tw-cloud">
    <li class="size6">
      <a rel="tag" href="http://dmoz.org/Arts/Music/Instruments" target="_blank" title="Arts/Music/Instruments (1.000)"><span>Arts/Music/Instruments <em>(1.000)</em></span></a>
    </li>  
  </ul>

JSON TagCloud Response Example

http://api.semantichacker.com/TOKEN/category?uri=http%3a%2f%2fen.wikipedia.org%2fwiki%2fElectric_guitar&format=jsontagcloud

{ "cloudHtml" :
 "  <ul class=\"tw-cloud\">\n    <li class=\"size6\">\n      <a rel=\"tag\" href=\"http://dmoz.org/Arts/Music/Instruments\" target=\"_blank\" title=\"Arts/Music/Instruments (1.000)\"><span>Arts/Music/Instruments <em>(1.000)<\/em><\/span><\/a>\n    <\/li>  \n  <\/ul>\n"
}

Javascript TagCloud Response Example

http://api.semantichacker.com/TOKEN/category?uri=http%3a%2f%2fen.wikipedia.org%2fwiki%2fElectric_guitar&format=javascripttagcloud

var tag = { "cloudHtml" :
 "  <ul class=\"tw-cloud\">\n    <li class=\"size6\">\n      <a rel=\"tag\" href=\"http://dmoz.org/Arts/Music/Instruments\" target=\"_blank\" title=\"Arts/Music/Instruments (1.000)\"><span>Arts/Music/Instruments <em>(1.000)<\/em><\/span><\/a>\n    <\/li>  \n  <\/ul>\n"
};
document.write(tag.cloudHtml);

RDF Response Example

http://api.semantichacker.com/TOKEN/category/odp_2007_l1_1.7k?uri=http%3a%2f%2fen.wikipedia.org%2fwiki%2fElectric_guitar&externalId=r001&format=rdf

<rdf:RDF
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:twtype="http://s.textwise.com/1.0/type#"
    xmlns:dc="http://purl.org/dc/elements/1.1/"
    xmlns:tw="http://s.textwise.com/1.0/pred#" > 
  <rdf:Description rdf:about="http://d.textwise.com/1.0/dochash/b8d3030f-414a-a99b-70bf-3a0f9164b3c3">
    <rdf:type rdf:resource="http://s.textwise.com/1.0/type#DocInfo"/>
    <tw:externalId>r001</tw:externalId>
    <tw:sourceUrl>http://en.wikipedia.org/wiki/Electric_guitar</tw:sourceUrl>
  </rdf:Description>
  <rdf:Description rdf:about="http://d.textwise.com/1.0/dochash/b8d3030f-414a-a99b-70bf-3a0f9164b3c3/meta">
    <rdf:type rdf:resource="http://s.textwise.com/1.0/type#DocInfoMeta"/>
    <tw:docId rdf:resource="http://d.textwise.com/1.0/dochash/b8d3030f-414a-a99b-70bf-3a0f9164b3c3"/>
    <tw:configId>odp_2007_l1_1.7k</tw:configId>
    <tw:tagSpaceLanguage>en_US</tw:tagSpaceLanguage>
    <tw:tagSpace>http://d.textwise.com/1.0/element/odp_2007_l1_1.7k/en_US/category</tw:tagSpace>
    <tw:systemVersion>2.1</tw:systemVersion>
    <tw:contentType>text/html</tw:contentType>
    <tw:requestDate>2011-08-30T20:01:04+00:00</tw:requestDate>
    <tw:contentDigest>4716877B22FA1AA0BEA6A41ED3FC827C</tw:contentDigest>
  </rdf:Description>
  <rdf:Description rdf:about="http://d.textwise.com/1.0/element/odp_2007_l1_1.7k/en_US/category/110">
    <rdf:type rdf:resource="http://s.textwise.com/1.0/type#CategoryTag"/>
  </rdf:Description>
  <rdf:Description rdf:about="http://d.textwise.com/1.0/dochash/b8d3030f-414a-a99b-70bf-3a0f9164b3c3/Instance/1">
    <rdf:type rdf:resource="http://s.textwise.com/1.0/type#Instance"/>
    <tw:docId rdf:resource="http://d.textwise.com/1.0/dochash/b8d3030f-414a-a99b-70bf-3a0f9164b3c3"/>
    <tw:subject rdf:resource="http://d.textwise.com/1.0/element/odp_2007_l1_1.7k/en_US/category/110"/>
    <tw:weight>0.8641099</tw:weight>
  </rdf:Description>
</rdf:RDF>