User guide

The API can be accessed with an HTTP client. Send a POST request to the /extractor endpoint with a text parameter to annotate a given text. For example:


    POST /extractor?text=This is a sample sentence. HTTP/1.1
    Host: localhost
    

You can use Postman to query the demo API. If you need to analyse a large number of texts, you will need set up POLKE locally and send the texts to the API one by one with an HTTP client of your choice.

The API returns the list of English Grammar Profile (EGP) constructs and/or tokens found in the text in the JSON format.


    {
        "annotationList": [
            {
                "begin": 9,
                "end": 21,
                "constructID": 36
            }
        ],
        "message": ""
    }
    
annotationList
All the EGP constructs found in the text. Each list item is one found construct.
begin and end
The positions of the construct in the text string.
constructID
The ID of the construct in the EGP mapping table.

Parameters

text
The text to annotate.
tokenize
Return list of tokens.
annotate
Return list of annotations. Used only for returning just the list of tokens without the annotations. Set to false and tokenize=true to return only the list of tokens.

Mapping table

Each construct ID maps to an entry in the mapping table and contains the data from the EGP for the given construct: supercategory, subcategory, CEFR level, guideword, can-do statement, and learner example.

The mapping table can be downloaded here.