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 service URLs in the table below is http://rest.bioontology.org/bioportal/

Note: As of May 2009 all NCBO REST web service calls MUST append a user identification query parameter with the pattern of "email=ENCODEDEMAIL" where ENCODEDEMAIL is your user identification URL encoded email address. For example, someUser@university.edu would look like someUser%40university.edu. Please start adding this 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.

Services to access ontologies and ontology versions

List all the latest version of ontologies

Signature: ./ontologies
Example: http://rest.bioontology.org/bioportal/ontologies

Get a specific ontology based on a version id

Signature: ./ontologies/{ontology version id}
Example: http://rest.bioontology.org/bioportal/ontologies/39002

Download an ontology file

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

Get all versions of an ontology form a virtual ontology id

Signature: ./ontologies/versions/{ontology id}
Example: http://rest.bioontology.org/bioportal/ontologies/versions/1104

Get latest version of an ontology id

Signature: ./virtual/{ontology_id}
Example: http://rest.bioontology.org/bioportal/virtual/1104

List all ontology categories id

Signature: ./categories
Example: http://rest.bioontology.org/bioportal/categories

Concept services

Get concept id

Signature: ./concepts/{ontology version id}/{concept id}
Example: http://rest.bioontology.org/bioportal/concepts/39002/BRO:Resource

Get all root concepts for an ontology id

Signature: ./concepts/{ontology version id}/root
Example: http://rest.bioontology.org/bioportal/concepts/39002/root

Get concept for latest ontology version id

Signature: ./virtual/{ontology id}/{concept id}
Example: http://rest.bioontology.org/bioportal/virtual/1104/BRO:Resource

Search services

Search BioPortal

Signature: ./search/{query}[?{optional args}]
Example: http://rest.bioontology.org/bioportal/search/Gene
You can use multiple query terms, separated by a space, for example: http://rest.bioontology.org/bioportal/search/lung disease
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)
- Example: http://rest.bioontology.org/bioportal/search/software/?ontologyids=1104&isexactmatch=1

Hierarchy Services

Note: The hierarchy services will be available in May, 2009

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

Signature: ./concepts/[parents|children]/{ontlogyVersionId}/{conceptId}[?{optional args}]
Example: http://rest.bioontology.org/bioportal/concepts/parents/13578/Melanoma
Example: http://rest.bioontology.org/bioportal/concepts/children/13578/Melanoma
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/13578/Melanoma?level=1&offset=1&limit=10
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.
Note: These services accept UMLS Abbreviated source name (SAB) for ontlogyVersionId and UMLS Unique identifier for concept (CUI) for conceptId.
Sample Output:

<?xml version="1.0" encoding="UTF-8" ?>
<success>
	<accessedResource>
		/bioportal/virtual/parents/MSH/C0025202
	</accessedResource>
	<accessDate>2009-04-21 10:55:33.494 PDT</accessDate>
	<data>
		<list>
			<classBean>
				<ontologyVersionId>MSH</ontologyVersionId>
				<id>C0206769</id>
				<relations>
					<entry>
						<string>Level</string>
						<int>1</int>
					</entry>
				</relations>
			</classBean>
			<classBean>
				<ontologyVersionId>MSH</ontologyVersionId>
				<id>C0206754</id>
				<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}[?{optional args}]
Example: http://rest.bioontology.org/bioportal/virtual/parents/1009/DOID:1909
Example: http://rest.bioontology.org/bioportal/virtual/children/1009/DOID:1909
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/1009/DOID:1909?level=1&offset=1&limit=3
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}[?{optional args}]
Example: http://rest.bioontology.org/bioportal/concepts/rootpath/13578/Melanoma
Example: http://rest.bioontology.org/bioportal/concepts/leafpath/13578/Melanoma
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.
Note: These services accepts UMLS Abbreviated source name (SAB) for ontlogyVersionId and UMLS Unique identifier for concept (CUI) fro conceptId.
Sample Output:

<?xml version="1.0" encoding="UTF-8" ?>
<success>
	<accessedResource>
		/bioportal/concepts/rootpath/13578/Melanoma
	</accessedResource>
	<accessDate>2009-04-21 11:06:23.439 PDT</accessDate>
	<data>
		<list>
			<classBean>
				<ontologyVersionId>13578</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>13578</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}[?{optional args}]
Example: http://rest.bioontology.org/bioportal/virtual/rootpath/1009/DOID:1909
Example: http://rest.bioontology.org/bioportal/virtual/leafpath/1009/DOID:1909
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>[&{optional args}]
Example: http://rest.bioontology.org/bioportal/concepts/siblings/13578/Melanoma?level=1
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.
Note: These services accepts UMLS Abbreviated source name (SAB) for ontlogyVersionId and UMLS Unique identifier for concept (CUI) fro conceptId.
Sample Output:

<?xml version="1.0" encoding="UTF-8" ?>
<success>
	<accessedResource>
		/bioportal/concepts/siblings/13578/Melanoma
	</accessedResource>
	<accessDate>2009-04-21 11:15:13.427 PDT</accessDate>
	<data>
		<list>
			<classBean>
				<ontologyVersionId>13578</ontologyVersionId>
				<id>Common_Germ_Cell_Neoplasm</id>
				<relations>
					<entry>
						<string>Level</string>
						<int>1</int>
					</entry>
				</relations>
			</classBean>
			<classBean>
				<ontologyVersionId>13578</ontologyVersionId>
				<id>Common_Hematopoietic_Neoplasm</id>
				<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>[&{optional args}]
Example: http://rest.bioontology.org/bioportal/virtual/siblings/1009/DOID:1909?level=1
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.

BioPortal REST services

Contents