TIES REST API

**** Disclaimer: This is an Alpha version of the API and is subject to changes.**

see Getting started using the API before trying to use the API.

This API provides the ability to search using controlled vocabularies (i.e., NCIT) using our local repository for concept searching. It also provides intelligent clinical data searching of reports processed by the TIES NLP pipeline, the associated unique participant and sample identifiers are returned. Other services will be developed in the future to return the annotated report text.

Currently, this API only searches against our TCGA public node which contains only the publicly available TCGA data and returns the TCGA ID. The TIES demo gives you access to the entire publicly available clinical data set provided as part of The Cancer Genome Atlas (http://cancergenome.nih.gov/). We’ve loaded >10,000 cancer cases, including NLP processed pathology reports, accompanying whole slide images, and discrete clinical data such as treatment and outcomes information. See the Live Demo

The following provides a summary of the available REST resources:

Resource	URL Endpoint
Query	/query
Concept	/concept/search
Document	/documents

Base URL

http://ties-tcga.bridges.psc.edu:8085/api/ties

**Header requirements (example curl)

-H 'authorization: Bearer YOUR AUTHORIZATION TOKEN'
-H 'content-type: application/json'

---

Query Service

Types of Searching in TIES When creating queries, users can use two main types of searches: Text searching - only returns reports that contain EXACT matches to the search term. Concept searching - returns documents that contain the exact search term as well as documents containing synonyms of the search term. Concept searching generally returns more accurate results.

In TIES, concept searching is the default search type. One difference between concept and text searching is how NOT (negation) searches are treated. For text searches, reports not containing the search term anywhere in the report will be returned. In contrast, for concept searches, reports containing the search term in the negated form are returned (such as “No evidence of ...”). For information on the coding of reports, see Noble tool Also, see publication.

Endpoint:

/query

Method:

GET

Parameters:

Required must include either one of these parameters

Param	type	desc
text	string	free text search using non-encoded term
concept	string	term search which is encoded into its related NCIT concept code (i.e., CUI)

Optional

Param	type	desc
limit	numeric	set the limit of results returned (minimal is 5, default is 50)
neg	boolean	apply negation to the submitted concept (i.e., true or false); used in conjunction with the concept parm

Response:

application/json

 {
    "total": 29,
    "criteria": "concept=%27adenosquamous%20carcinoma%27",
    "results": [
        {
            "patientId": "TCGA-05-4250",     // TCGA-ID
            "documentId": "4622744"          // document ID containing concept
        },
        {
            "patientId": "TCGA-BG-A0MK",
            "documentId": "4063320"
        },
        {
            "patientId": "TCGA-HM-A6W2",
            "documentId": "4624265"
        }
    ]
}

Usage:

• Performs a concept search within the coded document for Epithelial ovarian cancer (CUI C0677886)

  http://ties-tcga.bridges.psc.edu:8085/api/ties/query?concept=Epithelial ovarian cancer

• Performs a concept search within the coded document using NEGATION for Epithelial ovarian cancer (CUI C0677886)

  http://ties-tcga.bridges.psc.edu:8085/api/ties/query?concept=Epithelial ovarian cancer&neg=true

---

Concept Search

This allows searching for concepts using the TIES pre-built terminologies. For instance, the following are available with TIES

• NCI Thesaurus (15.03e) - NCI Thesaurus (NCIt) provides reference terminology for many NCI systems. It covers vocabulary for clinical care, translational and basic research, and public information and administrative activities.
• NCI Metathesaurus (201502) - NCI Metathesaurus (NCIm) is a wide-ranging biomedical terminology database that covers most terminologies used by NCI for clinical care, translational and basic research, and public information and administrative activities.

Endpoint:

/concept/search

Method:

GET

Parameters:

Required must include either one of these parameters

Param	type	desc
term	string	search term
cui	string	NCIT concept code (i.e., CUI)

Response:

application/json

{
  "concepts" : "Brain, brain, Brains, Brain structure (body structure), Brain structure, Encephalon, Encephalons",
  "term" : "brain",
  "cui" : "C0006104",
  "cn" : "Brains",
  "def" : "Subdivision of neuraxis that consists of neural tissue (which is organized into gray matter and white matter) and the cerebral ventricular system (cavity of organ part); it is embryologically derived from the rostral part of the neural tube; together with the spinal cord, the brain constitutes the organ neuraxis. Examples: There is only one brain."
} 

Usage:

• by Concept using an NCIT CUI

http://ties-tcga.bridges.psc.edu:8085/api/ties/concepts/search?cui=C0025202

• by Term

http://ties-tcga.bridges.psc.edu:8085/api/ties/concepts/search?term=fibroma

---

Document Search

Endpoint:

/documents/<document_id>

**Description This endpoint will accept a document id and return the matching pathology report and associated medical concept annotations in a JSON format.

Method:

GET

Parameters:

Param	type	desc
document id	numeric	internal document id; this id is returned from query search

Response:

application/json

{
  "href" : "http://ties-tcga.bridges.psc.edu:8085/api/ties/documents/164823",
  "id" : 164823,
  "text" : "[Report de-identified by TIES]... No evidence of Carcinomatous Component Present.",
  "conceptSet" :"NC1707292\n … NC1707292\n",
  "highlightText" : "<?xml type=\"CoreConcept\" <Concept cui=\"C13g\" term=\"Carcinomatous Component Present\" tui=\"T033\" />\r\n  </Annotation>\r\n  <Annotation type=\"Sentence\" startOffset=\"0\" endOffset=\"31\" />\r\n</Annotations>\r\n\r\n"
}

Usage:

http://ties-tcga.bridges.psc.edu:8085/api/ties/documents/4626086

---

Endpoint:

/documents/list

**Description This endpoint will accept a list of Medical Record Number(the patient_id in tcga data) and return the matching pathology report and associated medical concept annotations in a JSON format.

Method:

POST

Request Body:

application/json

{"patientIds":
   ["TCGA-A8-A07B",
   "TCGA-A3-E629"]
}

Response:

application/json

"number of patient": 2,
    "results": [
        {
            "patientId": "TCGA-A8-A07B",
            "total": "1",
            "docs": [
                {
                    "herf": "http://ties-tcga.bridges.psc.edu:8085/api/ties/documents/4625178",
                    "id": "4625178",
                    "conceptSet": "AC0205617\nAC0375111\nAC1134719\nAC1301886\n",
                    "text": "[Report de-identified by TIES]\nDiagnosis:\nPoorly differentiated invasive ductal carcinoma (tumor diameter: 3.0cm).\n\n\nConcluding tumor classification: NOS, G  pT2LOVORO.",
                    "highlightText": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\r\n<Annotations>\r\n  <Annotation type=\"CoreConcept\" startOffset=\"42\" endOffset=\"63\">\r\n    <Concept cui=\"C0205617\" cn=\"Poorly Differentiated\" sty=\"Qualitative Concept\" term=\"Poorly differentiated\" tui=\"T080\" />\r\n  </Annotation>\r\n  <Annotation type=\"Sentence\" startOffset=\"31\" endOffset=\"114\" />\r\n  <Annotation type=\"Sentence\" startOffset=\"117\" endOffset=\"168\" />\r\n  <Annotation type=\"CoreConcept\" startOffset=\"91\" endOffset=\"96\">\r\n    <Concept cui=\"C0375111\" cn=\"Neoplasm of unspecified nature, site unspecified\" sty=\"Neoplastic Process\" term=\"tumor\" tui=\"T191\" />\r\n  </Annotation>\r\n  <Annotation type=\"CoreConcept\" startOffset=\"64\" endOffset=\"89\">\r\n    <Concept cui=\"C1134719\" cn=\"Invasive Ductal Carcinoma of Breast\" sty=\"Neoplastic Process\" term=\"invasive ductal carcinoma\" tui=\"T191\" />\r\n  </Annotation>\r\n  <Annotation type=\"CoreConcept\" startOffset=\"97\" endOffset=\"105\">\r\n    <Concept cui=\"C1301886\" cn=\"Diameter (qualifier value)\" sty=\"Quantitative Concept\" term=\"diameter\" tui=\"T081\" />\r\n  </Annotation>\r\n</Annotations>\r\n\r\n"
                }
            ]
}