# Iskelesi

> Istanbul's passenger ferries as data: piers, operators, timetables, journeys between piers and where each boat is. Free, read-only, no key. An MCP server for AI agents and a JSON REST API serve the same data.

Important facts for anyone using this data:

- Boat positions are ESTIMATED from the timetable, not GPS. Each position says so (`positionSource: "estimated"` in MCP, `source: "estimated"` in REST). Never present one as live.
- Times are the operators' published timetables, not live running. Tell users to check with the operator before travelling.
- All times are Istanbul time: Europe/Istanbul (UTC+03:00 all year). MCP prints them with the +03:00 offset; REST serves ISO 8601 in UTC.
- Timetables loaded: Şehir Hatları, Turyol, Mavi Marmara, İDO. Not loaded: Dentur Avrasya, Prenstur.
- Attribution: "Kaynak: İBB Açık Veri Portalı" for piers and routes (İBB Open Data Portal), and the operator for its timetable.
- A sailing's stops belong to that sailing, not its line: Turyol's 17:00 from Eminönü goes straight to Kadıköy on weekdays and calls at Karaköy at weekends.

## MCP server

- [MCP endpoint](https://api.iskelesi.com/mcp): Streamable HTTP, stateless, no authentication. Claude Code: `claude mcp add --transport http iskelesi https://api.iskelesi.com/mcp`
- [Server card](https://api.iskelesi.com/mcp/server-card): machine-readable identity and connection details (MCP Server Card)
- [Developer documentation](https://iskelesi.com/developers): connection snippets for Claude, Claude Code, Cursor and VS Code, and the tool reference

Tools:

- `search_piers`: Find piers by name, operator, shore or nearness to a point
- `next_departures`: The next ferries from a pier, with destination, stops on the way and operator
- `plan_trip`: Direct sailings between two piers, and one-change journeys when they're quicker
- `boats_now`: Boats on the water now or at a given time, with estimated positions
- `boat_journey`: One sailing's stops and times, and where it is
- `list_operators`: Operators, their timetable pages, logos and when each was last read
- `timetable`: A whole day's departures from a pier, or sailings of a route
- `data_sources`: Where the data comes from, how fresh it is, and the attribution

Pier names are matched loosely ("kadikoy", "Kadıköy", "eminonu turyol"); a name covers every pier at that place.

## REST API

- [OpenAPI 3.1 description](https://api.iskelesi.com/openapi.json): every public endpoint with schemas and examples
- [GET /v1/network](https://api.iskelesi.com/v1/network): operators, piers and the routes today's sailings use
- [GET /v1/piers/{id}/departures](https://api.iskelesi.com/v1/piers/kadikoy/departures): the next departures from one pier
- [GET /v1/sailings?date=YYYY-MM-DD](https://api.iskelesi.com/v1/sailings): every sailing of one Istanbul day, with all its stops
- [GET /v1/vessels](https://api.iskelesi.com/v1/vessels): boats on the water now, each with its position source
- [GET /v1/health](https://api.iskelesi.com/v1/health): every data source and when it was last read

## Optional

- [Iskelesi](https://iskelesi.com): the iPhone app this data was built for
- [AI Catalog](https://api.iskelesi.com/.well-known/ai-catalog.json): domain-level discovery of the MCP server
