Home | WebAPI | About Cocoa | Help | FeedBack

Cocoa Compact cover annotator for biological noun phrases

To get Cocoa output programmatically, send a HTTP POST request to /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." /Cocoa/api/
    "doc": {
        "info": {
            "document": "...",
            "externalMetadata": "",
            "submitter": "",
            "externalID": "",
            "id": ""
        "meta": {
            "submitterCode": "1234",
            "signature": "",
            "messages": []
        "_type": "Organism",
        "_typeGroup": "entities",
        "name": "Viruses",
        "instances": [
                "exact": "Viruses",
                "offset": 0,
                "length": 7

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." /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." /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." /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

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: These literals should be input as-is (CAPS and spaces inclusive).

Entity tags in the JSON object

The values of the "_type" property for entities in the JSON object are slightly different from the acronym tags above. To be specific, one of the following literals is returned: "Protein", "Protein part", "Chemical", "Organism", "Location", "Physiology", "Parameter", "Value", "Molecule", "Molecular Part", "Geometrical part", "Category", "Complex", "State", "Technique", "Procedure", "Company" and "Food" (and "Custom tag" for user-defined entities).

Home | Terms of Service | Contact
©2012 - NPjoint