# Waterfalls

> Explore thousands of waterfalls worldwide — by height, type, and country. Sourced and kept in sync from Wikipedia.

This site is agent-friendly: the full dataset is queryable by any attribute via a public JSON API (no API key) and an MCP server. Data is sourced from Wikipedia (CC BY-SA).

## Data
- 554 waterfalls across 69 countries.

## API (no key, rate-limited per IP)
- Search waterfalls by any attribute: `GET http://waterfalls.tello.app/api/v1/locations?<filters>`
- A single waterfall: `GET http://waterfalls.tello.app/api/v1/locations/{slug}`
- Countries with counts: `GET http://waterfalls.tello.app/api/v1/countries`
- Machine-readable filter schema (every queryable attribute): `GET http://waterfalls.tello.app/api/v1/schema`
- OpenAPI 3 spec: `GET http://waterfalls.tello.app/openapi.json`

## MCP server
- Endpoint: `http://waterfalls.tello.app/mcp` (Streamable HTTP).
- Tools: `search`, `get`, `list_countries`, `describe_filters`.

## Queryable attributes
- `search` — Name search
- `country` — Country
- `height_m` — Height (range: `height_m_min`, `height_m_max` m)
- `type` — Type (one of: Plunge, Cascade, Tiered, Block, Horsetail, Fan, Cataract, Chute, Punchbowl, Segmented)
- `num_drops` — Number of drops (range: `num_drops_min`, `num_drops_max`)
- `watercourse` — River / watercourse
- `has_image` — Has photo (1 / true)
- `has_coordinates` — Has coordinates (1 / true)
- `sort` — one of: height_desc, name, newest

## Examples
- Find waterfalls in Norway → `GET http://waterfalls.tello.app/api/v1/locations?country=norway`
- waterfalls of type "Plunge" → `GET http://waterfalls.tello.app/api/v1/locations?type=Plunge`
- waterfalls with Height over 100 m → `GET http://waterfalls.tello.app/api/v1/locations?height_m_min=100`

## Per-entry Markdown
Append `.md` to any waterfall URL (e.g. `http://waterfalls.tello.app/location/<slug>.md`), or send `Accept: text/markdown`, to get clean Markdown instead of HTML.