API Response Reference

The response from any HTTP request to the API will be an XML document. This document may include a message, a signature, or both. If a signature is not present, an error code will be returned. The error code and message should help you quickly diagnose the problem. A list of possible error codes and messages is presented below.

CodeMessageExplanation
101 'No input' Neither a URL nor content text was provided with the request and there is nothing to process.
102 'No token' An authentication token was not included with the request.
103 'Invalid token' The token included with the request is not authenticated to use the system. The most common cause of this is the email confirmation has not been completed. The system will return this error until the confirmation is complete.
104 'API Not Available' The API is offline. This could be due to any number of reasons but is most likely due to a short maintenance task. If this error occurs, just try again at a later time.
105 'Maximum Length Exceeded' Your request has exceeded our system's configured maximum content length. You should write your program to limit content sent to no more then 100,000 characters to prevent this from happening.
106 'Unknown IO Error' An unknown I/O error has occurred. If a URL is sent to the API, this could mean that the URL could not be fetched.
107 'Invalid URI' The URI sent to the API as a parameter is malformed.
108 'No Significant Words' The provided content does not have enough words to produce a meaningful signature.
109 'Over load limit' Your requests to the API have exceeded the configured limit of more than 5 requests per second. You should code your application to rate limit your requests.
110 'Over minute limit' Your requests to the API have exceeded the configured limit of more than 300 requests per minute.
111 'Over hour limit' Your requests to the API have exceeded the configured limit of more than 10,000 requests per hour.
112 'Over day limit' Your requests to the API have exceeded the configured limit of more than 20,000 requests per day.

Explanation of Load Limiting

The Semantic Hacker API is a shared web resource. To be fair to everyone using the API we have limited how quickly any single user can make requests. The system is configured to allow for a minimum delay between requests of 200 milliseconds. This is tabulated as a running average of the last several requests by each user. If a user makes requests too quickly, they will be sent an 'over load limit' message as specified above. At this point, the program making requests should be designed to pause for 2 seconds. After pausing, requests will again be processed normally.

A very basic program may merely pause for 200 milliseconds between each request to adhere to this limit. However, depending on other program tasks, this may not be the efficient use of the available load. A more advanced program might use a 'Rate Limiting' algorithm similar to how a movie player displays frames and a specified rate. The maximum rate should be 5 requests per second (1 second / 200 milliseconds = 5 requests).

Example XML Responses

An HTTP request with an invalid token
http://api.semantichacker.com/sh/api?token=BADTOKEN&content=the%20art%20of%20computer%20science
and XML response.

<response>  
  <message code="103" string="Invalid token"/>
</response>

An XML response in the case of a signature and showLabels parameter being sent as true, with no message.

<response xmlns="http://www.semantichacker.com/api">
  <signature>
    <dimension label="Computers/Computer_Science/Academic_Departments/North_America" index="11011" weight="0.6952775" />

    <dimension label="Computers/Computer_Science/Academic_Departments/Europe" index="11008" weight="0.39374605" />
    <dimension label="Computers/Computer_Science/Academic_Departments/Oceania" index="11010" weight="0.31160173" />
    <dimension label="Science/Math/Academic_Departments/North_America/Undergraduate_and_Masters" index="5190" weight="0.2679401" />
    <dimension label="Computers/Computer_Science/Theoretical/Complexity_Theory/People" index="11027" weight="0.24521016" />
    <dimension label="Science/Math/Academic_Departments/North_America" index="5189" weight="0.11029301" />
    <dimension label="Computers/Computer_Science/People" index="11007" weight="0.10300408" />

    <dimension label="Computers/Computer_Science/Conferences" index="11014" weight="0.10113389" />
    <dimension label="Science/Math/Academic_Departments" index="5187" weight="0.09768124" />
    <dimension label="Society/People/Women/Science_and_Technology" index="16226" weight="0.08900166" />
    <dimension label="Reference/Libraries/Subject_Specific/Science" index="19716" weight="0.08885781" />
    <dimension label="Science/Institutions/Europe/United_Kingdom/e-Science" index="5362" weight="0.08094548" />
    <dimension label="Science/Directories" index="5487" weight="0.080226175" />

    <dimension label="Computers/Human-Computer_Interaction" index="11240" weight="0.07864371" />
    <dimension label="Reference/Education/Colleges_and_Universities/North_America/University_of_California/Irvine" index="19327" weight="0.076485805" />
    <dimension label="Health/Medicine/Education/Medical_Schools/North_America" index="11897" weight="0.07557468" />
    <dimension label="Computers/Artificial_Intelligence/People" index="9366" weight="0.07523901" />
    <dimension label="Business/Financial_Services/Insurance/Actuarial_Science/Academic_Departments/North_America" index="8110" weight="0.07380041" />
    <dimension label="Health/Medicine/Informatics/Academic/Universities" index="11884" weight="0.07193023" />

    <dimension label="Business/Information_Technology/Employment/Job_Search" index="8560" weight="0.07006004" />
    <dimension label="Science/Social_Sciences/Psychology/Cognitive/People" index="4442" weight="0.06334655" />
    <dimension label="Science/Math/Statistics/Education/Academic_Departments/North_America" index="5166" weight="0.06301088" />
    <dimension label="Business/Information_Technology/Employment/Resumes" index="8561" weight="0.053276323" />
    <dimension label="Computers/Security/Consultants/Forensics_and_Incident_Response" index="10811" weight="0.042846438" />
    <dimension label="Computers/Hardware/Technical_Support_and_Services" index="11201" weight="0.041839413" />

    <dimension label="Business/Energy_and_Environment/Waste_Management/Recycling/Electronics" index="8679" weight="0.041527715" />
    <dimension label="Computers/Computer_Science/Academic_Departments/Asia" index="11009" weight="0.040568646" />
    <dimension label="Science/Social_Sciences/Political_Science/Academic_Departments/North_America" index="4572" weight="0.040041156" />
    <dimension label="Science/Educational_Resources" index="5494" weight="0.038075063" />
    <dimension label="Society/Religion_and_Spirituality/Christianity/Denominations/Christian_Science" index="14610" weight="0.03769144" />
  </signature>

</response>