Ontology Lookup Service API Guide

Overview

HTTP verbs

This API supports the following HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

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

200 OK

The request completed successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

404 Not Found

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. Bad Request

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. 400

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 request

$ curl -L 'http://service.tib.eu/ts4tib/api/ontologies?page=1&size=1' -i

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

Links

Relation Description

self

This resource list

first

The first page in the resource list

next

The next page in the resource list

prev

The previous page in the resource list

last

The last page in the resource list

Resources

API

The api endpoint provides the entry point into the service.

Accessing the API

A GET request is used to access the API

Example request

$ curl -L 'http://service.tib.eu/ts4tib/api' -i -H 'Accept: application/json'

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"
    }
  }
}
Relation Description

ontologies

Link to the ontologies in OLS

terms

Link to all the terms in OLS

properties

Link to all the properties in OLS

individuals

Link to all the individuals in OLS

profile

ALPS is not currently supported

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"
    }
  }
}
Relation Description

self

This ontology

terms

Paginated list of terms in the ontology

properties

Paginated list of properties in the ontology

individuals

Paginated list of individuals in the ontology

Roots terms

You can access the root terms or properties in an ontology hierarchy with the following

GET /ols/api/ontologies/{ontology_id}/terms/roots
Parameter Description

ontology_id

The ontology id in OLS

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"
    }
  }
}
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'

Other related terms

In cases where a term has a direct relation to another term (single existential to a named class in OBO), for example a "part of" relation, the related terms can be accessed directly with this API.

GET /api/ontologies/{ontology_id}/terms/{term_iri}/{property_iri}

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. ontology=uberon,ma

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. ontology=uberon,ma

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. ontology=uberon,ma

rows

How many results per page

start

The results page number