Signature Tool

Overview

The Signature tool enables you to submit content via a URI, a local file, or directly within the command to the API. The resulting signature will either be displayed in the console or written out to a file.

Help Text for `signature`

The help for the signature tool can be displayed by running the following command:

	$ java -jar sh-tools.jar signature --help

Usage: java com.semantichacker.api.tools.GetSignature [OPTION]...
Get a signature from the SemanticHacker API, output defaults to pretty printing.
Mandatory Options: TOKEN (--uri|-u|--file|-f|--content|-c) PARAM

Option Summary:
	-t, --token TOKEN   	Your developer token
	-u, --uri URI       		The URI to get a signature for
	-f, --file FILE     		The file to get a signature for
	-c, --content STRING	The string to get a signature for
	-a, --api URL       		The URL of the API (default: http://api.semantichacker.com/sh/api)
	--xmlout            		Output raw XML from the API
	--outfile FILE      		Output to a file (otherwise to stdout)
	
	--configId ID   	      		Get a signature using a specific service configuration
	                	    		(defaults to the odp_2007_l1_1.7k configuration)    
	--filter FILTER         	Change the type of text filtering performed
	                	    		on the input (defaults to 'html' filtering)
	--nolabels      	    		Do not get labels from the API
	--nocall 	  	         	Do not call the API, print the URL that would be used instead
	--xmlin         	    		Do not call the API, instead read in an XML
	                	    		signature and pretty print it (-f or --file
	                	    		required)                                   
	--labels FILE   		The list of labels for the configuration that was
						used to generate the signature. This allows you to save bandwidth by using
						a local labels file instead of having them sent down via the API.
	-h, --help          		Display this help

Connecting through a proxy

There is no option built-in to the signature tool for connecting to the API through a proxy. However, you can pass Java an option to do this, the following command should tell java to use a proxy server.

	java -Dhttp.proxyHost=HOST -Dhttp.proxyPort=PORT sh-tools.jar signature

Examples

In example commands substitute TOKEN for your API access token.

Signature of a String

Getting the signature of a string is simple using this tool.

	$ java -jar sh-tools.jar signature -t TOKEN -c telescope              
 1332	0.702208	Science/Astronomy/Amateur
 1333	0.501593	Science/Astronomy/Business/Telescopes,_Binoculars_and_Accessories
 1331	0.435470	Science/Astronomy
 1334	0.185349	Science/Astronomy/Solar_System
 1335	0.119228	Science/Astronomy/Solar_System/Planets
 1437	0.076583	Science/Technology/Space
 <snip>

Note: Do not pass large amounts of text using the -c or --content, to pass large amounts of content, use the -f or --file parameter.

Signature of a File

The signature of a file can be retrieved by passing -f or --file; - (hyphen) is interpreted to mean "standard input", following the convention of Unix utilities.

	$ java -jar sh-tools.jar signature -t TOKEN -f FILE
<snip>

Signature of a Web Page

The signature of a page at particular URL can be retrieved by passing -u or --uri.

	$ java -jar sh-tools.jar signature -t TOKEN -u http://www.semantichacker.com
<snip>

Getting Raw XML

The other tools require XML from the API as input, passing --xmlout will provide the proper input for these tools. This option is best combined with --outfile or shell redirection to write the output directly to a file for use with other tools.

	$ java -jar sh-tools.jar signature -t TOKEN -c telescope --xmlout --outfile foobar.xml

Getting the URL that would be retrieved

To demonstrate the correct way to build a URL for calling the API, the --nocall parameter can be passed. This parameter tells the signature tool not to call the API, and instead to write out the URL that would have been retrieved. Note that since PUT requests are used to send file content to the API, if --file is passed then this URL alone will not be enough to get the correct results. However, for other types of data this URL can be used with command line programs such as wget or curl, or you can paste the URL into your favorite browser to see the results there.

	$ java -jar sh-tools.jar signature -t TOKEN -c telescope --nocall
http://api.semantichacker.com/TOKEN/signature/odp_2007_l1_1.7k?showLabel...

The `--labels` option

As previously mentioned, the signature tool takes a --labels parameter specifying a list of labels matching the dimensions for the SemanticHacker API. The signature tool does not use these directly, however, when a labels file is passed (and --nolabels is not) the signature tool can save bandwidth by reading labels from the file instead of requesting them from the API. Note that labels are not injected when --xmlout is specified, and --nolabels supersedes this option.

	$ java -jar sh-tools.jar signature -t TOKEN -c telescope --labels=labels.txt
<snip>

Error Messages

Except when --xmlout is used, error messages are printed to stdout or the outfile, see the API Response Reference for a list of error messages output by the API.

TextWise LLC