Capabilities

events.list

List stored events

Returns stored events, newest first. Filters are combinable: `type` restricts to one catalog type, `located` keeps only events whose position is known, and `limit` caps the number of rows. Events whose position could not be resolved are returned like any other — they simply carry no coordinates.

events.get

Fetch one event

Returns one event by its database id or by the source's own `external_id`. Both are accepted because the two identities answer different questions: the database id is ours, the external id is the source's and is what makes the import idempotent.

events.near

Events within a radius of a point

The spatial query proper. Answers "what happened within X km of here" using PostGIS `ST_DWithin` on the geography column, which measures on the spheroid in metres and is answered from the GiST index rather than by scanning the table. Every returned event also carries its `distance_m`, computed by `ST_Distance` in the same query.

events.stats

Counts by type and by geocoding status

The shape of the stored data at a glance: how many events of each catalog type, and how many positions are known, unknown, not found or failed. This is the number the operator looks at after an import.

No parameters.

catalog.event_types

The declared event types

The canonical vocabulary of event types, with the label and map colour each one is drawn with. Every other surface reads this list rather than keeping its own copy, which is why a new type appears in the filter, the map legend and the API documentation at once.

No parameters.

catalog.geocoding_statuses

The declared geocoding statuses

Every state a position can be in, and whether that state means the coordinates are known. The schema enforces the pairing: a status that claims coordinates exist cannot be stored without a point, and one that claims they do not cannot be stored with one.

No parameters.

geocoding.lookup

Resolve a place name

Forward geocoding through the configured geocoder, without storing anything. The answer carries `candidates` — how many places the geocoder found plausible — and `confidence`, its ranking score for the one returned, so an ambiguous name is visibly ambiguous. A place the geocoder does not know is `not_found`, which is an answer, not a failure. A geocoder that cannot be reached is an `error`.

geocoding.status

Health of the geocoder

Asks the configured geocoder whether it is up and which adapter is in use. Returns a reason instead of raising when it is not, so this is safe to call from a status page or a monitor.

No parameters.

ingest.import

Import the dataset

Runs the ingest pipeline over a JSON dataset: normalise, upsert on `external_id`, geocode what needs geocoding, store the outcome. Running it twice is safe and is the point: the second run updates the same rows and reuses positions that are already resolved, so the report shows updates and reuses rather than inserts. Pass `regeocode` to resolve positions again anyway.

system.capabilities

The registry itself

Lists every capability with its parameters, its route, its CLI form and its MCP tool name. This is the registry describing itself: the same list that generated the routes, the OpenAPI document and the documentation is readable at run time.

No parameters.

system.health

Health of the system

One call that answers whether the parts are there: the database, the PostGIS extension and its version, the number of stored events and whether the geocoder answers.

No parameters.