ErgApi

Background

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 programming 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.

As of Easter 2016, 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.

A First Example

In a nutshell, the API is accessed through HTTP GET requests to the following base URI: http://erg.delph-in.net/rest/0.9/parse. 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, two 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) and a simplification of the associated semantics as an Elementary Dependency Structure (EDS; see the EdsTop page for background).

For example, the query http://erg.delph-in.net/rest/0.9/parse?derivation=json&input=Abrams%20arrived. 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,
   "results":
   [{"result-id": 0,
     "derivation": [...]
     "eds": [...]}]}

Parameterizing the Parser

• results: integer (default: 1) Usage Example

• time (tbd)

• roots (tbd)

• derivation: json, udf, or null (default)

• mrs (tbd)

• eds: json (default), native, latex, or null

• properties json (default) or null Usage Example

• filter: regular expression (default: null) Usage Example

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 = "http://erg.delph-in.net/rest/0.9/parse"
input = urllib.quote("Have her report on my desk!")
fd = urllib.urlopen("%s?nresults=5&derivation=null&input=%s" % (base, input))
item = json.load(fd)
eds = item["results"][0]["eds"]
eds["nodes"][eds["top"]]["label"]

Known Limitations

As of Easter 2016, there are still a few necessary pieces missing in the interface, including (a) the ability to return full MRS structures (in JSON); error reporting in case of parse failures (e.g. due to resource limitations or lexical gaps); and (c) more control over resource usage (and sensible ceilings) and the choice of grammar start symbols (and maybe the use of generic lexical entries). Once these basic additions are in place, it would be nice if user uptake were to call for bandwidth limitation mechanisms (which would be easy to enforce in the proxy server). More contentfully, one could also speculate about providing additional methods, for example POSTing a structure (like an MRS or EDS) for conversion to additional output views, or of course invoking sentence realization.