Cocoa annotator WebAPI

To get Cocoa output programmatically, send a HTTP POST request to http://npjoint.com/Cocoa/api/ with URI encoded data containing the desired text (in ASCII or UTF-8). This call returns a JSON object containing the entities tagged by Cocoa.

$ curl -d "outputFormat=json&apikey=1234&text=Viruses." http://npjoint.com/Cocoa/api/
{
    "doc": {
        "info": {
            "document": "...",
            "externalMetadata": "",
            "submitter": "127.0.0.1",
            "externalID": "",
            "id": "http://npjoint.com"
        },
        "meta": {
            "submitterCode": "1234",
            "signature": "",
            "messages": []
        }
    },
"1":
    {
        "_type": "Organism",
        "_typeGroup": "entities",
        "name": "Viruses",
        "instances": [
            {
                "exact": "Viruses",
                "offset": 0,
                "length": 7
            }
        ]
    },
}

Each entity has a unique ID of the form "N" where N is a unique number for a particular occurrence of the entity in the current document
The values of the "_type" property are more fully described in this page. The actual literals are described in the section on tags below.
The value of the "_typegroup" property is always "entities".
The value of the "exact" subproperty is the text in the span region, except that adjacent newlines, carriage returns and spaces are all compacted to a single space character.
The values of the "offset" and the "length" subproperties are as defined in the Open Calais format.
The value of the "name" property is a copy of the value for the "exact" property (for now).

The output above is a minimal subset of the JSON object returned by Open Calais. The Cocoa API in fact also accepts Open Calais style JSON requests, and returns the same output as above; see e.g., the OpenCalais plugin in GATE.

GENIA/Brat compatible A1 output is returned by setting the outputFormat parameter to a1 thusly:

$ curl -d "outputFormat=a1&apikey=1234&text=Viruses." http://npjoint.com/Cocoa/api/
T1      Organism 0 7    Viruses

Cocoa can be called from within the brat annotator by setting the setting the outputFormat parameter to a1j. This option is probably not useful for a program call.

Setting the outputFormat parameter to b1 retrieves extended annotations from Cocoa. Compare the following ('a1' output):

$ curl -d "outputFormat=a1&apikey=1234&text=A smorgasbord: Liver cancer, chromatophores and tigers." http://npjoint.com/Cocoa/api/
T1      Physiology 15 27        Liver cancer
T2      Body_part 29 43 chromatophores
T3      Organism 48 54  tigers

with this ('b1' output):

$ curl -d "outputFormat=b1&apikey=1234&text=A smorgasbord: Liver cancer, chromatophores and tigers." http://npjoint.com/Cocoa/api/
T1      Disease 15 27        Liver cancer
T2      Cellular_component 29 43        chromatophores
T3      Organism1 48 54 tigers
T4      Organ 15 20     Liver

Required Parameters

text :- the URI-encoded text/data, should be less than 10000 characters.

outputFormat :- 'json', 'a1', 'a1j', 'b1'. The 'a1j' output is specific to the brat annotator. 'b1' returns extended annotations.

apikey :- your API key (use "1234" for now)

Optional Parameters

code :- 'utf8'; use this if the input text is in UTF-8 (default is ASCII)
An undefined acronym may be interpreted somewhat randomly by the system. To help processing, you may wish to pre-define acronyms with the acronym parameter.
acronym :- a URI-encoded string that is the acronym followed by its expansion and then by a predefined tag (see below) . These fields should be separated by a pipe ("|") symbol. An example is acronym=DC|discus cells|BODY PART

Multiple acronym definitions can be given. Each definition should be separated from the next by a newline ("\n").

Cocoa detects and tags chemical formulas. However, tagging of formulas may be undesirable for documents with abbreviations which resemble chemical formulas (or protein sequences). For such documents, turn off formula tagging by setting the mode parameter.

mode :- 'noform' - turn off formula detection; 'minform' - do not tag abbreviations in pure CAPS; formulae with a lowercase letter or a numeral will be tagged.

Compare these outputs:

$ curl -d "outputFormat=a1&apikey=1234&text=HBr, H2O, GGGG, and ABCD." http://npjoint.com/Cocoa/api/
T1      Chemical 0 3    HBr
T2      Chemical 5 8    H2O
T3      Protein_part 10 14      GGGG
T4      Unknown 20 24   ABCD

$ curl -d "mode=minform&outputFormat=a1&apikey=1234&text=HBr, H2O, GGGG, and ABCD." http://npjoint.com/Cocoa/api/
T1      Chemical 0 3    HBr
T2      Chemical 5 8    H2O
T3      Unknown 10 14   GGGG
T4      Unknown 20 24   ABCD

$ curl -d "mode=noform&outputFormat=a1&apikey=1234&text=HBr, H2O, GGGG, and ABCD." http://npjoint.com/Cocoa/api/
T1      Unknown 0 3     HBr
T2      Unknown 5 8     H2O
T3      Unknown 10 14   GGGG
T4      Unknown 20 24   ABCD

Use the custom tag CTAG in a pseudo-acronym definition to prevent Cocoa from processing a pre-defined entity. Compare:

$ curl -d "outputFormat=a1&apikey=1234&acronym=HBr|humongous breakthrough|CTAG&text=HBr, H2O, GGGG, and ABCD." http://npjoint.com/Cocoa/api/
T1      Custom_tag 0 3  HBr
T2      Chemical 5 8    H2O
T3      Protein_part 10 14      GGGG
T4      Unknown 20 24   ABCD

$ curl -d "outputFormat=a1&apikey=1234&acronym=ABCD|a blank compact disc|CTAG&text=HBr, H2O, GGGG, and ABCD." http://npjoint.com/Cocoa/api/
T1      Chemical 0 3    HBr
T2      Chemical 5 8    H2O
T3      Protein_part 10 14      GGGG
T4      Custom_tag 20 24        ABCD

Note: Context-sensitive tagging is never turned off, so your mileage with the acronym and mode parameters may vary.

Return Values

200 Ok

404: No text to process

503 Output format unavailable

504 Bad API/license key

505 Processing error

Entity tags

Entity tags for acronyms

Entity tags are used in on-the-fly acronym definitions. Allowed tag literals for acronyms are:

PROTEIN: Proteins or genes e.g., cytochrome P-450
CHEMICAL: Chemicals e.g., N(omega)-nitro-L-arginine methyl ester
PPART: Protein/DNA parts e.g., Lys-23, E30K
MOLECULE: Ambiguous entities; could be either chemicals or proteins/DNA e.g., chromophore, photon
ORGANISM: Organisms e.g., rat, sauropod, Ectothiorhodospira halophila
PROCESS: Actions, events and processes e.g., protonation, cleavage
BODY PART: Cells, organs, tissues or anatomical structures e.g., hindlimb
DISEASE: Physiological states, conditions and symptoms e.g., stress, disease
PARAMETER: Parameters, e.g., systemic arterial pressure, open probability
EXPERIMENT: Techniques e.g., spectroscopy, patch clamping
PROCEDURE: Surgical procedures e.g., resection, hysterectomy
FOOD: e.g., bread
CTAG: Predefined entities.

These literals should be input as-is (CAPS and spaces inclusive).

Entity tags in the JSON object