Ontology directory

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

GET/api/v2.0/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, or add ontology=emdat for its hierarchy, definitions and live coverage. Levels are local to an ontology: GICS returns sector, industry_group, industry and sub_industry; IAB returns tier_1 through tier_4. These are distinct from indexed fields such as gics_sector or iab_tier_1. Flat taxonomies can retain names such as iptc_genre or media_frame. Use the returned ontology id and level together, or copy a hierarchy node's events_url for event retrieval.

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[]

Local level names, from the top level down: sector for GICS, tier_1 for IAB, disaster_group for EM-DAT. They are not necessarily the indexed filter field names.

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_json — The request body is not JSON. Every error body, 401 included, is {error, message, status}.

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.

422validation_error — The request is well formed but the API cannot decode or validate it: an unknown body field or query parameter, a missing required parameter, a value of the wrong type, an empty and, or or not, a date that is not a calendar date (in the path, the query or the body), an unknown enum value or a reversed range. The message names the parameter and what is wrong.

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.

503api_key_metering_unavailable — API key usage metering is temporarily unavailable, so the request was not served; wait for the Retry-After header (30 seconds) and retry.

502backend_error — The World backend could not be reached or did not return a valid response; retry shortly.

504backend_timeout — The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.

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.