To provide a programmatic interface to the ERG on-line demonstrator, a sub-set of its functionality is available via a RESTful (HTTP-based) application program interface (API). Through this interface, parsing requests can be submitted anonymously to a server at the University of Oslo, and processing results will be returned in machine-readable form to the requester.

This service is still under development and has not been broadly tested. The following terse sections aim to provide minimal documentation to users who might want to obtain ERG parses without creating their own installation of the DELPH-IN software stack. Michael Goodman and NedLetcher have contributed substantially to the design and testing of the interface; StephanOepen maintains the server-side implementation based on the LKB and [incr tsdb()] environments.

A First Example

In a nutshell, the API is accessed through HTTP GET requests to the following base URI: There is one required parameter, named input, to provide a string for the parser to analyze. The HTTP response will be of type application/json and will contain some high-level statistics about the parsing process (e.g. the number of distinct readings and overall parsing time), as well as an array of result structures. At present, three perspectives on each parsing result are available (with more in the making): its derivation tree (e.g. the full recipe for deriving this analysis; see the ItsdbDerivations page), an underspecified logical-form meaning representation in Minimal Recursion Semantics (MRS; see the ErgSemantics page for background), and a simplification of the semantics as an Elementary Dependency Structure (EDS; see the EdsTop page for background).

For example, the query will request the on-line service to parse the string Abrams arrived. Note how some special characters, including whitespace, in the input need to be percent-encoded. The JSON document returned for this query will include the following pieces of information:

  {"readings": 1, "tcpu": 0.05,
   [{"result-id": 0,
     "derivation": { … }}]}

Parameterizing the Parser

Usage Example in Python

The following code snippets exemplify how to connect to the RESTful parsing service using Python 2.6 or upwards.

import urllib, json
base = ""
input = urllib.quote("Have her report on my desk!")
fd = urllib.urlopen("%s?nresults=2&input=%s" % (base, input))
item = json.load(fd)
eds = item["results"][0]["eds"]

Known Limitations

As of Easter 2016, there are still a few necessary pieces missing in the interface, including

  1. error reporting in case of parse failures (e.g. due to resource limitations or lexical gaps);
  2. more control over resource usage (and sensible ceilings) and the choice of grammar start symbols; and
  3. inclusion of additional information from the [incr tsdb()] result structure.

Once these basic additions are in place, it would be nice if user uptake were to call for bandwidth limitation mechanisms (which will be easy to enforce in the proxy server). More contentfully, one could also speculate about providing additional methods, for example POST-ing a structure (like an MRS or EDS) for conversion to additional output views, querying the SEM-I, or of course invoking sentence realization.

ErgApi (last edited 2017-04-16 11:43:52 by StephanOepen)

(The DELPH-IN infrastructure is hosted at the University of Oslo)