Signature Tool

The signature tool retrieves signatures from the SemanticHacker API. You will need to get an access token for the API by signing up before the tool can be useful. As with all of the tools, passing no arguments, --help, or -h will display help text.

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

Help Text for signature


$ java -jar sh-tools.jar signature

Usage: java com.semantichacker.api.tools.GetSignature [OPTION]...
Get a signature from the SemanticHacker API, output defaults to pretty printing.
Mandatory Options: (-t|--token) 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)
	--dictid ID         	Get a signature from a different dictionary
	                    	(defaults to the API default dictionary)    
	--type TYPE         	Change the type of text scraping performed
	                    	on the input (defaults to API default       
	                    	scraping)                                   
	--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 from the SemanticHacker
	                    	Datafile, this allows labels without needing
	                    	to get them from the API                    
	-h, --help          	Display this help

Homepage: http://www.semantichacker.com

Note: For more information on calling the API and valid parameters, see the API Request Reference.

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 "foobar"              
 1435   0.493902        Computers/Security
 1270   0.492348        Computers/Programming/Languages/C++
 1431   0.330637        Computers/Internet/Protocols
 2120   0.311546        Society/People/Requesting_Help
 1462   0.189958        Computers/Usenet
 1285   0.170701        Computers/Programming/Languages/C
 <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 "foo" --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 "foo" --nocall
http://api.semantichacker.com/sh/api?token=TOKEN&showLabels=true&content=foo

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.

See also: The Labels File 

$ java -jar sh-tools.jar signature -t TOKEN -c "foo" --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. 

$ java -jar sh-tools.jar signature -t TOKEN -c "foobar" --labels=labels.txt
Message from server: No Significant Words 108