FAQ - OpenCalais API

How do I ...?

Q: How can I create simple manual post?

A: See the code examples.

Q: How can I implement traffic compression?

A: See the detailed guidelines.

Q: If I'm using JavaScript to send content to OpenCalais, what must I do?

A: Programmers using JavaScript to send content and use ‘escape(myContent)’ function to escape the content need to change it to: ‘encodeURIComponent(myContent)’.
For example:

                var clfsws = new XMLHttpRequest();
                clfsws.open("POST", "http://api.opencalais.com/enlighten/rest/", true);
                clfsws.onreadystatechange = function() { _this.swsStateChangeCallback(); };
                clfsws.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
                clfsws.setRequestHeader('User-Agent', 'My very very smart user agent');
                clfsws.send("licenseID=thisismylicenseid&content=" + encodeURIComponent(content) + '&paramsXML=' + encodeURIComponent('<c:params xmlns:c="http://s.opencalais.com/1/pred/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><c:processingDirectives c:contentType="text/txt" c:outputFormat="text/gnosis" c:discardMetadata=";"></c:processingDirectives><c:userDirectives c:allowDistribution="true" c:allowSearch="true" c:externalID="calaisbridge" c:submitter="calaisbridge"></c:userDirectives><c:externalMetadata c:caller="GnosisFirefox"/></c:params>'));
                                } catch (ex) {
                                                if (getShowAlert())
                                                                alert(gnosis.stringsBundle.getString('errorSending'));
                                                dump(ex);
                                }

I'm getting this error message ...

Q: I'm using Apache's HttpClient bundle to send non-English text to Calais, through OpenCalais REST endpoint. My text includes some accented characters, such as "Ségolène Royal". The OpenCalais results are stripping those characters, trashing the original text.

A: OpenCalais servers expect their url-encoded arguments to be encoded using UTF-8. HttpClient defaults to another encoding, so you must instruct it to use UTF-8 for proper url-encoding of your arguments. You can do this by setting the HTTP Content-Type header as follows:

postmethod.setRequestHeader("Content-Type", "application/x-www-form-urlencoded; charset=utf-8");

Q: I get error message from service - "couldn't finish process within given time limit". What does it mean?

A: Currently the text size limit is 100,000 chars, and any text longer than that will not be accepted. Large documents within this limit, however, might cause this error.

Q: When I submit XML content I get a document conversion error. What is causing this problem?

A: XMLs containing HTML-Entities, such as "&nbsp", "©", "é", "—", etc., are INVALID XMLs. You cannot include HTML entities in your XML, unless you declare them first, inside the DTD section of your XML. For instance, the following XML is invalid:

<MyText>
H&eacute;llo World &copy;
</MyText>


It becomes valid when you declare the entities, like this:

<!DOCTYPE test [
<!ENTITY copy "&#x00A9;">
<!ENTITY eacute "&#x00C9;">
]>
<MyText>
H&eacute;llo World &copy;
</MyText> 

Q: I am working with REST, using Python and get an error 403 message.

A: Take a look at this forum post for guidance.

Q: I get error message regarding root element of the Cparams XML I've sent. The XML is well formed, what could cause the problem?

A: This might be an URL-Encoding related issue. Always use URL-Encoding when using POST/GET. This is not necessary if you use a client-side SOAP layer (such as a .NET web reference or Axis in Java). 

Q: When trying to connect to the OpenCalais server, I get Proxy Authentication Error. What should I do?

A: Add proxy to your webClient, contact your system admin to get the proxy address and your credentials. See the code examples.

Q: I am using PHP SoapClient to invoke the OpenCalais Web Service, but I get "Invalid request format" errors. What can cause this?

A: This might be the result of incorrect calls to the SoapClient's function. For example, the following is a non-valid call:

$result = $client->Enlighten($key, $text, $params);

It should be:

$enlighten_params = array(
'licenseID' => $key,
'content' => $text,
'paramsXML' => $params
);

Q: I am sending text to OpenCalais but I am not getting any entities, events, and facts. When I send this text through viewer.opencalais.com, I do get the expected entities, events, and facts. What am I doing wrong?

A: Make sure, when sending pure text, to set c:contentType="TEXT/TXT" (and not c:contentType="TEXT/HTML") in the paramsXML processingDirectives.

I have a question ...

Q: How can I send content textboxes with JavaScript as Unicode?

A: When you use 'XMLHttpRequest' object to send content to OpenCalais, the content needs to be encoded. The default escape() function of JavaScript is for English only but not enough for other languages, as it converts to ASCII instead of Unicode. Therefore you need to use: encodeURIComponent(). Passing the content of the textbox with this function creates a string with Unicode characters that will be parsed correctly on the server side of OpenCalais.

Q: Do I need to url-encode the post params?

A: Yes, always url-encode when using POST/GET. This is not necessary if you use a client-side SOAP layer (such as a .NET web reference or Axis in Java).

Q: I send a POST request, but I get suspiciously small response. What can cause this?

A: Make sure you have URL-Encoded the arguments; any non-coded ampersand sign would interfere with the request arguments.

Q: Can I invoke the Enlighten web method in SOAP without using any client-side SOAP layer?

A: POST-ing to the SOAP url (".../enlighten/" or ".../enlighten/calais.asmx"): To use the SOAP url it is best if you have a client-side SOAP layer such as Axis in Java or .NET web reference. If you still choose to manually construct your SOAP envelope and POST, observe the following:

1. Use text/sml content type.
2. XML-escape your arguments (emphasis on paramsXML).
3. Make sure your content-length is accurate.
4. Make sure the resulting SOAP-envelope is a well-formed XML.

Nevertheless, this practice is not recommended. It is better to use REST. (This information is also included in the API Calls documentation.)

Q: How do I use ActionScript with OpenCalais?

A: Open Calais supports JSON output - that can help you use ActionScripts. Please use the paramsXML and configure outputFormat=JSON.

For more info on URL request with post data, look at:
http://www.hardcode.nl/archives_9/article_442-post-request-data-in-as3.h...

For more info on JSON, look at:
http://www.cakesgood.com/2009/04/flash-cs3-actionscript-30-json-keep-it_...