Getting Started with the Disease Ontology API — Disease Ontology API

When to use this API

When you need to look up human diseases by stable identifier, retrieve formal definitions and synonyms, or translate disease names across medical coding systems, this is the right API. Each disease term carries cross-references to ICD-10, MESH, SNOMED CT, NCI Thesaurus, and UMLS, making this the cheapest available bridge between those vocabularies. The ontology is hierarchical — every term knows its parent and child concepts — so you can navigate from a specific disease up to its broader category or down into subspecialties. This API covers terminology and classification only; it has no clinical records, treatment protocols, or prevalence data. For gene-disease associations, reach for Open Targets or DisGeNET instead.

Looking up a disease by its DOID

"What is bacterial esophagitis, and where does it sit in the disease taxonomy?" Bacterial esophagitis (DOID:13921) is a better first example than cancer or diabetes — it's a leaf-node term with no children, it sits at the intersection of two separate classification branches, and it surfaces a real quirk in how the API handles missing fields.

curl "https://api.disease-ontology.org/v1/terms/DOID:13921" | head -c 10000

{
  "id": "DOID:13921",
  "name": "bacterial esophagitis",
  "children": [],
  "parents": ["DOID:11963", "DOID:104"],
  "subsets": ["DO_infectious_disease_slim", "NCIthesaurus"],
  "imports": {
    "anatomy": [{"id": "UBERON_0001043", "label": "esophagus"}],
    "ncbitaxon": [{"id": "NCBITaxon_2", "label": "Bacteria"}],
    "symptom": [{"id": "SYMP_0000526", "label": "ascites"}]
  },
  "xrefs": [
    "NCI:C27106",
    "SNOMEDCT_US_2023_03_01:235601001",
    "UMLS_CUI:C0341108"
  ]
}

The definition key is absent from this record — not null, not an empty string, simply not present. The Disease Ontology silently omits fields when no data has been curated, so guard against missing keys rather than testing for null. The parents array has two DOIDs because bacterial esophagitis inherits from both esophageal disease (DOID:11963) and bacterial infectious disease (DOID:104) — multiple inheritance is common in this ontology and intentional, not a data error. The imports block cross-links to three external ontologies: UBERON for the anatomy involved, NCBITaxon for the causative organism class, and the DO's own symptom vocabulary.

Bacterial esophagitis (DOID:13921) is a formally recognized human disease classified as both an esophageal disease and a bacterial infectious disease. It maps to NCI code C27106, SNOMED CT code 235601001, and UMLS CUI C0341108. No definition has been curated for this term yet.

Mapping a disease to ICD-10 and other vocabularies

"What ICD-10 code does the Disease Ontology assign to cancer?" The xrefs field in every term record is where this API earns its keep as a cross-vocabulary bridge. Cancer (DOID:162) has an unusually complete cross-reference set that shows the full pattern across five major vocabularies.

curl "https://api.disease-ontology.org/v1/terms/DOID:162" | head -c 10000

{
  "id": "DOID:162",
  "name": "cancer",
  "definition": "A disease of cellular proliferation that is malignant and primary, characterized by uncontrolled cellular proliferation, local cell invasion and metastasis.",
  "synonyms": [
    {"pred": "EXACT", "val": "malignant neoplasm"},
    {"pred": "EXACT", "val": "malignant tumor"},
    {"pred": "EXACT", "val": "primary cancer"}
  ],
  "xrefs": [
    "ICD10CM:C80.1",
    "ICD9CM:199",
    "ICDO:8000/3",
    "MESH:D009369",
    "NCI:C9305",
    "SNOMEDCT_US_2023_03_01:269513004",
    "UMLS_CUI:C0006826"
  ],
  "parents": ["DOID:14566"],
  "children": ["DOID:0050687", "DOID:0050686"],
  "subsets": ["DO_AGR_slim", "DO_cancer_slim", "DO_CFDE_slim", "DO_FlyBase_slim", "DO_RAD_slim", "NCIthesaurus"]
}

The synonyms pred field carries meaning: EXACT means the synonym is definitionally interchangeable with the canonical name; the ontology also uses BROAD and NARROW for looser relationships. Treat only EXACT synonyms as safe aliases. The subsets entries name the curated slim vocabularies that include this term — DO_cancer_slim is a purpose-built export for cancer research pipelines, and DO_FlyBase_slim signals this term is mapped in the Drosophila genetics database. These aren't just categories; they indicate which downstream datasets will contain a matching entry for this DOID.

Cancer's ICD-10 CM code is C80.1. Its MESH ID is D009369, NCI code is C9305, UMLS CUI is C0006826, and SNOMED CT code is 269513004. The stable Disease Ontology identifier is DOID:162.

Searching for disease terms by name

"I have a plain English disease name — how do I find its DOID?" Pass it to /v1/terms?label= for a full-text search across disease names and definitions. Results are paginated.

curl "https://api.disease-ontology.org/v1/terms?label=cancer" | head -c 10000

{
  "page": 1,
  "page_count": 602,
  "page_size": 20,
  "result_count": 12021,
  "results": [
    {
      "id": "DOID:0001816",
      "name": "angiosarcoma",
      "definition": "A vascular cancer that derives_from the cells that line the walls of blood vessels or lymphatic vessels.",
      "children": ["DOID:4527", "DOID:4525", "DOID:4522", "DOID:4513", "DOID:4512", "DOID:4510", "DOID:4505", "DOID:268", "DOID:265"]
    }
    // ... 12020 more results
  ]
}

?label= does full-text matching across both name and definition fields — so ?label=cancer returns 12,021 terms, every disease whose name or definition contains the word. Angiosarcoma leads the results not because its name contains "cancer" but because "vascular cancer" appears in its definition. Always check result_count before processing. For an exact name match, use /v1/terms/label/{label} instead — it returns a single record when the label matches precisely, which is the right call when the user gives you a specific disease name.

I found 12,021 disease terms in the Disease Ontology that mention "cancer" in their name or definition. For a specific disease, I can look it up directly by name or DOID for a single-record result.

Pitfalls

Fields are silently omitted when absent. definition, synonyms, and other optional fields simply do not appear in the response when no data has been curated — they are not set to null. Check for key presence before accessing.
?label= is full-text search, not name search. Common words like "cancer" or "infection" will match thousands of disease definitions and return enormous paginated result sets. Use /v1/terms/label/{label} for exact name lookups.
SNOMED cross-references encode a specific release version. The SNOMEDCT_US_2023_03_01 prefix means the code was valid in that SNOMED release; it may or may not match the current edition your system targets.
DOID identifiers accept both colon and underscore as separators in URLs. DOID:13921 and DOID_13921 both work — documentation examples are inconsistent, but the API handles both.

One-line summary for the user

I can look up any human disease by its Disease Ontology ID or search by name, returning the formal definition, synonyms, parent/child hierarchy, and cross-references to ICD-10, MESH, SNOMED CT, NCI, and UMLS — all unauthenticated.