Ontology Lookup Service API Guide
Overview
HTTP status codes
This API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.
Status code | Usage |
---|---|
|
The request completed successfully |
|
The request was malformed. The response body will include an error providing further information |
|
The requested resource did not exist |
Errors
Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:
Path | Type | Description |
---|---|---|
error |
String |
The HTTP error that occurred, e.g. |
message |
String |
A description of the cause of the error |
path |
String |
The path to which the request was made |
status |
Number |
The HTTP status code, e.g. |
timestamp |
Number |
The time, in milliseconds, at which the error occurred |
For example, a request that attempts to apply a non-existent tag to a resource will produce a
400 Bad Request
response:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 153
{
"timestamp" : 1554117059039,
"status" : 404,
"error" : "Not Found",
"message" : "Resource not found",
"path" : "/ols/api/ontologies/foobar"
}
Hypermedia
This API uses hypermedia and resources include links to other resources in their
responses. Responses are in Hypertext Application
Language (HAL) format. Links can be found beneath the _links
key. Users of the API should
not create URIs themselves, instead they should use the above-described links to navigate
from resource to resource.
Listing resources
Requests that return multiple resources will be paginated to 20 items by default. You can change the number of items
returned using the size
parameter up to a maximum of 500 for a single request. The API also supports the page
parameter for accessing a specific page of items.
Paging resources
Links will be provided in the response to navigate the resources.
Example response
HTTP/1.1 200 OK
Content-Type: application/json
{
"_links" : {
"first" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies?page=0&size=1"
},
"prev" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies?page=0&size=1"
},
"self" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies"
},
"next" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies?page=2&size=1"
},
"last" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies?page=140&size=1"
}
},
"_embedded" : {
...
},
"page" : {
"size" : 1,
"totalElements" : 141,
"totalPages" : 141,
"number" : 1
}
}
Response structure
Path | Type | Description |
---|---|---|
_links |
Object |
Links to other resources |
_embedded |
Object |
The list of resources |
page.size |
Number |
The number of resources in this page |
page.totalElements |
Number |
The total number of resources |
page.totalPages |
Number |
The total number of pages |
page.number |
Number |
The page number |
Resources
API
The api endpoint provides the entry point into the service.
Accessing the API
A GET
request is used to access the API
Response structure
Path | Type | Description |
---|---|---|
_links |
Object |
Links to other resources |
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 432
{
"_links" : {
"ontologies" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies"
},
"individuals" : {
"href" : "http://service.tib.eu/ts4tib/api/individuals"
},
"terms" : {
"href" : "http://service.tib.eu/ts4tib/api/terms"
},
"properties" : {
"href" : "http://service.tib.eu/ts4tib/api/properties"
},
"profile" : {
"href" : "http://service.tib.eu/ts4tib/api/profile"
}
}
}
Ontologies
The Ontologies resources is used to list ontologies in OLS
Listing ontologies
A GET
request will list all of the OLS ontologies.
Example request
$ curl -L 'http://service.tib.eu/ts4tib/api/ontologies' -i -H 'Accept: application/json'
Response structure
The response is paginated where the individual ontology resources are in the _embedded.ontologies
field.
Ontology
Retrieve an ontology
GET /ols/api/ontologies/{ontology_id}
Parameter | Description |
---|---|
ontology_id |
The ontology id in OLS |
Example request
$ curl -L 'http://service.tib.eu/ts4tib/api/ontologies/efo' -i -H 'Accept: application/json'
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3386
{
"ontologyId" : "efo",
"loaded" : "2019-04-01T10:31:42.870+0000",
"updated" : "2019-04-01T10:31:42.870+0000",
"status" : "LOADED",
"message" : "",
"version" : null,
"numberOfTerms" : 22669,
"numberOfProperties" : 328,
"numberOfIndividuals" : 0,
"config" : {
"id" : "http://www.ebi.ac.uk/efo/efo.owl",
"versionIri" : "http://www.ebi.ac.uk/efo/releases/2019-03-18/efo.owl",
"title" : "Experimental Factor Ontology",
"namespace" : "efo",
"preferredPrefix" : "EFO",
"description" : "The Experimental Factor Ontology (EFO) provides a systematic description of many experimental variables available in EBI databases, and for external projects such as the NHGRI GWAS catalogue. It combines parts of several biological ontologies, such as anatomy, disease and chemical compounds. The scope of EFO is to support the annotation, analysis and visualization of data handled by many groups at the EBI and as the core ontology for the Centre for Therapeutic Validation (CTTV)",
"homepage" : "http://www.ebi.ac.uk/efo",
"version" : "2.106",
"mailingList" : "efo-users@lists.sourceforge.net",
"creators" : [ ],
"annotations" : {
"license" : [ "www.apache.org/licenses/LICENSE-2.0" ],
"creator" : [ "Gautier Koscielny", "Simon Jupp", "Jon Ison", "Laura Huerta Martinez", "Helen Parkinson", "Eleanor Williams", "James Malone", "Zoe May Pendlington", "Trish Whetzel", "Sirarat Sarntivijai", "Catherine Leroy", "Ele Holloway", "Tomasz Adamusiak", "Emma Kate Hastings", "Olamidipupo Ajigboye", "Paola Roncaglia", "Natalja Kurbatova", "Dani Welter", "Drashtti Vasant" ],
"rights" : [ "Copyright [2014] EMBL - European Bioinformatics Institute \nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the \nLicense. " ],
"format-version" : [ "1.4" ],
"comment" : [ "2019-03-18" ]
},
"fileLocation" : "http://www.ebi.ac.uk/efo/efo.owl",
"reasonerType" : "OWL2",
"oboSlims" : false,
"labelProperty" : "http://www.w3.org/2000/01/rdf-schema#label",
"definitionProperties" : [ "http://www.ebi.ac.uk/efo/definition" ],
"synonymProperties" : [ "http://www.ebi.ac.uk/efo/alternative_term" ],
"hierarchicalProperties" : [ "http://purl.obolibrary.org/obo/RO_0002202", "http://purl.obolibrary.org/obo/BFO_0000050" ],
"baseUris" : [ "http://www.ebi.ac.uk/efo/EFO_" ],
"hiddenProperties" : [ "http://www.ebi.ac.uk/efo/has_flag" ],
"internalMetadataProperties" : [ "http://www.w3.org/2002/07/owl#versionInfo" ],
"skos" : false
},
"_links" : {
"self" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/efo"
},
"terms" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/efo/terms"
},
"properties" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/efo/properties"
},
"individuals" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/efo/individuals"
}
}
}
Links
Relation | Description |
---|---|
self |
This ontology |
terms |
|
properties |
Paginated list of properties in the ontology |
individuals |
Paginated list of individuals in the ontology |
Terms
The terms resources is used to list terms (or classes) in OLS from a particular ontology
Listing ontology terms
GET /ols/api/ontologies/{ontology_id}/terms
Parameter | Description |
---|---|
ontology_id |
The ontology id in OLS |
Optional parameters
Parameter | Description |
---|---|
iri |
Filter by IRI, when using IRI the result will always be one |
short_form |
Filter by IRI shortform, these values aren’t guaranteed to be unique e.g. GO_0098743 |
obo_id |
Filter by OBO id. This is OBO style id that aren’t guaranteed to be unique within a given ontology e.g. GO:0098743 |
Example request
$ curl -L 'http://service.tib.eu/ts4tib/api/ontologies/efo/terms' -i -H 'Accept: application/json'
Response structure
The response is paginated where the individual term resources are in the _embedded.terms
field.
Term
Retrieve a term
Example request
GET /ols/api/ontologies/{ontology}/terms/{iri}
Parameter | Description |
---|---|
ontology |
The OLS ontology id e.g. go |
iri |
The IRI of the terms, this value must be double URL encoded |
Example request
$ curl -L 'http://service.tib.eu/ts4tib/api/ontologies/go/terms/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FGO_0043226' -i -H 'Accept: application/json'
Example response
HTTP/1.1 200 OK
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
Content-Length: 3624
{
"iri" : "http://purl.obolibrary.org/obo/GO_0043226",
"label" : "GO_0043226",
"description" : [ "Organized structure of distinctive morphology and function. Includes the nucleus, mitochondria, plastids, vacuoles, vesicles, ribosomes and the cytoskeleton, and prokaryotic structures such as anammoxosomes and pirellulosomes. Excludes the plasma membrane." ],
"annotation" : {
"hasDbXref" : [ "NIF_Subcellular:sao1539965131", "Wikipedia:Organelle" ],
"hasOBONamespace" : [ "cellular_component" ],
"id" : [ "GO:0043226" ]
},
"synonyms" : null,
"ontology_name" : "go",
"ontology_prefix" : "GO",
"ontology_iri" : "http://purl.obolibrary.org/obo/go.owl",
"is_obsolete" : false,
"term_replaced_by" : null,
"is_defining_ontology" : true,
"has_children" : true,
"is_root" : false,
"short_form" : "GO_0043226",
"obo_id" : "GO:0043226",
"in_subset" : [ "goslim_chembl", "goslim_generic", "goslim_pir" ],
"obo_definition_citation" : [ {
"definition" : "Organized structure of distinctive morphology and function. Includes the nucleus, mitochondria, plastids, vacuoles, vesicles, ribosomes and the cytoskeleton, and prokaryotic structures such as anammoxosomes and pirellulosomes. Excludes the plasma membrane.",
"oboXrefs" : [ {
"database" : "GOC",
"id" : "go_curators",
"description" : null,
"url" : null
} ]
} ],
"obo_xref" : [ {
"database" : "Wikipedia",
"id" : "Organelle",
"description" : null,
"url" : "http://en.wikipedia.org/wiki/Organelle"
}, {
"database" : "NIF_Subcellular",
"id" : "sao1539965131",
"description" : null,
"url" : "http://www.neurolex.org/wiki/sao1539965131"
} ],
"obo_synonym" : null,
"_links" : {
"self" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/go/terms/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FGO_0043226"
},
"parents" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/go/terms/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FGO_0043226/parents"
},
"ancestors" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/go/terms/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FGO_0043226/ancestors"
},
"hierarchicalParents" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/go/terms/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FGO_0043226/hierarchicalParents"
},
"hierarchicalAncestors" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/go/terms/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FGO_0043226/hierarchicalAncestors"
},
"jstree" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/go/terms/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FGO_0043226/jstree"
},
"children" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/go/terms/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FGO_0043226/children"
},
"descendants" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/go/terms/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FGO_0043226/descendants"
},
"hierarchicalChildren" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/go/terms/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FGO_0043226/hierarchicalChildren"
},
"hierarchicalDescendants" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/go/terms/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FGO_0043226/hierarchicalDescendants"
},
"graph" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/go/terms/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FGO_0043226/graph"
}
}
}
Links
Relation | Description |
---|---|
self |
Link to this resource |
parents |
Link to the direct parent resources for this term |
hierarchicalParents |
Link to the direct hierarchical parent resources for this term. Hierarchical parents include is-a and other related parents, such as part-of/develops-from, that imply a hierarchical relationship |
hierarchicalAncestors |
Link to all hierarchical ancestors (all parents’s parents) resources for this term. Hierarchical ancestors include is-a and other related parents, such as part-of/develops-from, that imply a hierarchical relationship |
ancestors |
Link to all parent resources for this term |
children |
Link to the direct children resources for this term |
hierarchicalChildren |
Link to the direct hierarchical children resources for this term. Hierarchical children include is-a and other related children, such as part-of/develops-from, that imply a hierarchical relationship |
hierarchicalDescendants |
Link to all hierarchical children resources for this term. Hierarchical children include is-a and other related children, such as part-of/develops-from, that imply a hierarchical relationship |
descendants |
Link to all child resources for this term |
jstree |
A JSON tree structure of the term hierarchy |
graph |
A JSON graph structure of the immediately related nodes |
Parent/child relationships for terms
The RESTful way to retrieve direct parent/child or all parent/child (ancestors/descendant) terms is to follow the _links URL on a given term. There are cases where it is convenient to request parent/child terms for a given term when you only have the URI or short id. For these cases we have implemented a convenient endpoint for these that takes a term id as a parameter. There are methods for all parent/child relationships as documented in the links sections for term resources.
Example request
GET /ols/api/ontologies/{ontology}/parents
Parameter | Description |
---|---|
ontology |
The OLS ontology id e.g. go |
id |
The id of the term, can be URI, short form or obo id |
Example requests
$ curl -L 'http://service.tib.eu/ts4tib/api/ontologies/go/parents?id=GO:0043226' -i -H 'Accept: application/json'
$ curl -L 'http://service.tib.eu/ts4tib/api/ontologies/go/children?id=GO:0043226' -i -H 'Accept: application/json'
$ curl -L 'http://service.tib.eu/ts4tib/api/ontologies/go/ancestors?id=GO:0043226' -i -H 'Accept: application/json'
$ curl -L 'http://service.tib.eu/ts4tib/api/ontologies/go/descendants?id=GO:0043226' -i -H 'Accept: application/json'
$ curl -L 'http://service.tib.eu/ts4tib/api/ontologies/go/hierarchicalDescendants?id=GO:0043226' -i -H 'Accept: application/json'
$ curl -L 'http://service.tib.eu/ts4tib/api/ontologies/go/hierarchicalAncestors?id=GO:0043226' -i -H 'Accept: application/json'
Term matching across ontologies
It is possible to search for terms across ontologies using the requests and responses as defined in this section.
Example requests
$ curl -L 'http://service.tib.eu/ts4tib/api/terms/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000001' -i -H 'Accept: application/json'
$ curl -L 'http://service.tib.eu/ts4tib/api/terms?iri=http://www.ebi.ac.uk/efo/EFO_0000001' -i -H 'Accept: application/json'
$ curl -L 'http://service.tib.eu/ts4tib/api/terms?short_form=EFO_0000001' -i -H 'Accept: application/json'
$ curl -L 'http://service.tib.eu/ts4tib/api/terms?obo_id=EFO:0000001' -i -H 'Accept: application/json'
$ curl -L 'http://service.tib.eu/ts4tib/api/terms?id=EFO:0000001' -i -H 'Accept: application/json'
Example response
HTTP/1.1 200 OK
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
Content-Length: 3022
{
"_embedded" : {
"terms" : [ {
"iri" : "http://www.ebi.ac.uk/efo/EFO_0000001",
"label" : "EFO_0000001",
"description" : null,
"annotation" : {
"IAO_0000115" : [ "An experimental factor in Array Express which are essentially the variable aspects of an experiment design which can be used to describe an experiment, or set of experiments, in an increasingly detailed manner. This upper level class is really used to give a root class from which applications can rely on and not be tied to upper ontology classses which do change." ],
"IAO_0000117" : [ "Helen Parkinson", "James Malone", "Tomasz Adamusiak", "Jie Zheng" ],
"MO_definition_citation" : [ "MO:10" ],
"bioportal_provenance" : [ "ExperimentalFactor[accessedResource: MO_10][accessDate: 05-04-2011]" ],
"comment" : [ "Concept naming convention is lower case natural naming with spaces, when necessary captials should be used, for example disease factor, HIV, breast carcinoma, Ewing's sarcoma" ],
"created_by" : [ "Helen Parkinson", "James Malone", "Tomasz Adamusiak" ],
"organizational_class" : [ "true" ]
},
"synonyms" : [ "ExperimentalFactor" ],
"ontology_name" : "efo",
"ontology_prefix" : "EFO",
"ontology_iri" : "http://www.ebi.ac.uk/efo/efo.owl",
"is_obsolete" : false,
"term_replaced_by" : null,
"is_defining_ontology" : true,
"has_children" : true,
"is_root" : true,
"short_form" : "EFO_0000001",
"obo_id" : "EFO:0000001",
"in_subset" : null,
"obo_definition_citation" : null,
"obo_xref" : null,
"obo_synonym" : null,
"_links" : {
"self" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/efo/terms/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000001"
},
"children" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/efo/terms/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000001/children"
},
"descendants" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/efo/terms/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000001/descendants"
},
"hierarchicalChildren" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/efo/terms/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000001/hierarchicalChildren"
},
"hierarchicalDescendants" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/efo/terms/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000001/hierarchicalDescendants"
},
"graph" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/efo/terms/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000001/graph"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "http://service.tib.eu/ts4tib/api/terms/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000001"
}
},
"page" : {
"size" : 20,
"totalElements" : 1,
"totalPages" : 1,
"number" : 0
}
}
Terms based on defining ontology
Where users are interested in a particular ontology, they may also be interested in retrieving only terms from that ontology. The requests and reponses in this section defines an API for achieving this.
Example requests
$ curl -L 'http://service.tib.eu/ts4tib/api/terms/findByIdAndIsDefiningOntology/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000001' -i -H 'Accept: application/json'
$ curl -L 'http://service.tib.eu/ts4tib/api/terms/findByIdAndIsDefiningOntology?iri=http://www.ebi.ac.uk/efo/EFO_0000001' -i -H 'Accept: application/json'
$ curl -L 'http://service.tib.eu/ts4tib/api/terms/findByIdAndIsDefiningOntology?short_form=EFO_0000001' -i -H 'Accept: application/json'
$ curl -L 'http://service.tib.eu/ts4tib/api/terms/findByIdAndIsDefiningOntology?obo_id=EFO:0000001' -i -H 'Accept: application/json'
$ curl -L 'http://service.tib.eu/ts4tib/api/terms/findByIdAndIsDefiningOntology?id=EFO:0000001' -i -H 'Accept: application/json'
Example response
HTTP/1.1 200 OK
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
Content-Length: 3052
{
"_embedded" : {
"terms" : [ {
"iri" : "http://www.ebi.ac.uk/efo/EFO_0000001",
"label" : "EFO_0000001",
"description" : null,
"annotation" : {
"IAO_0000115" : [ "An experimental factor in Array Express which are essentially the variable aspects of an experiment design which can be used to describe an experiment, or set of experiments, in an increasingly detailed manner. This upper level class is really used to give a root class from which applications can rely on and not be tied to upper ontology classses which do change." ],
"IAO_0000117" : [ "Helen Parkinson", "James Malone", "Tomasz Adamusiak", "Jie Zheng" ],
"MO_definition_citation" : [ "MO:10" ],
"bioportal_provenance" : [ "ExperimentalFactor[accessedResource: MO_10][accessDate: 05-04-2011]" ],
"comment" : [ "Concept naming convention is lower case natural naming with spaces, when necessary captials should be used, for example disease factor, HIV, breast carcinoma, Ewing's sarcoma" ],
"created_by" : [ "Helen Parkinson", "James Malone", "Tomasz Adamusiak" ],
"organizational_class" : [ "true" ]
},
"synonyms" : [ "ExperimentalFactor" ],
"ontology_name" : "efo",
"ontology_prefix" : "EFO",
"ontology_iri" : "http://www.ebi.ac.uk/efo/efo.owl",
"is_obsolete" : false,
"term_replaced_by" : null,
"is_defining_ontology" : true,
"has_children" : true,
"is_root" : true,
"short_form" : "EFO_0000001",
"obo_id" : "EFO:0000001",
"in_subset" : null,
"obo_definition_citation" : null,
"obo_xref" : null,
"obo_synonym" : null,
"_links" : {
"self" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/efo/terms/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000001"
},
"children" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/efo/terms/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000001/children"
},
"descendants" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/efo/terms/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000001/descendants"
},
"hierarchicalChildren" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/efo/terms/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000001/hierarchicalChildren"
},
"hierarchicalDescendants" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/efo/terms/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000001/hierarchicalDescendants"
},
"graph" : {
"href" : "http://service.tib.eu/ts4tib/api/ontologies/efo/terms/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000001/graph"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "http://service.tib.eu/ts4tib/api/terms/findByIdAndIsDefiningOntology/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000001"
}
},
"page" : {
"size" : 20,
"totalElements" : 1,
"totalPages" : 1,
"number" : 0
}
}
Properties and individuals
You can access property (relationships) and ontology individuals (instances) following similar methods to terms.
Retrieve a property
GET /ols/api/ontologies/{ontology}/properties/{iri}
Parameter | Description |
---|---|
ontology |
The OLS ontology id e.g. go |
iri |
The IRI of the relation, this value must be double URL encoded |
Property matching across ontologies
Similar to terms, properties can be found based on id. See Term matching across ontologies. Here we only provide 2 examples: Both examples retrieve a property based on its IRI. The first illustrates finding a property where the IRI is specified as part of the path and the second illustrates finding a property where the IRI is specified as a parameter.
$ curl -L 'http://service.tib.eu/ts4tib/api/properties/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000784' -i -H 'Accept: application/json'
$ curl -L 'http://service.tib.eu/ts4tib/api/properties?iri=http://www.ebi.ac.uk/efo/EFO_0000784' -i -H 'Accept: application/json'
Properties based on defining ontology
Similar to terms, users may want to only access properties that are related to a particular ontology. See Terms based on defining ontology.
$ curl -L 'http://service.tib.eu/ts4tib/api/properties/findByIdAndIsDefiningOntology/http%253A%252F%252Fwww.ebi.ac.uk%252Fefo%252FEFO_0000784' -i -H 'Accept: application/json'
$ curl -L 'http://service.tib.eu/ts4tib/api/properties/findByIdAndIsDefiningOntology?iri=http://www.ebi.ac.uk/efo/EFO_0000784' -i -H 'Accept: application/json'
Retrieve an individual
GET /ols/api/ontologies/{ontology}/individuals/{iri}
Parameter | Description |
---|---|
ontology |
The OLS ontology id e.g. go |
iri |
The IRI of the individual, this value must be double URL encoded |
Individual matching across ontologies
Similar to terms, individuals can be found based on id. See Term matching across ontologies. Here we only provide 2 examples: Both examples retrieve an individual based on its IRI. The first illustrates finding an individual where the IRI is specified as part of the path and the second illustrates finding an individual where the IRI is specified as a parameter.
$ curl -L 'http://service.tib.eu/ts4tib/api/individuals/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FIAO_0000125' -i -H 'Accept: application/json'
$ curl -L 'http://service.tib.eu/ts4tib/api/individuals?iri=http://purl.obolibrary.org/obo/IAO_0000125' -i -H 'Accept: application/json'
Individual based on defining ontology
Similar to terms, users may want to only access individuals that are related to a particular ontology. See Terms based on defining ontology.
$ curl -L 'http://service.tib.eu/ts4tib/api/individuals/findByIdAndIsDefiningOntology/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FRO_0001901' -i -H 'Accept: application/json'
$ curl -L 'http://service.tib.eu/ts4tib/api/individuals/findByIdAndIsDefiningOntology?iri=http://purl.obolibrary.org/obo/RO_0001901' -i -H 'Accept: application/json'
Search
Search terms
The search API is independent of the REST API and supports free text search over the ontologies. The default search is across all textual fields in the ontology, but results are ranked towards hits in labels, then synonyms, then definitions, then annotations.
GET /api/search?q={query}
Search parameters
Parameter | Description |
---|---|
query |
The terms to search. By default the search is performed over term labels, synonyms, descriptions, identifiers and annotation properties. |
You can override the fields that are searched by supplying a queryFields
argument. For example, to query on labels and synonyms use
GET /ols/api/search?q={query}&queryFields={label,synonym}
Parameter | Description |
---|---|
ontology |
Restrict a search to a set of ontologies e.g. |
type |
Restrict a search to an entity type, one of {class,property,individual,ontology} |
slim |
Restrict a search to an particular set of slims by name |
fieldList |
Specifcy the fields to return, the defaults are {iri,label,short_form,obo_id,ontology_name,ontology_prefix,description,type} |
queryFields |
Specifcy the fields to query, the defaults are {label, synonym, description, short_form, obo_id, annotations, logical_description, iri} |
exact |
Set to true for exact matches |
groupField |
Set to true to group results by unique id (IRI) |
obsoletes |
Set to true to include obsoleted terms in the results |
local |
Set to true to only return terms that are in a defining ontology e.g. Only return matches to gene ontology terms in the gene ontology, and exclude ontologies where those terms are also referenced |
childrenOf |
You can restrict a search to children of a given term. Supply a list of IRI for the terms that you want to search under |
allChildrenOf |
You can restrict a search to all children of a given term. Supply a list of IRI for the terms that you want to search under (subclassOf/is-a plus any hierarchical/transitive properties like 'part of' or 'develops from') |
rows |
How many results per page |
start |
The results page number |
Select terms
We provide an additional search endopint that is designed specifically for selecting ontology terms. This has been tuned specifically to support applications such as autocomplete.
GET /ols/api/select?q={query}
Parameter | Description |
---|---|
ontology |
Restrict a search to a set of ontologies e.g. |
type |
Restrict a search to an entity type, one of {class,property,individual,ontology} |
slim |
Restrict a search to an particular set of slims by name |
fieldList |
Specify the fields to return, the defaults are {iri,label,short_form,obo_id,ontology_name,ontology_prefix,description,type} |
obsoletes |
Set to true to include obsoleted terms in the results |
local |
Set to true to only return terms that are in a defining ontology e.g. Only return matches to gene ontology terms in the gene ontology, and exclude ontologies where those terms are also referenced |
childrenOf |
You can restrict a search to all children of a given term. Supply a list of IRI for the terms that you want to search under (subclassOf/is-a relation only) |
allChildrenOf |
You can restrict a search to all children of a given term. Supply a list of IRI for the terms that you want to search under (subclassOf/is-a plus any hierarchical/transitive properties like 'part of' or 'develops from') |
rows |
How many results per page |
start |
The results page number |
Suggest term
We also provide a generic suggester endpoint. This endpoint aims to provide traditional autosuggest based on all the vocabulary in OLS (all class labels or synonyms). All results from this endpoint are unique and are not coupled to any particular ontology, however, searches can be restricted by ontology.
GET /ols/api/suggest?q={query}
Parameter | Description |
---|---|
ontology |
Restrict a search to a set of ontologies e.g. |
rows |
How many results per page |
start |
The results page number |