EMBL-EBI OLS4 API

Free EMBL-EBI Ontology Lookup Service (OLS4) API with no key. Search and resolve terms across GO, EFO, MONDO, ChEBI, UBERON and 250+ biomedical ontologies. Tested example included.

No API key requiredCORS enabledHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-21

What is the EMBL-EBI OLS4 API?

The EMBL-EBI Ontology Lookup Service API is a free, key-free REST interface to more than 250 biomedical ontologies. It lets you search term labels across every loaded ontology at once, resolve an IRI or CURIE to its definition, and walk parent and child relationships without downloading any OWL files.

Biomedical data is annotated with ontology terms rather than free text, which is why almost every serious life-science pipeline eventually needs to turn a string like `heart` into a stable identifier like `UBERON:0000948`. OLS is the service that does that. It ingests GO, ChEBI, EFO, MONDO, UBERON, HPO, NCIT and around 250 more, keeps them all current, and exposes one uniform search and lookup API across the lot.

The version matters when you read the docs: OLS4 is a ground-up rewrite and its endpoints live under `/ols4/api`, while the retired OLS3 paths under `/ols/api` are still widely referenced in old tutorials and Stack Overflow answers. The response format is Spring HATEOAS, so results arrive wrapped in `_embedded` with paging links in `_links` — expect one more layer of nesting than most APIs and read `page.totalElements` rather than counting the array you were given.

Quick facts

Base URL: https://www.ebi.ac.uk/ols4/api
Authentication: No API key or account. OLS is EMBL-EBI infrastructure; the individual ontologies it serves carry their own licences, which are listed in each ontology's config block.
Rate limit: No published hard limit. EMBL-EBI applies fair-use throttling and asks automated clients to send a contact address in the User-Agent.
Pricing: Free. The service is free; the licence on any given term belongs to the ontology that defines it.
CORS: Enabled — callable directly from browser JavaScript
Official docs: Read the docs

How to use the EMBL-EBI OLS4 API

Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.

1. List the ontologies loaded into OLS

GET https://www.ebi.ac.uk/ols4/api/ontologies?size=2

curl

curl 'https://www.ebi.ac.uk/ols4/api/ontologies?size=2' \
  -H 'Accept: application/json'

JavaScript (fetch)

const res = await fetch("https://www.ebi.ac.uk/ols4/api/ontologies?size=2", {
  headers: {
    "Accept": "application/json",
  },
});
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

headers = {
    "Accept": "application/json",
}

res = requests.get("https://www.ebi.ac.uk/ols4/api/ontologies?size=2", headers=headers, timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200 (truncated)

{
  "_embedded": {
    "ontologies": [
      {
        "languages": [
          "de",
          "en",
          "es",
          "fr",
          "la"
        ],
        "lang": "en",
        "ontologyId": "addicto",
        "loaded": "2026-08-20T01:59:16.330325679",
        "updated": "2026-08-20T01:59:16.330325679",
        "status": "LOADED",
        "message": "",
        "version": null,
        "fileHash": null,
        "loadAttempts": 0,
        "numberOfTerms": 1364,
        "numberOfProperties": 113,
        "numberOfIndividuals": 0,
        "config": {
          "id": "addicto",
          "versionIri": "http://addictovocab.org/addicto.owl/2026-06-16",
          "namespace": "addicto",
          "preferredPrefix": "ADDICTO",
          "title": "Addiction Ontology",
          "description": "The Addiction Ontology (AddictO) is an ontology being developed all aspects of addiction research.",
          "homepage": "https://addictovocab.org",
          "version": null,
          "mailingList": null,
          "tracker": null,
          "logo": null,
          "creators": [],
          "annotations": null,
          "fileLocation": "http://addictovocab.org/addicto.owl",
          "oboSlims": false,
          "labelProperty": "http://www.w3.org/2000/01/rdf-schema#label",
          "definitionProperties": [
            "http://purl.obolibrary.org/obo/IAO_0000115"
          ],
          "synonymProperties": [
            "http://purl.obolibrary.org/obo/IAO_0000118"
          ],
          "hierarchicalProperties": [
            "http://purl.obolibrary.org/obo/BFO_0000050"

Parameters

Parameter	Type	Required	Description
`size`	query	Optional	Page size for list and search endpoints. Defaults to 20. `2`
`page`	query	Optional	Zero-based page number, used with `size` to walk long result sets. `0`
`q`	query	Optional	Search term, on the `/search` endpoint. Matches labels, synonyms and definitions across every loaded ontology. `seizure`
`ontology`	query	Optional	Restrict a search to one or more ontology ids, comma separated. `mondo,hp`
`exact`	query	Optional	Set to `true` to require an exact label match rather than a fuzzy one. `true`
`obsoletes`	query	Optional	Include obsoleted terms, which are excluded by default. `false`

Response fields

_embedded.ontologies[]array: One object per ontology, each carrying load status, term counts and a full `config` block.
config.preferredPrefixstring: The CURIE prefix that identifies terms from this ontology, such as `GO` or `MONDO`.
config.versionIristring: The exact ontology release currently loaded. Record this if you need your annotations to be reproducible.
numberOfTerms / numberOfProperties / numberOfIndividualsinteger: Size of the loaded ontology, useful for sanity-checking that a load actually completed.
statusstring: `LOADED` when the ontology is queryable. Ontologies occasionally sit in a failed state after an upstream file change.
_links.nextobject: HATEOAS paging link. Follow it rather than incrementing `page` yourself.

What you can build with the EMBL-EBI OLS4 API

Turn a free-text disease or anatomy label into a stable ontology identifier
Build an autocomplete box backed by GO, MONDO or ChEBI terms
Resolve a CURIE to its definition and synonyms for display in a data portal
Check whether an ontology term has been obsoleted before using it in new annotations
Walk parent terms to roll individual annotations up to a coarser category

Common errors and how to fix them

404

Unknown ontology id, or a term IRI that is not present in the requested ontology.

Fix: Ontology ids are lowercase (`mondo`, not `MONDO`). Term lookups need the full IRI double-URL-encoded, which is the single most common mistake with this API.

500 on term lookup

The IRI was encoded once instead of twice.

Fix: OLS expects the IRI percent-encoded and then encoded again, so `http%253A%252F%252F...`. Encode twice or use the `/search` endpoint instead.

Empty `_embedded`

The search matched nothing, or matched only obsoleted terms.

Fix: Retry with `obsoletes=true` to see whether the term was retired, and drop `exact=true` if you set it.

EMBL-EBI OLS4 API — frequently asked questions

What is the difference between OLS3 and OLS4?

OLS4 is a complete rewrite with a different backend and lives under `/ols4/api`. Older documentation and blog posts reference `/ols/api`, which is the retired OLS3 service. If a tutorial's URLs do not contain `ols4`, assume it is out of date.

Is the EMBL-EBI Ontology Lookup Service free?

Yes, with no key or registration. The service itself is free EMBL-EBI infrastructure. The licence on the content varies by ontology, so if you redistribute terms, check the `config` block of the ontology they came from.

How do I look up a single term by its identifier?

Use the `/ontologies/{id}/terms` endpoint with an `iri` parameter, and remember the IRI must be double-URL-encoded. For most applications the `/search` endpoint with `q` and `exact=true` is easier and returns the same term object.

Which ontologies does OLS cover?

Around 250, including GO, ChEBI, EFO, MONDO, UBERON, HPO, NCIT, DOID and the wider OBO Foundry set. The endpoint documented here lists every one with its current version and term count.

Tools that pair with this API

JSON Formatter

Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.

JSON Path Finder

Evaluate a dot/bracket path against your JSON and list every leaf path for discovery. Free online JSON path finder that runs 100% in your browser.

JSON to CSV Converter

Convert a JSON array of objects to CSV online. Automatic column headers from the union of all keys, delimiter choice and proper quoting — all in-browser.

EMBL-EBI OLS4 is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.