Annotator API

The Annotator endpoint will examine text input and return relevant classes. Currently, the annotator only returns direct annotations (hierarchy and mapping annotations are planned for a future release [as of May 2013]).

Endpoints

GET /annotator?text={input text}

example:
/annotator?text=Melanoma+is+a+malignant+tumor+of+melanocytes+which+are+found+predominantly+in+skin+but+also+in+the+bowel+and+the+eye.

Parameters

Filtering & query behavior

ontologies={ontology_id1,ontology_id2,ontology_id3}
max_level={0..N}

Response Formats

Notes

• ... indicates that similar items to the previous will continue in the list
• // indicates a comment (text after this should not appear in response)
• {value1|value2} indicates expected values:

Annotation JSON

[
    {
        "annotatedClass": {
            "@id": "http://purl.bioontology.org/ontology/HL7/C0796561",
            "@type": "http://www.w3.org/2002/07/owl#Class",
            "links": {
                "self": "http://stagedata.bioontology.org/ontologies/HL7/classes/http%3A%2F%2Fpurl.bioontology.org%2Fontology%2FHL7%2FC0796561",
                "ontology": "http://stagedata.bioontology.org/ontologies/HL7",
                "children": "http://stagedata.bioontology.org/ontologies/HL7/classes/http%3A%2F%2Fpurl.bioontology.org%2Fontology%2FHL7%2FC0796561/children",
                "parents": "http://stagedata.bioontology.org/ontologies/HL7/classes/http%3A%2F%2Fpurl.bioontology.org%2Fontology%2FHL7%2FC0796561/parents",
                "descendants": "http://stagedata.bioontology.org/ontologies/HL7/classes/http%3A%2F%2Fpurl.bioontology.org%2Fontology%2FHL7%2FC0796561/descendants",
                "ancestors": "http://stagedata.bioontology.org/ontologies/HL7/classes/http%3A%2F%2Fpurl.bioontology.org%2Fontology%2FHL7%2FC0796561/ancestors",
                "tree": "http://stagedata.bioontology.org/ontologies/HL7/classes/http%3A%2F%2Fpurl.bioontology.org%2Fontology%2FHL7%2FC0796561/tree",
                "@context": {
                    "self": "http://www.w3.org/2002/07/owl#Class",
                    "ontology": "http://data.bioontology.org/metadata/Ontology",
                    "children": "http://www.w3.org/2002/07/owl#Class",
                    "parents": "http://www.w3.org/2002/07/owl#Class",
                    "descendants": "http://www.w3.org/2002/07/owl#Class",
                    "ancestors": "http://www.w3.org/2002/07/owl#Class",
                    "tree": "http://www.w3.org/2002/07/owl#Class"
                }
            },
            "@context": {
                "@vocab": "http://data.bioontology.org/metadata/"
            }
        },
        "hierarchy": [ ],
        "annotations": [
            {
                "from": 1,
                "to": 8,
                "matchType": "PREF"
            }
        ]
    },
    . . .
]

Annotator JSON Schema

JSON-schema for description and validation of REST JSON responses.

• http://tools.ietf.org/id/draft-zyp-json-schema-03.html
• http://tools.ietf.org/html/draft-zyp-json-schema-03

{
  "type": "array",
  "title": "annotations",
  "description": "An array of annotator objects.",
  "items": { "type": "object" }
}

{
    "type": "object",
    "title": "annotator",
    "description": "An annotator object.",
    "additionalProperties": false,
    "properties": {
        "annotatedClass": { "type": "object", "required": true },
        "hierarchy": { "type": "array", "required": true },
        "annotations": { "type": "array", "required": true }
    }
}

{
    "type": "object",
    "title": "annotatedClass",
    "description": "An annotator annotatedClass object.",
    "additionalProperties": false,
    "properties": {
        "@id": { "type": "string", "format": "uri", "required": true },
        "@type": { "type": "string", "format": "uri", "required": true },
        "links": { "type": "object", "required": true },
        "@context": { "type": "object", "required": true }
    }
}

{
    "type": "object",
    "title": "annotated class links",
    "description": "An annotated class links object.",
    "additionalProperties": false,
    "properties": {
        "self": { "type": "string", "format": "uri", "required": true },
        "ontology": { "type": "string", "format": "uri", "required": true },
        "children": { "type": "string", "format": "uri" },
        "parents": { "type": "string", "format": "uri" },
        "descendants": { "type": "string", "format": "uri" },
        "ancestors": { "type": "string", "format": "uri" },
        "tree": { "type": "string", "format": "uri" },
        "@context": { "type": "object" }
    }
}

{
    "type": "object",
    "title": "annotation list item",
    "description": "An annotator annotation list item.",
    "additionalProperties": false,
    "properties": {
        "from": { "type": "number", "required": true },
        "to": { "type": "number", "required": true },
        "matchType": { "type": "string", "required": true }
    }
}