This page documents BioPortal Web Service signatures. The list below contains commonly accessed BioPortal Web services and is not intended to be an exhaustive list. If a feature you are interested in is not in the list below, please contact BioPortal Support to request the service or ask for more details on the full list of services.

The prefix for all production service URLs in the table below is http://rest.bioontology.org/bioportal/

Note: All NCBO REST web service calls MUST append a user identification query parameter with the pattern of "email=UserEmail" (note some clients may need to use URL encoding). For example, email=example@example.org or email=example%40example.org as an encoded email. Please start adding the user identification URL parameter to all your web service invocations. Later in 2009, we may start challenging REST service calls that do not have this parameter.

Note: Signatures for BioPortal services have changed in BioPortal 2.0.4 release on January 13th, 2009. This page has the new service URLs. If you have any questions, please contact BioPortal Support.

Overview - Using NCBO Technology in Your Project

See Using NCBO Technology in your Project for general information and widgets available for use.

Code Examples

Code examples for the ontology web services, developed in FlexViz, is available at: https://bmir-gforge.stanford.edu/gf/project/flexviz/frs/?action=index. To see the code in action, visit the Test User Interface that has been set-up using the FlexViz code.

Code examples for the Annotator and Resource Index can be found on pages specific for those tools.

BioPortal Announce Mailing List

To receive notices of new BioPortal releases, changes to web services, or planned downtime subscribe to the bioportal-annouce list.

Services to access ontologies and ontology versions

List all the latest version of ontologies

Signature: ./ontologies?email={email_address}
Example: http://rest.bioontology.org/bioportal/ontologies?email=example@example.org

Get a specific ontology based on a version id

Signature: ./ontologies/{ontology version id}?email={email_address}
Example: http://rest.bioontology.org/bioportal/ontologies/39002?email=example@example.org

Download an ontology file

Description: Download the file (.obo, .owl) corresponding to the given ontology version id.
Signature: ./ontologies/download/{ontology version id}?email={email_address}
Example: http://rest.bioontology.org/bioportal/ontologies/download/39002?email=example@example.org

Download the latest ontology file

Description: Download the file (.obo, .owl) corresponding to the given virtual ontology id.
Signature: ./virtual/download/{ontology id}?email={email_address}
Example: http://rest.bioontology.org/bioportal/virtual/download/1090?email=example@example.org

Get all versions of an ontology from a virtual ontology id

Signature: ./ontologies/versions/{ontology id}?email={email_address}
Example: http://rest.bioontology.org/bioportal/ontologies/versions/1104?email=example@example.org

Get latest version of an ontology id

Signature: ./virtual/ontology/{ontology_id}?email={email_address}
Example: http://rest.bioontology.org/bioportal/virtual/ontology/1104?email=example@example.org

List all ontology categories

NOTE: To be released in BioPortal version 2.2

Signature: ./categories?email={email_address}
Example: http://rest.bioontology.org/bioportal/categories

List all ontology groups

NOTE: To be released in BioPortal version 2.2

Signature: ./groups?email={email_address}
Example: http://rest.bioontology.org/bioportal/groups

Services to access ontology views and ontology view versions

Since all the views on ontologies are ontologies themselves all the services that work on ontologies do work for ontology views also with the same signature.

For example to get a specific ontology view based on a version id would be possible by using the signature:

./ontologies/download/{view version id}?email={email_address}

or for getting all view versions of a virtual view can be achieved called using the signature:

./ontologies/versions/{view id}?email={email_address}

However, there are a couple of services that are special for views:

List all the latest version of views

NOTE: To be released in BioPortal version 2.2

Signature: ./views?email={email_address}
Example: http://rest.bioontology.org/bioportal/views?email=example@example.org

Get all versions of views from a virtual ontology id

NOTE: To be released in BioPortal version 2.2

Description: Returns all versions of views defined on the latest version a virtual ontology, grouped by virtual view ids.
Signature: ./views/versions/{ontology id}?email={email_address}
Example: http://rest.bioontology.org/bioportal/views/versions/1104?email=example@example.org

Search services

Search BioPortal

Signature: ./search/{query}[?{optional args}]&email={email_address}
Alt Signature: ./search/?query={uri-encoded query}[&{optional args}]&email={email_address}
Example: http://rest.bioontology.org/bioportal/search/Gene?email=example@example.org
You can use multiple query terms, separated by a space, for example: http://rest.bioontology.org/bioportal/search/lung disease?email=example@example.org
Optional arguments:
- ontologyids=<ontologyid>,<ontologyid>… - limits the search to specific ontologies (default: all ontologies)
- isexactmatch=[1/0] – match the entire concept name (default: 0)
- includeproperties=[1/0] – include attributes in the search (default: 0)
- pagesize=<pagesize> - the number of results to display in a single request (default: all)
- pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)
- maxnumhits=<maxnumhits> - the maximum number of top matching results to return (default: 1000)
- subtreerootconceptid=<uri-encoded conceptid> - narrow the search to concepts residing in a sub-tree, where the "subtreerootconceptid" is the root node. This feature requires a SINGLE <ontologyid> passed in using the "onotlogyids" parameter.
Description:

The search attempts to match both partial and exact queries, giving more weight to exact matches. In single-word searches, the wildcard character (*) is automatically appended to the end of the word. For example, searching for "lun" would return all concepts whose name contains a word that begins with "lun" (i.e. "Lung", "Murine Lunate Bone", "Base of the Lung", etc).

In phrase searches (multiple words), the wildcard character is appended to the last word. For example, searching for "cutaneous mela" would return all concepts whose name contains the word "cutaneous", followed by any word that begins with "mela" (i.e. "Cutaneous Melanoma", "Metastatic Non-Cutaneous Melanoma", "Cutaneous Melanoma Clinical TNM Finding", etc).

Example: http://rest.bioontology.org/bioportal/search/software/?ontologyids=1104&isexactmatch=1&email=example@example.org
Sample Output:

<?xml version="1.0" encoding="UTF-8" ?>
<success>
	<accessedResource>
		/bioportal/search/cutaneous%20mela
	</accessedResource>
	<accessDate>2009-05-07 16:17:46.182 PDT</accessDate>
	<data>
		<page>
			<pageNum>1</pageNum>
			<numPages>1</numPages>
			<pageSize>3</pageSize>
			<numResultsPage>3</numResultsPage>
			<numResultsTotal>3</numResultsTotal>
			<contents
				class="org.ncbo.stanford.bean.search.SearchResultListBean">
				<searchResultList>
					<searchBean>
						<ontologyVersionId>39715</ontologyVersionId>
						<ontologyId>1136</ontologyId>
						<ontologyDisplayLabel>
							Experimental Factor Ontology
						</ontologyDisplayLabel>
						<recordType>
							RECORD_TYPE_PREFERRED_NAME
						</recordType>
						<conceptId>
							http://www.ebi.ac.uk/efo/EFO_0000389
						</conceptId>
						<conceptIdShort>EFO_0000389</conceptIdShort>
						<preferredName>
							cutaneous melanoma
						</preferredName>
						<contents>cutaneous melanoma</contents>
					</searchBean>
					<searchBean>
						<ontologyVersionId>39478</ontologyVersionId>
						<ontologyId>1032</ontologyId>
						<ontologyDisplayLabel>
							NCI Thesaurus
						</ontologyDisplayLabel>
						<recordType>
							RECORD_TYPE_PREFERRED_NAME
						</recordType>
						<conceptId>
							http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Cutaneous_Melanoma
						</conceptId>
						<conceptIdShort>
							Cutaneous_Melanoma
						</conceptIdShort>
						<preferredName>
							Cutaneous Melanoma
						</preferredName>
						<contents>Cutaneous Melanoma</contents>
					</searchBean>
					<searchBean>
						<ontologyVersionId>39833</ontologyVersionId>
						<ontologyId>1009</ontologyId>
						<ontologyDisplayLabel>
							Human disease
						</ontologyDisplayLabel>
						<recordType>
							RECORD_TYPE_PREFERRED_NAME
						</recordType>
						<conceptId>DOID:2418</conceptId>
						<conceptIdShort>DOID:2418</conceptIdShort>
						<preferredName>
							Cutaneous Melanocytic Neoplasm
						</preferredName>
						<contents>
							Cutaneous Melanocytic Neoplasm
						</contents>
					</searchBean>
				</searchResultList>
				<ontologyHitList>
					<ontologyHitBean>
						<ontologyVersionId>39715</ontologyVersionId>
						<ontologyId>1136</ontologyId>
						<ontologyDisplayLabel>
							Experimental Factor Ontology
						</ontologyDisplayLabel>
						<numHits>1</numHits>
					</ontologyHitBean>
					<ontologyHitBean>
						<ontologyVersionId>39833</ontologyVersionId>
						<ontologyId>1009</ontologyId>
						<ontologyDisplayLabel>
							Human disease
						</ontologyDisplayLabel>
						<numHits>1</numHits>
					</ontologyHitBean>
					<ontologyHitBean>
						<ontologyVersionId>39478</ontologyVersionId>
						<ontologyId>1032</ontologyId>
						<ontologyDisplayLabel>
							NCI Thesaurus
						</ontologyDisplayLabel>
						<numHits>1</numHits>
					</ontologyHitBean>
				</ontologyHitList>
			</contents>
		</page>
	</data>
</success>

Term services

(formerly referred to as Concept services)

Get term

Signature: ./concepts/{ontology version id}/{concept id}?email={email_address}
Alt Signature: ./concepts/{ontology version id}?conceptid={uri-encoded concept id}&email={email_address}
Optional arguments:
- light=[1/0] - when set to 1, returns the "light" version of XML with only a basic info for the concept and its immediate children
- norelations=[1/0] - when set to 1, returns only the requested term information (id, label, fullid, type, synonyms, definitions) without the "relations" map. This is useful when you need to quickly retrieve just the base information about a term.
Examples:

http://rest.bioontology.org/bioportal/concepts/39002/BRO:Resource?email=example@example.org
http://rest.bioontology.org/bioportal/concepts/41009?conceptid=http%3A%2F%2Fihtsdo.owl%2Fsnomedct%2Fanatomy%23302509004&light=0&email=example@example.org
http://rest.bioontology.org/bioportal/concepts/41009?conceptid=http%3A%2F%2Fihtsdo.owl%2Fsnomedct%2Fanatomy%23302509004&norelations=1&email=example@example.org

Sample Output:

<?xml version="1.0" encoding="UTF-8" ?>
<success>
	<accessedResource>/bioportal/concepts/40644/</accessedResource>
	<accessDate>2009-12-16 10:06:10.727 PST</accessDate>
	<data>
		<classBean>
			<id>Melanoma</id>
			<fullId>http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Melanoma</fullId>
			<label>Melanoma</label>
			<type>Class</type>
			<synonyms>
				<string>Malignant Melanoma</string>
				<string>Melanoma</string>
				<string>melanoma</string>
			</synonyms>
			<definitions>
				<string>A malignant, usually aggressive tumor composed of atypical,
					neoplastic melanocytes.</string>
			</definitions>
			<relations>
				<entry>
					<string>UMLS_CUI</string>
					<list>
						<string>C0025202</string>
					</list>
				</entry>
				<entry>
					<string>owl:equivalentClass</string>
					<list>
						<string>'Common Neoplasm' and 'Melanocytic Neoplasm' and
							(Disease_Has_Abnormal_Cell only 'Melanoma Cell')</string>
					</list>
				</entry>
				<entry>
					<string>ALT_DEFINITION</string>
					<list>
						<string>
							<def-source>NCI-GLOSS</def-source>
							<def-definition>A form of skin cancer that arises in
								melanocytes, the cells that produce pigment.</def-definition>
						</string>
					</list>
				</entry>
				<entry>
					<string>ICD-O-3_Code</string>
					<list>
						<string>8720/3</string>
					</list>
				</entry>
				<entry>
					<string>Semantic_Type</string>
					<list>
						<string>Neoplastic Process</string>
					</list>
				</entry>
				<entry>
					<string>SubClass</string>
					<list>
						<classBean>
							<id>Non-Cutaneous_Melanoma</id>
							<fullId>http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Non-Cutaneous_Melanoma</fullId>
							<label>Non-Cutaneous Melanoma</label>
							<type>Class</type>
							<synonyms>
								<string>Extracutaneous Melanoma</string>
								<string>Non-Cutaneous Melanoma</string>
							</synonyms>
							<definitions>
								<string>Melanoma is a malignant tumor of melanocytes,
									cells that are derived from the neural crest.</string>
							</definitions>
							<relations>
								<entry>
									<string>code</string>
									<list>
										<string>C8711</string>
									</list>
								</entry>
							</relations>
						</classBean>
					</list>
				</entry>
			</relations>
		</classBean>
	</data>
</success>

Get all root terms for an ontology version id

Signature: ./concepts/{ontology version id}/root?email={email_address}
Example: http://rest.bioontology.org/bioportal/concepts/39002/root?email=example@example.org

Get term for latest ontology version id

NOTE: This signature will change in BioPortal release 2.2

New Signature: ./virtual/ontology/{ontology id}/{concept id}?email={email_address}
New Example: http://rest.bioontology.org/bioportal/virtual/ontology/1104/BRO:Resource?email=example@example.org

Signature: ./virtual/{ontology id}/{concept id}?email={email_address}
Example: http://rest.bioontology.org/bioportal/virtual/1104/BRO:Resource?email=example@example.org

Get all terms using the specific ontology version id

NOTE: 'Get all terms' service has changed. The new signature and examples are reflected below. See #Changes_to_the_Get_all_terms_service for more information.

Signature: ./concepts/{ontology version id}/all?pagesize={pagesize}&pagenum={pagenum}&email={email_address}
Examples: A preview of the new service can be seen on the NCBO staging site:
- http://rest.bioontology.org/bioportal/concepts/40644/all?pagesize=50&pagenum=1&email=example@example.org
- http://rest.bioontology.org/bioportal/concepts/42431/all?pagesize=50&pagenum=500&email=example@example.org
Arguments:
- pagesize: An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
- pagenum: An integer indicating which page of results to return.

Get all terms using the virtual ontology id

NOTE: 'Get all terms' service has changed. The new signature and examples are reflected below. See #Changes_to_the_Get_all_terms_service for more information.

Signature: ./virtual/ontology/{ontology id}/all?pagesize={pagesize}&pagenum={pagenum}&email={email_address}
Example: http://rest.bioontology.org/bioportal/virtual/ontology/1104/all?&pagesize=50&pagenum=1&email=example@example.org
Arguments:
- pagesize: An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
- pagenum: An integer indicating which page of results to return.

Changes to the Get all terms service

Starting in BioPortal 2.3.1 (released March 15, 2010), the 'Get all terms' service has changed to support speedier and more complete term retrieval. To support this, several changes to the response XML and service signature are being made. Please see the following notes to update your existing applications to support these changes.

Examples: A preview of the new service can be seen on the NCBO staging site:
- http://rest.bioontology.org/bioportal/concepts/40644/all?pagesize=50&pagenum=1
- http://rest.bioontology.org/bioportal/concepts/42431/all?pagesize=50&pagenum=500

Signature
- New parameters: Previously, offset and limit were used to control pagination of results. These parameters have been replaced as follows:
  - pagesize: An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
  - pagenum: An integer indicating which page of results to return.

Response: The structure of the new 'Get all terms' response XML has been brought into line with other BioPortal REST term services. In addition, to assist in paging through result sets, 'page' metadata is provided. A list of classBeans is provided in the classBeanResultList element, which includes each classes' set of relations (examples of relations include SuperClass, SubClass, and rdfs:label). Please see the example below for a full demonstration of the new response.

Instance Services

Get all direct instances for a given term

Signature: ./concepts/instances/{ontlogyVersionId}[?conceptid={uri-encoded concept id}&email={email_address}]
Optional arguments:
- pagesize=<pagesize> - the number of results to display in a single request (default: all)
- pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)

Example: http://rest.bioontology.org/bioportal/concepts/instances/38801?conceptid=SubstrateType&pagesize=1&pagenum=1&email=example@example.org
Description: returns all direct instances for a given term.
Sample Output:

<?xml version="1.0" encoding="UTF8" ?>
<success>
	<accessedResource>/bioportal/concepts/instances/38801
	</accessedResource>
	<accessDate>20100408 18:17:21.226 PDT</accessDate>
	<data>
		<page>
			<pageNum>1</pageNum>
			<numPages>5</numPages>
			<pageSize>1</pageSize>
			<numResultsPage>1</numResultsPage>
			<numResultsTotal>5</numResultsTotal>
			<contents class="org.ncbo.stanford.bean.concept.InstanceBeanResultListBean">
				<list>
					<instanceBean>
						<id>unknown_substrate_type</id>
						<fullId>
							http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unknown_substrate_type
						</fullId>
						<label>unknown_substrate_type</label>
						<relations>
							<entry>
								<propertyBean>
									<id>rdf:type</id>
									<fullId>http://www.w3.org/1999/02/22rdfsyntaxns#type
									</fullId>
									<label>rdf:type</label>
									<relations />
								</propertyBean>
								<list>
									<instanceBean>
										<id>SubstrateType</id>
										<fullId>
											http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
										</fullId>
										<label>SubstrateType</label>
										<relations />
										<instanceType>
											<list>
												<classBean>
													<id>owl:Class</id>
													<fullId>http://www.w3.org/2002/07/owl#Class
													</fullId>
													<label>owl:Class</label>
													<type>Class</type>
													<relations />
												</classBean>
											</list>
										</instanceType>
									</instanceBean>
								</list>
							</entry>
							<entry>
								<propertyBean>
									<id>:NAME</id>
									<fullId>:NAME</fullId>
									<label>:NAME</label>
									<relations />
								</propertyBean>
								<list>
									<string>
										http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unknown_substrate_type
									</string>
								</list>
							</entry>
							<entry>
								<propertyBean>
									<id>unique_identifier</id>

									<fullId>
										http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unique_identifier
									</fullId>
									<label>unique_identifier</label>
									<relations />
								</propertyBean>
								<list>
									<string>MO_484</string>
								</list>
							</entry>
							<entry>
								<propertyBean>
									<id>:DIRECTTYPE</id>
									<fullId>:DIRECTTYPE</fullId>
									<label>:DIRECTTYPE</label>
									<relations />
								</propertyBean>
								<list>
									<instanceBean>
										<id>SubstrateType</id>
										<fullId>
											http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
										</fullId>
										<label>SubstrateType</label>
										<relations />
										<instanceType>
											<list>
												<classBean>
													<id>owl:Class</id>
													<fullId>http://www.w3.org/2002/07/owl#Class
													</fullId>
													<label>owl:Class</label>
													<type>Class</type>
													<relations />
												</classBean>
											</list>
										</instanceType>
									</instanceBean>
								</list>
							</entry>
							<entry>
								<propertyBean>
									<id>rdfs:comment</id>
									<fullId>http://www.w3.org/2000/01/rdfschema#comment
									</fullId>
									<label>rdfs:comment</label>
									<relations />
								</propertyBean>

								<list>
									<string>SubstrateType of unknown type.</string>
								</list>
							</entry>
						</relations>
						<instanceType>
							<list>
								<classBean>
									<id>SubstrateType</id>
									<fullId>
										http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
									</fullId>
									<label>SubstrateType</label>
									<type>Class</type>
									<relations />
								</classBean>
							</list>
						</instanceType>
					</instanceBean>
				</list>
			</contents>
		</page>
	</data>
</success>

Get an instance and its property/value pairs

Signature: ./instance/{ontlogyVersionId}[?instanceid={instanceid}&email={email_address}]

Example: http://rest.bioontology.org/bioportal/instance/38801?instanceid=glass&email=example@example.org
Description: returns information about an instance and a list of property/value pairs.
Sample Output:

<?xml version="1.0" encoding="UTF8" ?>
<success>
	<accessedResource>/bioportal/instance/38801
	</accessedResource>
	<accessDate>20100408 18:10:48.760 PDT</accessDate>
	<data>
		<instanceBean>
			<id>glass</id>
			<fullId>
				http://mged.sourceforge.net/ontologies/MGEDOntology.owl#glass
			</fullId>
			<label>glass</label>
			<relations>
				<entry>
					<propertyBean>
						<id>:NAME</id>
						<fullId>:NAME</fullId>
						<label>:NAME</label>
						<relations />
					</propertyBean>
					<list>
						<string>
							http://mged.sourceforge.net/ontologies/MGEDOntology.owl#glass
						</string>
					</list>
				</entry>
				<entry>
					<propertyBean>
						<id>unique_identifier</id>
						<fullId>
							http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unique_identifier
						</fullId>
						<label>unique_identifier</label>
						<relations />
					</propertyBean>
					<list>
						<string>MO_742</string>
					</list>
				</entry>
				<entry>
					<propertyBean>
						<id>rdfs:comment</id>
						<fullId>http://www.w3.org/2000/01/rdfschema#comment
						</fullId>
						<label>rdfs:comment</label>
						<relations />
					</propertyBean>
					<list>
						<string>The array is made on a glass slide.</string>
					</list>
				</entry>
				<entry>
					<propertyBean>
						<id>:DIRECTTYPE</id>
						<fullId>:DIRECTTYPE</fullId>
						<label>:DIRECTTYPE</label>
						<relations />
					</propertyBean>
					<list>
						<instanceBean>
							<id>SubstrateType</id>
							<fullId>
								http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
							</fullId>
							<label>SubstrateType</label>
							<relations />
							<instanceType>
								<list>
									<classBean>
										<id>owl:Class</id>
										<fullId>http://www.w3.org/2002/07/owl#Class
										</fullId>
										<label>owl:Class</label>
										<type>Class</type>
										<relations />
									</classBean>
								</list>
							</instanceType>
						</instanceBean>
					</list>
				</entry>
				<entry>
					<propertyBean>
						<id>rdf:type</id>
						<fullId>http://www.w3.org/1999/02/22rdfsyntaxns#type
						</fullId>
						<label>rdf:type</label>
						<relations />
					</propertyBean>
					<list>
						<instanceBean>
							<id>SubstrateType</id>
							<fullId>
								http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
							</fullId>
							<label>SubstrateType</label>
							<relations />
							<instanceType>
								<list>
									<classBean>
										<id>owl:Class</id>
										<fullId>http://www.w3.org/2002/07/owl#Class
										</fullId>
										<label>owl:Class</label>
										<type>Class</type>
										<relations />
									</classBean>
								</list>
							</instanceType>
						</instanceBean>
					</list>
				</entry>
			</relations>
			<instanceType>
				<list>
					<classBean>
						<id>SubstrateType</id>
						<fullId>
							http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
						</fullId>
						<label>SubstrateType</label>
						<type>Class</type>
						<relations />
					</classBean>
				</list>
			</instanceType>
		</instanceBean>
	</data>
</success>

Hierarchy Services

NOTE: To see which ontology versions have been processed for use with the Hierarchy services, see http://rest.bioontology.org/obs/ontologies

Get parents/children of a given concept in a specific ontology version

Signature: ./concepts/[parents|children]/{ontlogyVersionId}/{conceptId}[?email={email_address}&{optional args}]

Example: http://rest.bioontology.org/bioportal/concepts/parents/42331/Melanoma?email=example@example.org
Example: http://rest.bioontology.org/bioportal/concepts/children/42331/Melanoma?email=example@example.org
Optional arguments:
- level=<integer> - limits results to a given level in the hierarchy
- offset=<integer> – results offset (used for pagination)
- limit=<integer> – limits the number of results
- Example: http://rest.bioontology.org/bioportal/concepts/parents/42331/Melanoma?level=1&offset=1&limit=10&email=example@example.org
Description: returns all parents of the concept, with the level indicating how far away the parent is from the concept. For instance, direct parents have level 1; their direct parents have level 2, etc. If no level is specified, the service returns all the levels up to the root. If the level is specified, the service returns only the parents at that level.
Sample Output:

<?xml version="1.0" encoding="UTF8" ?>
<success>
	<accessedResource>/bioportal/concepts/parents/42331/Melanoma
	</accessedResource>
	<accessDate>20100408 17:58:14.230 PDT</accessDate>
	<data>
		<list>
			<classBean>
				<ontologyVersionId>42331</ontologyVersionId>
				<id>Common_Neoplasm</id>
				<fullId>
					http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Common_Neoplasm
				</fullId>
				<label>Common Neoplasm</label>
				<synonyms>
					<string>Common Tumor</string>
					<string>Common Neoplasm</string>
				</synonyms>
				<relations>
					<entry>
						<string>Level</string>
						<int>1</int>
					</entry>
				</relations>
			</classBean>
			<classBean>
				<ontologyVersionId>42331</ontologyVersionId>
				<id>Melanocytic_Neoplasm</id>
				<fullId>
					http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Melanocytic_Neoplasm
				</fullId>
				<label>Melanocytic Neoplasm</label>
				<synonyms>
					<string>Melanocytic Neoplasm</string>
				</synonyms>
				<relations>
					<entry>
						<string>Level</string>
						<int>1</int>
					</entry>
				</relations>
			</classBean>
		</list>
	</data>
</success>

Get parents/children of a given concept in the latest version of a given ontology

Signature: ./virtual/[parents|children]/{ontlogyId}/{conceptId}[?email={email_address}&{optional args}]
Example: http://rest.bioontology.org/bioportal/virtual/parents/1032/Melanoma?email=example@example.org
Example: http://rest.bioontology.org/bioportal/virtual/children/1032/Melanoma?email=example@example.org
Optional arguments:
- level=<integer> - limits results to a given level in the hierarchy
- offset=<integer> – results offset (used for pagination)
- limit=<integer> – limits the number of results
- Example: http://rest.bioontology.org/bioportal/virtual/parents/1032/Melanoma?level=1&offset=1&limit=3&email=example@example.org
Description: The same as the previous services, but takes an ontology id and returns parents from the latest version of that ontology.

Get paths to roots/leaves from a concept in a specific ontology version

Signature: ./concepts/[rootpath|leafpath]/{ontologyVersionId}/{conceptId}[?email={email_address}&{optional args}]
- NOTE: To see which ontology versions have been processed for use with the Hierarchy services, see http://rest.bioontology.org/obs/ontologies
Example: http://rest.bioontology.org/bioportal/concepts/rootpath/42331/Melanoma?email=example@example.org
Example: http://rest.bioontology.org/bioportal/concepts/leafpath/42331/Melanoma?email=example@example.org
Optional arguments:
- offset=<integer> – results offset (used for pagination)
- limit=<integer> – limits the number of results
Description: return a set of path to the roots (resp. leaves) for a given concept in a specific ontology version. Paths are represented as a list of conceptIds, separated by periods (.) The first one in the list is a root (resp. leaf) in the hierarchy; the last one in the list is the direct parent (resp. direct child) of the concept.
Sample Output:

<?xml version="1.0" encoding="UTF-8" ?>
<success>
	<accessedResource>
		/bioportal/concepts/rootpath/40644/Melanoma
	</accessedResource>
	<accessDate>2009-04-21 11:06:23.439 PDT</accessDate>
	<data>
		<list>
			<classBean>
				<ontologyVersionId>40644</ontologyVersionId>
				<id>Melanoma</id>
				<relations>
					<entry>
						<string>Path</string>
						<string>
							Getings_and_Disorders_Kind.Diseases_Disorders_and_Getings.Diseases_and_Disorders.Neoplasm.Neoplasm_by_Morphology.Melanocytic_Neoplasm
						</string>
					</entry>
				</relations>
			</classBean>
			<classBean>
				<ontologyVersionId>40644</ontologyVersionId>
				<id>Melanoma</id>
				<relations>
					<entry>
						<string>Path</string>
						<string>
							Getings_and_Disorders_Kind.Diseases_Disorders_and_Getings.Diseases_and_Disorders.Neoplasm.Neoplasm_by_Special_Category.Common_Neoplasm
						</string>
					</entry>
				</relations>
			</classBean>
		</list>
	</data>
</success>

Get paths to root/leaves from a concept in the latest version of a given ontology

Signature: ./virtual/[rootpath|leafpath]/{ontologyId}/{conceptId}[?email={email_address}&{optional args}]
Example: http://rest.bioontology.org/bioportal/virtual/rootpath/1032/Melanoma?email=example@example.org
Example: http://rest.bioontology.org/bioportal/virtual/leafpath/1032/Melanoma?email=example@example.org
Optional arguments:
- offset=<integer> – results offset (used for pagination)
- limit=<integer> – limits the number of results
Description: The same as the previous services, but takes an ontology id and returns parents from the latest version of that ontology.

Get siblings of a given concept in a specific ontology version

Signature: ./concepts/siblings/{ontlogyVersionId}/{conceptId}?level=<level>&email={email_address}&[&{optional args}]
- NOTE: To see which ontology versions have been processed for use with the Hierarchy services, see http://rest.bioontology.org/obs/ontologies
Example: http://rest.bioontology.org/bioportal/concepts/siblings/42331/Melanoma?level=1&email=example@example.org
Required arguments:
- level=<integer> - limits results to a given level in the hierarchy
Optional arguments:
- offset=<integer> – results offset (used for pagination)
Description: returns the set of sibling concepts at the given level (i.e., siblings that have the same direct (level=1), grand-parents (level=2), etc.) for a given concept.
Sample Output:

<?xml version="1.0" encoding="UTF8" ?>
<success>
	<accessedResource>/bioportal/concepts/siblings/42331/Melanoma
	</accessedResource>
	<accessDate>20100408 18:06:16.868 PDT</accessDate>
	<data>
		<list>
			<classBean>
				<ontologyVersionId>42331</ontologyVersionId>
				<id>Common_Germ_Cell_Neoplasm</id>
				<fullId>
					http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Common_Germ_Cell_Neoplasm
				</fullId>
				<label>Common Germ Cell Tumor</label>
				<synonyms>
					<string>Common Germ Cell Tumor</string>
					<string>Common Germ Cell Neoplasm</string>
				</synonyms>
				<relations>
					<entry>
						<string>Level</string>
						<int>1</int>
					</entry>
				</relations>
			</classBean>
			<classBean>
				<ontologyVersionId>42331</ontologyVersionId>
				<id>Common_Hematopoietic_Neoplasm</id>
				<fullId>
					http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Common_Hematopoietic_Neoplasm
				</fullId>
				<label>Common Hematopoietic Neoplasm</label>
				<synonyms>
					<string>Common Hematopoietic Neoplasm</string>
					<string>Common Hematopoietic Tumor</string>
				</synonyms>
				<relations>
					<entry>
						<string>Level</string>
						<int>1</int>
					</entry>
				</relations>
			</classBean>
		</list>
	</data>
</success>

Get siblings of a given concept in the latest version of a given ontology

Signature: ./virtual/siblings/{ontlogyId}/{conceptId}?level=<level>&email={email_address}&[&{optional args}]
Example: http://rest.bioontology.org/bioportal/virtual/siblings/1032/Melanoma?level=1&email=example@example.org
Required arguments:
- level=<integer> - limits results to a given level in the hierarchy
Optional arguments:
- offset=<integer> – results offset (used for pagination)
Description: The same as the previous service, but takes an ontology id and returns parents from the latest version of that ontology.

RDF Dump Service

This service allows you to output a given ontology from BioPortal in the form of a N3 RDF file. This RDF dump will preserve original ontology names space and term URIs.

Coming soon ...

Bio2RDF Dump Service

This service allows you to output a given ontology from BioPortal in the form of a N3 RDF file conforming to the requirements for integrating into the Bio2RDF collection.

Signature: ./ontology/dump_n3/{ontlogyVersionId}?email={email_address}
Example: http://rest.bioontology.org/bioportal/ontology/dump_n3/40865?email=example@example.org

Annotator Service

The NCBO Annotator is a Web service that can be used to annotate text metadata with biomedical ontology concepts. The concepts are from ontologies in BioPortal and includes the Unified Medical Language System (UMLS) Metathesaurus, OBO Foundry candidate ontologies and many others.

The Annotator can be tested via a Web interface available through BioPortal. For more information on using the Annotator Web service, see: http://bioontology.org/wiki/index.php/Annotator_Web_service.

Resource Index Service

The Resource Index provides a mechanism to search for biomedical data based on ontology concepts. For more information on using the Resource Index service, see http://www.bioontology.org/wiki/index.php/Resource_Index.

Prototypes

Notes Service

Signature: ./notes/ont/{ontology_id}
Example: http://bioportal.bioontology.org/notes/ont/1104
Required arguments:
- ontology_id
Description: returns BioPortal Notes as XML. This is a prototype web service, for updates subscribe to bioportal-announce
Sample Output:

<records type="array">
  <record>
    <comment>
    I note that clinical data is specifically defined not to include clinical trial data. So is anyone already thinking about where at a high level subtrees might be added to deal with clinical trial data and clinical trial management systems? Or is it premature to do that? This is for the CTSAs.
    </comment>
    <created-at>2008-08-07 11:21:00</created-at>
    <ontology-id>1104</ontology-id>
    <updated-at>2008-08-07 11:21:00</updated-at>
    <mapping-id nil="true"/>
    <subject>Including clinical trial data as clinical data</subject>
    <id>75</id>
    <user-id>38143</user-id>
    <parent-id nil="true"/>
    <ontology-version-id>38407</ontology-version-id>
    <concept-id>BRO:Clinical_Data</concept-id>
    <note-type>Question</note-type>
  </record>
  <record>
    <comment> Not sure I follow the argument here.  Clinical trial data is covered under PHI so no distinction there.  Data generated in the course of delivering routine standard of care may be needed in the course of a clinical trial.  Does this make clinical trial data an overlapping superset of clinical data?
    </comment>
    <created-at>2008-08-07 11:24:04</created-at>
    <ontology-id>1104</ontology-id>
    <updated-at>2008-08-07 11:24:04</updated-at>
    <mapping-id nil="true"/>
    <subject>RE:Including clinical trial data as clinical data</subject>
    <id>76</id>
    <user-id>38144</user-id>
    <parent-id>75</parent-id>
    <ontology-version-id>38407</ontology-version-id>
    <concept-id>BRO:Clinical_Data</concept-id>
    <note-type>Comment</note-type>
  </record>
</records>

Mapping Service

Signature: ./mappings/service/{ontology_id}/{concept_id}
Example: http://bioportal.bioontology.org/mappings/service/1083/
Required arguments:
- ontology_id
Optional arguments:
- concept_id=if concept_id is included, the service will return all mappings to and from the given concept
Description: returns BioPortal Mappings as XML. This is a prototype web service, for updates subscribe to bioportal-announce
Sample Output:

<hash>
  <mapping-from type="array">
    <mapping-from>
      <comment nil="true"></comment>
      <map-type>Human</map-type>
      <created-at>2008-05-09 08:25:23</created-at>
      <updated-at>2008-08-05 17:26:06</updated-at>

      <source-name>Carbon</source-name>
      <source-ont-name>NanoParticle Ontology (NPO)</source-ont-name>
      <destination-id>CHEBI:27594</destination-id>
      <id>98216</id>
      <user-id>38139</user-id>
      <relationship-type nil="true"></relationship-type>

      <destination-ont-name>Chemical entities of biological interest</destination-ont-name>
      <destination-name>Carbon</destination-name>
      <map-source nil="true"></map-source>
      <destination-ont>1007</destination-ont>
      <source-id>Carbon</source-id>
      <destination-version-id>38377</destination-version-id>

      <source-version-id>29531</source-version-id>
      <source-ont>1083</source-ont>
    </mapping-from>   
    <mapping-from>
      <comment nil="true"></comment>
      <map-type>Human</map-type>
      <created-at>2008-05-09 08:27:05</created-at>

      <updated-at>2008-08-05 17:26:06</updated-at>
      <source-name>Gold</source-name>
      <source-ont-name>NanoParticle Ontology (NPO)</source-ont-name>
      <destination-id>CHEBI:29287</destination-id>
      <id>98218</id>
      <user-id>38139</user-id>

      <relationship-type nil="true"></relationship-type>
      <destination-ont-name>Chemical entities of biological interest</destination-ont-name>
      <destination-name>Gold</destination-name>
      <map-source nil="true"></map-source>
      <destination-ont>1007</destination-ont>
      <source-id>Gold</source-id>
      <destination-version-id>38377</destination-version-id>

      <source-version-id>29531</source-version-id>
      <source-ont>1083</source-ont>
    </mapping-from>
  </mapping-from>
  <mapping-to type="array">
    <mapping-to>
      <comment nil="true"></comment>
      <map-type>Human</map-type>

      <created-at>2008-05-09 08:35:27</created-at>
      <updated-at>2008-08-05 17:26:06</updated-at>
      <source-name>Carbohydrate</source-name>
      <source-ont-name>NanoParticle Ontology (NPO)</source-ont-name>
      <destination-id>Carbohydrate</destination-id>
      <id>98219</id>

      <user-id>38139</user-id>
      <relationship-type nil="true"></relationship-type>
      <destination-ont-name>NanoParticle Ontology (NPO)</destination-ont-name>
      <destination-name>Carbohydrate</destination-name>
      <map-source nil="true"></map-source>
      <destination-ont>1083</destination-ont>
      <source-id>Carbohydrate</source-id>

      <destination-version-id>29531</destination-version-id>
      <source-version-id>29531</source-version-id>
      <source-ont>1083</source-ont>
    </mapping-to>
  </mapping-to>
</hash>

XML Schema Definitions for the REST services

XML Schema for concept and hierarchy services is available (courtesy Eamonn Maguire).

@@ Line 368: / Line 368: @@
 == Get all direct instances for a given term ==
 * '''Signature''': ./concepts/instances/{ontlogyVersionId}[?conceptid={uri-encoded concept id}&email={email_address}]
+* '''Optional arguments:'''
+** pagesize=<pagesize> - the number of results to display in a single request (default: all)
+** pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)
 * '''Example''': http://rest.bioontology.org/bioportal/concepts/instances/38801?conceptid=SubstrateType&pagesize=1&pagenum=1&email=example@example.org

Difference between revisions of "BioPortal REST services"

Revision as of 17:21, 8 April 2010

Overview - Using NCBO Technology in Your Project

Code Examples

BioPortal Announce Mailing List

Services to access ontologies and ontology versions

List all the latest version of ontologies

Get a specific ontology based on a version id

Download an ontology file

Download the latest ontology file

Get all versions of an ontology from a virtual ontology id

Get latest version of an ontology id

List all ontology categories

List all ontology groups

Services to access ontology views and ontology view versions

List all the latest version of views

Get all versions of views from a virtual ontology id

Search services

Search BioPortal

Term services

Get term

Get all root terms for an ontology version id

Get term for latest ontology version id

Get all terms using the specific ontology version id

Get all terms using the virtual ontology id

Changes to the Get all terms service

Instance Services

Get all direct instances for a given term

Get an instance and its property/value pairs

Hierarchy Services

Get parents/children of a given concept in a specific ontology version

Get parents/children of a given concept in the latest version of a given ontology

Get paths to roots/leaves from a concept in a specific ontology version

Get paths to root/leaves from a concept in the latest version of a given ontology

Get siblings of a given concept in a specific ontology version

Get siblings of a given concept in the latest version of a given ontology

RDF Dump Service

Bio2RDF Dump Service

Annotator Service

Resource Index Service

Prototypes

Notes Service

Mapping Service

XML Schema Definitions for the REST services

Navigation menu

Search