PONK API Reference

PONK REST API web service is available on http(s)://quest.ms.mff.cuni.cz/ponk/api/.

The service is freely available for testing under these terms of use. Explicit written permission of the authors of PONK and the external services called (UDPipe and NameTag) is required for any commercial exploitation of the system.

Anonymity

To maintain anonymity at the REST API server, neither PONK, nor the external services UDPipe and NameTag, log the processed texts.
The only information that may be logged is: time of usage, size of the processed data, the system configuration and the IP address from where it is accessed.

If you wish to maintain anonymity when using the service via REST API, make sure to use the POST method, as REST API URLs may also be logged.

All comments and reactions are welcome.

API Reference

The PONK REST API can be accessed directly or via web programming tools that support standard HTTP request methods and JSON for output handling.

Method process

Process the given data as described in the User's Manual.

The response is in JSON format of the following structure:

{
 "message": "overview_message"
 "result": "processed_output"
 "stats": "statistics"
 "app1_features": "list_of_used_rules_app1"
 "app1_rule_info": "properties_of_used_rules_app1"
}

overview_message is a short comprehensible message of what has been called;
processed_output is the output of PONK in the requested output format;
statistics is an HTML overview giving the PONK version, length of the text, processing time and information on the readability of the text as a whole.;
list_of_used_rules_app1 is an HTML list of rules from subapplication 1 that were used in the given text;
properties_of_used_rules_app1 is a JSON structure with information about rules from subapplication 1 that were used in the given text.

Method info

Returns the info about the server - the PONK version and a list of supported features. The method does not have parameters.

The response is in JSON format of the following structure:

{
 "version": "PONK_version"
 "features": "supported_features"
}

The PONK_version is the version of the server consisting of the version number and the creation date; in case of an anonymized server (without text logging), these are followed by the string "(no text logging)",
and supported_features is a list of the analysis features, separated by '•'.

Browser Example

http://quest.ms.mff.cuni.cz/ponk/api/process?input=txt&text=Váš dlužník Vám na žádost do tří dnů vystaví potvrzení o čísle účtu, z něhož Vám vyplácí peníze. Pokud nás o to požádáte, zajistíme potvrzení sami.

Accessing API using Curl

The described API can be comfortably used by curl. Several examples follow:

Passing Input on Command Line (if UTF-8 locale is being used)

curl --data 'input=txt&output=html&text=Váš dlužník Vám na žádost do tří dnů vystaví potvrzení o čísle účtu, z něhož Vám vyplácí peníze. Pokud nás o to požádáte, zajistíme potvrzení sami.' http://quest.ms.mff.cuni.cz/ponk/api/process

Using Files as Input (files must be in UTF-8 encoding)

curl --data-urlencode 'input=txt' --data-urlencode 'output=html' --data-urlencode 'text@input_file.txt' http://quest.ms.mff.cuni.cz/ponk/api/process

Converting JSON Result to Plain Text

curl --data 'input=txt&output=html&text=Váš dlužník Vám na žádost do tří dnů vystaví potvrzení o čísle účtu, z něhož Vám vyplácí peníze. Pokud nás o to požádáte, zajistíme potvrzení sami..' http://quest.ms.mff.cuni.cz/ponk/api/process | PYTHONIOENCODING=utf-8 python3 -c "import sys,json; sys.stdout.write(json.load(sys.stdin)['result'])"