EMBL-EBI Ontology Lookup Service (OLS)

Prerequisites

1. uv: Read the uv skill and follow its Setup instructions to ensure

uv is installed and on PATH.

1. User Notification: If LICENSE_NOTIFICATION.txt does not already exist in

this skill directory then (1) prominently notify the user to check the terms at https://www.ebi.ac.uk/ols4/api-docs, then (2) create the file recording the notification text and timestamp.

Core Rules

• !IMPORTANT] Use the Utility Scripts: You MUST ALWAYS use the provided

utility script under scripts/ for all API interactions, including checking status. NEVER use curl or custom Python requests to query API directly.

• Rate Limiting & Resilience: You MUST respect EBI's Terms of Use with a

maximum 5 requests per second. The provided utility scripts automatically enforce this.

• Notification: If this skill is used, ensure this is mentioned in the

output.

When to Use — Quick Recipes

Use this skill whenever a user query matches one of these patterns:

• Definition of a disease, phenotype, or term → get_term.py --obo_id <ID>

--summary

• Subtypes or children of a term → get_term.py --obo_id <ID>

--relations children

• Parent of a term → get_term.py --obo_id <ID> --relations parents
• Ancestors / disease categories / classified under → get_term.py

--obo_id <ID> --relations ancestors

• Root terms of an ontology → get_term.py --ontology <id> --roots
• Hierarchical parents (is-a + part-of) → get_term.py --obo_id <ID>

--relations hierarchicalParents

• Structures part of / hierarchical children → get_term.py --obo_id <ID>

--relations hierarchicalChildren

• Compare direct vs hierarchical parents → get_term.py --obo_id <ID>

--relations parents,hierarchicalParents

• Search for a term (e.g., "apoptosis" in GO) → search_ols.py --query "..."

--ontology <id>

• Find a GO term matching a function → search_ols.py --query "..."

--ontology go --exact

• Search in MONDO, CHEBI, CL, UBERON → search_ols.py --query

"..." --ontology <id> --defining

• Paginate search results / next page → search_ols.py --query "..."

--rows N --start <offset>

• Autocomplete a partial name → suggest_ols.py --query "..."
• Ontology metadata (e.g., EFO info) → get_ontology.py --id <id>
• OLS index statistics → get_stats.py

> Multi-step queries (e.g., "What is the parent of myocardial infarction?"): > When the user names a term but you don't know its OBO ID, complete in > exactly 2 steps — do NOT search across multiple ontologies: > > 1. Search in the single most appropriate ontology: search_ols.py --query > "myocardial infarction" --ontology doid --exact --rows 1 --output > /tmp/step1.json > 2. Get relations using the OBO ID from step 1: get_term.py --obo_id > DOID:5844 --relations parents --output /tmp/step2.json > > Ontology selection rule: ALWAYS use doid for common human diseases > (e.g., diabetes, cancer), hp for phenotypes, go for gene functions, > chebi for chemicals, uberon for anatomy, cl for cell types. Use mondo > ONLY when cross-species context is explicitly mentioned or needed.

Utility Scripts

1. Search Terms Across Ontologies

Search for ontology terms by keyword and return clean JSON.

bash
uv run scripts/search_ols.py --query "diabetes" \
  --rows 5 --output /tmp/ols_search_results.json 2>/dev/null

> Important: --output is required for all scripts. Results are always > written to the specified file. For larger output, you can limit --rows > (e.g., 5-10) or paginate using --start.

Returned Fields: JSON results include iri, label, description, ontology_name, ontology_prefix, obo_id, short_form, type, is_defining_ontology, and exact_synonyms.

Pagination: Output includes a pagination block with start, rows, and has_more so you can decide whether to fetch more results.

Options:

• --query: Search string (required). Searches labels, synonyms,

descriptions, and identifiers.

• --ontology: Filter by ontology ID (e.g., go, doid, efo, hp).

Recommended when you know which ontology to search — avoids noise from 250+ ontologies.

• --type: Filter by entity type: class, property, individual, or

ontology.

• --exact: Flag for exact label match only. Use this for entity

resolution when mapping a user's string to a specific ontology term ID.

• --defining: Only return terms from their defining (authoritative)

ontology. E.g., GO:0005634 only from GO, not cross-referenced copies.

• --obsolete: Flag to include obsolete terms in results.
• --local: Only return terms in their defining ontology.
• --childrenOf: Restrict to children of given term IRI(s), comma-separated.
• --allChildrenOf: Restrict to all children including transitive relations

(part of, develops from), comma-separated IRIs.

• --queryFields: Comma-separated fields to search in (e.g.,

label,synonym,description).

• --fieldList: Comma-separated fields to return.
• --groupField: Group results by unique IRI.
• --isLeaf: Only return leaf terms (no children).
• --rows: Number of results to return (default 10).
• --start: Pagination offset (default 0).
• --output: File path to save results (required).

2. Autocomplete / Suggest

Get autocomplete suggestions for partial term names.

bash
uv run scripts/suggest_ols.py --query "diabet" --rows 5 \
  --output /tmp/ols_suggest.json 2>/dev/null

Options:

• --query: Partial term to autocomplete (required).
• --ontology: Filter by ontology ID(s), comma-separated.
• --rows: Number of suggestions (default 10).
• --start: Pagination offset (default 0).
• --output: File path to save results (default: stdout).

3. Get Term Details

Retrieve full details for a specific ontology term by its OBO ID or IRI.

bash
uv run scripts/get_term.py --obo_id "GO:0005634" \
  --output /tmp/ols_term.json 2>/dev/null

Returned Fields: JSON includes iri, label, description, obo_id, synonyms, ontology_name, is_obsolete, is_defining_ontology, has_children, is_root, annotation, in_subset, and any requested relations.

Summary Mode: Use --summary to get a clean, human-readable block on stdout (Label, OBO ID, Ontology, Definition, Synonyms). The full JSON is always saved to the --output file.

bash
uv run scripts/get_term.py --obo_id "GO:0005634" --summary \
  --output /tmp/nucleus_full.json

Options:

• --obo_id: OBO-style identifier (e.g., GO:0005634, DOID:9351). Mutually

exclusive with --iri. Auto-converts to IRI with double encoding.

• --iri: Full IRI of the term. Mutually exclusive with --obo_id.
• --ontology: Ontology ID (auto-derived from --obo_id if not provided).
• --relations: Comma-separated list of relations to fetch.

• Direct (is-a only): parents, children, ancestors,

descendants

• Hierarchical (is-a + transitive like "part of", "develops from"):

hierarchicalParents, hierarchicalChildren, hierarchicalAncestors, hierarchicalDescendants

• Graph: graph — full graph JSON for a term

> Note: Use hierarchical variants for anatomical/developmental > ontologies (UBERON, CL) where transitive relations like "part of" and > "develops from" are critical for navigating the hierarchy.

• --roots: List root terms of the ontology (requires --ontology).

• --preferred_roots: List preferred root terms (requires --ontology).

• --summary: Human-readable summary on stdout, full JSON to --output.

• --output: File path to save results (default: stdout).

4. Get Property Details

Retrieve details for an ontology property (relation type) with hierarchy.

bash
uv run scripts/get_property.py --obo_id "BFO:0000051" --ontology go \
  --output /tmp/ols_property.json 2>/dev/null

Options:

• --obo_id: OBO-style ID of the property. Mutually exclusive with --iri.
• --iri: Full IRI of the property. Mutually exclusive with --obo_id.
• --ontology: Ontology ID (required with --iri).
• --relations: Comma-separated: parents, children, ancestors,

descendants.

• --roots: List root properties of the ontology (requires --ontology).
• --output: File path to save results (default: stdout).

5. Get Individual Details

Retrieve details for an ontology individual (instance).

bash
uv run scripts/get_individual.py --obo_id "IAO:0000103" --ontology iao --types \
  --output /tmp/ols_individual.json 2>/dev/null

Options:

• --obo_id: OBO-style ID. Mutually exclusive with --iri.
• --iri: Full IRI. Mutually exclusive with --obo_id.
• --ontology: Ontology ID (required with --iri).
• --types: Fetch the direct types (classes) of this individual.
• --alltypes: Fetch all types including ancestor classes.
• --output: File path to save results (default: stdout).

6. Get Ontology Information

List available ontologies or retrieve details for a specific one.

bash
uv run scripts/get_ontology.py --id go \
  --output /tmp/ols_ontology.json 2>/dev/null

Options:

• --id: Specific ontology ID (e.g., go, efo, doid). If omitted, lists

all ontologies.

• --page: Page number for pagination (default 0).
• --size: Number of ontologies per page (default 20).
• --output: File path to save results (default: stdout).

7. Get OLS Statistics

Retrieve index statistics (total ontologies, classes, properties, individuals).

bash
uv run scripts/get_stats.py --output /tmp/ols_stats.json 2>/dev/null

Options:

• --output: File path to save results (default: stdout).

Reference

• API Reference: See

references/api_reference.md for common ontology IDs, OBO ID format, and key API endpoints.

Workflow

1. Use suggest_ols.py for autocomplete when you have a partial term name.
2. Search for terms using search_ols.py. Use --defining to prioritize

authoritative definitions. Use --exact for entity resolution.

1. If full details are needed, use get_term.py with the OBO ID or IRI. Use

--summary for a concise view.

1. To explore a term's hierarchy, use get_term.py --relations

parents,children for is-a only, or --relations hierarchicalParents,hierarchicalChildren for "part of" etc.

1. To explore from the top down, use get_term.py --ontology go --roots.
2. For properties or individuals, use get_property.py or get_individual.py.
3. To discover available ontologies, use get_ontology.py.
4. To check OLS index status, use get_stats.py.