Ontology directory

List all supported ontologies, or fetch one ontology's hierarchy, definitions, coverage statistics, and example events.

GET/api/v2.0-preview/ontology

Authorizations

Bearer

Authorizationstringrequiredheader

Required Bearer API key. Programmatic access to the World API needs a key; browsing nosible.world in a browser does not.

Example: Bearer nos_sk_...

Parameters

query & path

ontologystringquery

Optional ontology id or slug. Omit it to list every supported ontology; use emdat for the full EM-DAT reference.

Example: emdat

How to use this endpoint

guidance

Call without parameters to list every supported ontology. Add ontology=emdat for the nested EM-DAT tree, definitions, example events, and live coverage statistics.

Response body

application/json

These are the fields you can build against. Nested names use dot notation; optional sections are called out in their descriptions.

schemastring

Response schema name.

ontologiesobject[]

Every supported taxonomy, when ontology is not sent.

ontologies[].idstring

Taxonomy id, accepted by ontology=. It can differ from the name in an event's ontologies (media_frames here, media_frame there).

ontologies[].slugstring

URL slug, also accepted by ontology=.

ontologies[].namestring

Taxonomy name.

ontologies[].short_namestring

Short taxonomy name.

ontologies[].descriptionstring

What the taxonomy classifies.

ontologies[].levelsstring[]

Slot names, from the top level down.

ontologies[].category_countinteger

Classes in the taxonomy.

ontologies[].leaf_countinteger

Leaf classes.

ontologies[].root_countinteger

Top-level classes.

ontologies[].max_depthinteger

Depth of the deepest class; 0 for a flat taxonomy.

ontologies[].events_supportedboolean

Whether events are classified in the taxonomy.

ontologies[].coverageobject

labelled_events, unclassified_events, world_events and share_of_world in the current index.

ontologies[].reference_urlstring

The taxonomy's reference page on nosible.com.

ontologies[].details_urlstring

This endpoint for the one taxonomy.

countinteger

Taxonomies listed.

ontologyobject

The selected taxonomy's metadata (with ontology=): id, name, levels, counts, versions and source.

coverageobject

Indexed event counts and share for the selected taxonomy (with ontology=).

examplesobject

How the example events in the hierarchy were chosen (with ontology=).

hierarchyobject[]

The selected taxonomy as a tree (with ontology=): each class with its path, definition, event_count, events_url, example_events and children.

as_ofobject

index_build, archive_cutoff and rows (events in the index).

Responses and errors

HTTP

200Request succeeded. The response body is shown in the panel on the right.

400invalid_request — The date, filter, cursor, identifier, or request combination is invalid.

401api_key_required — No API key was sent. Send it as Authorization: Bearer <key> or the api-key header.

401invalid_api_key — The API key is invalid or has been revoked.

403access_denied — The requested archive date is outside the caller's World tier.

404not_found — The requested date, entity, ticker, or event does not exist in the accessible index.

410cursor_expired — The cursor was minted against a replaced index build. Restart pagination from the first page.

429rate_limited — The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.

501backend_not_configured — The World backend is not configured for this deployment.

503api_key_auth_unavailable — API key authentication is temporarily unavailable; retry shortly.

502backend_error — The BFF could not obtain a valid response from the World backend.

504backend_timeout — The World backend or an upstream data source timed out.

404unknown_ontology — The ontology id or slug is not in the supported ontology directory.

503inverted_index_unavailable — Current ontology counts cannot be served until the live World index is loaded.