ICTV ontology API

Resolve virus taxa across ICTV releases programmatically.

ICTV Logo EVORA Project Logo

Programmatic access to the official taxonomy of viruses with ICTV Ontology API – Helper Libraries & Direct API Access

📑 Quick Navigation

🌍 What is the ICTV OLS API?

The EVORA project (European Viral Outbreak Response Alliance) in collaboration with the ICTV (International Committee on Taxonomy of Viruses) has developed a public programmatic access to the official taxonomy of viruses by transforming ICTV releases into the ICTV ontology and serving it through the Ontology Lookup Service (OLS) API.

OLS is a REST-based web service hosted by EMBL-EBI that provides programmatic access to biomedical ontologies, including the ICTV ontology. This makes it possible to retrieve structured semantic information about virus taxa and their relationships across ICTV releases.

This is useful for:

With the ICTV OLS API, you can:

📖 API Documentation

The ICTV OLS API follows REST principles and returns JSON responses, making it accessible from any programming language or environment that can make HTTP requests.

🎯 Two Approaches to Access the ICTV OLS API

The ICTV ontology data can be accessed in two complementary ways:

✅ Approach 1: Helper Libraries (recommended for most users)

Lightweight client libraries that encapsulate the complexity of direct OLS queries and provide a simple, domain-friendly interface for common use cases.

Use this if you:

🔧 Approach 2: Direct OLS API access

Direct HTTP access to the OLS API endpoints, giving you full control and flexibility for custom queries and advanced workflows.

Use this if you:

📘 Helper Libraries Overview

This directory provides lightweight client libraries that make it easy to query the ICTV Ontology API, as served through the OLS API.

These helpers allow you to resolve ICTV taxon names, historical ICTV identifiers, IRIs, virus names and NCBI Taxon IDs to the current ICTV taxon, including lineage and replacement history.

📦 Available Implementations

Helpers are available in three languages:

helpers/
 ├── js/
 │    └── ictv-api.js
 ├── python/
 │    └── ictv-api.py
 └── php/
      └── ictv-api.php

🚀 Quick Start with Helper Libraries

🔹 JavaScript (js/ictv-api.js)

ES module suitable for browsers, Node.js, and static sites.

Installation: Simply import from CDN or local file.

import { ICTVApi } from 'https://cdn.jsdelivr.net/gh/EVORA-project/ictv-ontology/helpers/js/ictv-api.js';

const api = new ICTVApi();
const result = await api.resolveToLatest("SARS-CoV-2");
console.log(result);

Note: Requires a module-compatible environment. Use in HTML with script type="module"> or in modern Node.js projects with "type": "module" in package.json.

Features:

No dependencies — pure ES module.

👉 Full JS helper documentation: See helpers/js/README.md

🔹 Python (python/ictv-api.py)

Best for: Data pipelines, scripts, Jupyter notebooks, ETL workflows

Lightweight client using the requests library.

Installation: Copy python/ictv-api.py to your project.

from ictv_api import ICTVOLSClient

client = ICTVOLSClient()
result = client.resolveToLatest("Zika virus")
print(result)

Features:

👉 Full Python helper documentation: See helpers/python/README.md

🔹 PHP (php/ictv-api.php)

Best for: Server-side integrations, CMS backends, database imports

Standalone PHP helper using cURL (built-in).

Installation: Copy php/ictv-api.php to your project.

require_once "ictv-api.php";

$api = new ICTVOLSClient();
$result = $api->resolveToLatest("Tehran virus");
print_r($result);

Features:

👉 Full PHP helper documentation: See helpers/php/README.md

📚 Choose Your Helper

Feature JavaScript Python PHP
Basic resolution ✅ ✅ ✅
Bulk export (getAllFromRelease) ❌ ✅ ✅
Release-specific queries ❌ ✅ ✅
Dependencies None requests curl (built-in)
Best for 🌐 Web 📊 Data pipelines 🖥️ Server-side
Full Docs js/README python/README php/README

📚 Helper Library Architecture

Common Resolution Strategy

All three helper implementations follow the same general resolution strategy:

  1. recognize ICTV IRIs and identifiers
  2. optionally map NCBI Taxon identifiers to ICTV taxa
  3. search classes by label and synonym
  4. search individuals when needed and resolve them upward through their parent class
  5. follow replacement chains when an entity is obsolete until final non-obsolete taxa are reached

Normalized Output

The helper libraries return a normalized ICTV taxon object containing:

This abstraction allows developers to focus on domain logic rather than on raw OLS API response handling.

🌐 Live Implementation Example

👉 ICTV Taxon Resolver
https://evora-project.github.io/ictv-resolver/

A browser-based demonstration of the helper logic. It accepts:

and returns the latest accepted ICTV taxon with lineage and mapping information.

Source code: https://github.com/EVORA-project/ictv-resolver

🔧 Advanced: Direct OLS API Access

For users who need direct access to the ICTV Ontology Lookup Service API without using helper libraries, this section provides guidance on constructing and executing OLS API queries.

👉 Official OLS Documentation: https://www.ebi.ac.uk/ols4/api-docs

📡 OLS API Endpoints Overview

The ICTV Ontology is exposed through two main sets of OLS endpoints:

v1 Endpoints (legacy)

https://www.ebi.ac.uk/ols4/api/ontologies/ictv

Examples:

https://www.ebi.ac.uk/ols4/api/v2/ontologies/ictv

Examples:

🎯 Common Use Cases with Examples

Use Case 1: Building a Local Cache of a former release

If you want to retrieve all classes for one ICTV release, your code can query the classes endpoint while filtering by the release value stored in owl:versionInfo, with pagination and the includeObsoleteEntities set to true as all former releases terms are marked as obsolete.

Example pattern:

GET /api/v2/ontologies/ictv/classes?http%3A%2F%2Fwww.w3.org%2F2002%2F07%2Fowl%23versionInfo=MSL39&page=0&size=10&includeObsoleteEntities=true

Parameters:

An iteration loop can simply handle paginated results to retrieve all terms

Response structure: JSON array of classes objects with IRIs, labels, synonyms, and metadata.

Use Case 2: Building a Local Cache of the latest release

Note: As the ICTV ontology is a unified ontology of all ICTV releases (made available online on OLS typically 24H after a new ICTV release), as all the previous releases terms are marked as obsolete and as the classes endpoint has false for default value of the includeObsoleteEntities parameter, omitting the versionInfo and the includeObsoleteEntities will automatically return the taxonomic terms of the most recent ICTV release.

example: https://www.ebi.ac.uk/ols4/api/v2/ontologies/ictv/classes?page=0&size=1000

Example response fragment:

{
  "page" : 0,
  "numElements" : 1000,
  "totalPages" : 21,
  "totalElements" : 20845,
  "elements" : [ {
    "appearsIn" : [ "ictv" ],
    "curie" : "ICTV19710003",
    "directAncestor" : [ "http://ictv.global/id/MSL40/ICTV20080005", "http://ictv.global/id/MSL40/ICTV201857095", "http://ictv.global/id/MSL40/ICTV201907198", "http://ictv.global/id/MSL40/ICTV201907209", "http://ictv.global/id/MSL40/ICTV201907210", "http://purl.obolibrary.org/obo/NCBITaxon_10239" ],
    "directParent" : [ "http://ictv.global/id/MSL40/ICTV20080005" ],
    "hasDirectChildren" : true,
    "hasDirectParents" : true,
    "hasHierarchicalChildren" : true,
    "hasHierarchicalParents" : true,
    "hierarchicalAncestor" : [ "http://ictv.global/id/MSL40/ICTV20080005", "http://ictv.global/id/MSL40/ICTV201857095", "http://ictv.global/id/MSL40/ICTV201907198", "http://ictv.global/id/MSL40/ICTV201907209", "http://ictv.global/id/MSL40/ICTV201907210", "http://purl.obolibrary.org/obo/NCBITaxon_10239" ],
    "hierarchicalParent" : [ "http://ictv.global/id/MSL40/ICTV20080005" ],
    "hierarchicalProperty" : "http://www.w3.org/2000/01/rdf-schema#subClassOf",
    "imported" : false,
    "iri" : "http://ictv.global/id/MSL40/ICTV19710003",
    "isDefiningOntology" : false,
    "isObsolete" : false,
    "isPreferredRoot" : false,
    "label" : [ "Picornaviridae" ],
    "linkedEntities" : {
      "http://ictv.global/id/MSL39/ICTV19710003" : {
        "numAppearsIn" : 1.0,
        "hasLocalDefinition" : true,
        "label" : [ "Picornaviridae" ],
        "curie" : "ICTV19710003",
        "type" : [ "class", "entity" ]
      },
    ...

}

Use Case 3: Resolving Historical References

Objective: Find the current accepted ICTV taxon for a viral taxon that may be known by a historical or obsolete taxon name.

Step 1: Search for the Historical Name (Including Obsolete Terms)

https://www.ebi.ac.uk/ols4/api/v2/ontologies/ictv/classes?label=severe%20acute%20respiratory%20syndrome%20coronavirus&includeObsoleteEntities=true

Parameters:

Response: List of matching classes, including obsolete ones.

Note: Except in case where it is already known that the searched term is obsolete, it is a good practice to run a first search with includeObsoleteEntities=false to seek in the most recent ICTV release first.

Step 2: Follow the Replacement Chain

When an obsolete entity is found, it typically includes a reference using the IAO:0100001 property (term_replaced_by), which links to the current/replacement taxon.

Key metadata fields:

Example workflow:

1. Search: "Severe acute respiratory syndrome coronavirus"
2. Find obsolete entity with IRI: http://ictv.global/id/MSL22/ICTV20040588
3. Check for "term_replaced_by" relationship → points to:
   http://ictv.global/id/MSL40/ICTV20040588
4. Fetch the replacement entity (see Use Case 4 below)
5. Return as the current accepted taxon

Use Case 4: Resolving ICTV IDs

Objective: Query the ICTV API using stable ICTV IDs, which remain consistent across releases.

ICTV IDs (e.g., ICTV20040588) are stable identifiers provided by ICTV specifically for use with the ICTV ontology and API.

Pattern for ICTV ID Resolution

The API endpoint pattern for resolving by ICTV ID is:

https://ebi.ac.uk/ols4/api/v2/ontologies/{ONTOLOGY}/classes/{DOUBLE_URL_ENCODED_IRI}

Step-by-Step Example: Resolving SARS-CoV-2

1. Construct the IRI:

http://ictv.global/id/MSL40/ICTV20040588

2. Double URL-Encode the IRI:

The IRI must be double URL-encoded to embed it safely in the API path:

Original:  http://ictv.global/id/MSL40/ICTV20040588
Encoded:   http%253A%252F%252Fictv.global%252Fid%252FMSL40%252FICTV20040588

Encoding breakdown:

3. Construct the full API URL:

https://ebi.ac.uk/ols4/api/v2/ontologies/ictv/classes/http%253A%252F%252Fictv.global%252Fid%252FMSL40%252FICTV20040588

4. Fetch the entity:

curl "https://ebi.ac.uk/ols4/api/v2/ontologies/ictv/classes/http%253A%252F%252Fictv.global%252Fid%252FMSL40%252FICTV20040588"

Response: Full JSON object for the species of SARS-CoV-2 including:

General IRI Encoding Pattern

For any ICTV IRI, follow this pattern:

1. IRI Format:        http://ictv.global/id/{RELEASE}/{ICTV_ID}
2. Step 1 Encoding:   http%3A%2F%2Fictv.global%2Fid%2F{RELEASE}%2F{ICTV_ID}
3. Step 2 Encoding:   http%253A%252F%252Fictv.global%252Fid%252F{RELEASE}%252F{ICTV_ID}
4. API URL:           https://ebi.ac.uk/ols4/api/v2/ontologies/ictv/classes/{STEP_2_ENCODING}

📋 Direct API Quick Reference

Essential v2 Endpoints

Endpoint Purpose
GET /api/v2/ontologies/ictv/classes List all current ICTV classes/taxa
GET /api/v2/ontologies/ictv/classes?label={LABEL} Search classes by taxon name
GET /api/v2/ontologies/ictv/classes?label={LABEL}&includeObsoleteEntities=true Search classes by name including obsolete taxa
GET /api/v2/ontologies/ictv/classes/{ENCODED_IRI} Retrieve a specific class by IRI
GET /api/v2/ontologies/ictv/entities List all entities, including classes and individuals
GET /api/v2/ontologies/ictv/entities?label={LABEL} Search by name across all entity types
GET /api/v2/ontologies/ictv/entities/{ENCODED_IRI} Retrieve a specific entity by IRI
GET /api/v2/ontologies/ictv/individuals List isolates and strains
GET /api/v2/ontologies/ictv/properties List ontology properties

Common Query Parameters

Parameter Values Purpose
label string (URL-encoded) Search by entity label/name
includeObsoleteEntities true/false Include obsolete terms in results
page integer Page number (0-indexed)
size integer (1-1000) Results per page

🔍 Response Structure and Navigation

Typical v2 Class Response

{
  "iri": "http://ictv.global/id/MSL38/ICTV20040588",
  "label": "Severe acute respiratory syndrome-related coronavirus",
  "synonym": [
    "SARS-CoV",
    {
      "type": [
        "reification"
      ],
      "value": "Severe acute respiratory syndrome coronavirus",
      "axioms": [
        {
          "http://www.geneontology.org/formats/oboInOwl#hasSynonymType": "http://purl.obolibrary.org/obo/OMO_0003008",
          "http://www.w3.org/2002/07/owl#versionInfo": "MSL22",
          "oboSynonymTypeName": "previous name"
        }
      ]
    }
  ],
  "isObsolete": true,
  "hierarchicalParent": [ "http://ictv.global/id/MSL38/ICTV20186129" ],
  "hierarchicalAncestor": [ "http://ictv.global/id/MSL38/ICTV19750006", "http://ictv.global/id/MSL38/ICTV19960002", "http://ictv.global/id/MSL38/ICTV20090624", "http://ictv.global/id/MSL38/ICTV20091082", "http://ictv.global/id/MSL38/ICTV201857095", "http://ictv.global/id/MSL38/ICTV20186105", "http://ictv.global/id/MSL38/ICTV20186129", "http://ictv.global/id/MSL38/ICTV201907198", "http://ictv.global/id/MSL38/ICTV201907209", "http://ictv.global/id/MSL38/ICTV201907210", "http://purl.obolibrary.org/obo/NCBITaxon_10239" ],
  "http://purl.obolibrary.org/obo/IAO_0100001" : "http://ictv.global/id/MSL40/ICTV20040588",
  "http://purl.obolibrary.org/obo/TAXRANK_1000000" : "http://purl.obolibrary.org/obo/TAXRANK_0000006",
  "http://purl.org/dc/terms/identifier" : "ICTV20040588"
  }

Key Fields

🛠️ Working with Replacement Chains

When resolving historical taxa, you may encounter the term_replaced_by relationship (IAO:0100001):

Original Request:
  GET /api/v2/ontologies/ictv/classes?label=old%20name&includeObsoleteEntities=true

Response includes:
  {
    "iri": "http://ictv.global/id/OLD_RELEASE/ICTV123456",
    "label": ["Old taxon name"],
    "isObsolete": true,
    "http://purl.obolibrary.org/obo/IAO_0100001": "http://ictv.global/id/MSL40/ICTV789012"
    }
  }

Follow-up Request:
  GET /api/v2/ontologies/ictv/classes/http%253A%252F%252Fictv.global%252Fid%252FMSL40%252FICTV789012

Response:
  {
    "iri": "http://ictv.global/id/MSL40/ICTV789012",
    "label": "Current taxon name",
    "isObsolete": false,
    ...
  }

Real example request URL of ICTV ID ICTV20040588 on MSL38 with API V2: https://www.ebi.ac.uk/ols4/api/v2/ontologies/ictv/classes/http%253A%252F%252Fictv.global%252Fid%252FMSL38%252FICTV20040588

📖 Additional Resources

Official OLS Documentation

ICTV Ontology Resources

Jupyter Notebook Example

The repository includes a comprehensive Jupyter notebook illustrating typical workflows:

🌐 When to Use Direct API vs. Helper Libraries

Use Direct API Access When:

Use Helper Libraries When:

🔗 Related Resources

🤝 Support & Feedback

⚖️ License

This site is open source. Improve this page.