{"openapi":"3.1.0","info":{"title":"Iskelesi API","version":"1.0.0","summary":"Istanbul ferry piers, timetables and estimated boat positions.","description":"Read-only JSON about Istanbul's passenger ferries. No key, no sign-in. The same data is available to AI agents as an MCP server at `/mcp`.\n\n**Positions are estimates.** Times are the operators' published timetables, not live running, and boat positions are estimated from those timetables, not GPS. Check with the operator before travelling. Every vessel carries `source`: `estimated` or `live`.\n\n**Times.** Instants are ISO 8601 in UTC. Timetables are Istanbul wall-clock time (Europe/Istanbul, UTC+03:00 all year), and `date` parameters are Istanbul calendar dates.\n\n**Attribution.** Piers and routes: Kaynak: İBB Açık Veri Portalı. Timetables: each operator's own published timetable (see `timetableURL`).\n\n**Fair use.** Responses are cached for 15 seconds to 5 minutes; please honour `cache-control` rather than polling faster.","contact":{"name":"Iskelesi","url":"https://iskelesi.com/developers"}},"servers":[{"url":"https://api.iskelesi.com"}],"externalDocs":{"description":"Developer documentation and the MCP server","url":"https://iskelesi.com/developers"},"tags":[{"name":"Network"},{"name":"Sailings"},{"name":"Boats"},{"name":"Status"}],"paths":{"/v1/network":{"get":{"operationId":"getNetwork","tags":["Network"],"summary":"Operators, piers and routes","description":"Every operator (with logo, timetable page and when its timetable was last read), every pier (with its owner and who sails from it), and the routes today's sailings use. A route is one stopping pattern with a path over water.","responses":{"200":{"description":"The network","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Network"},"example":{"operators":[{"id":"turyol","name":"Turyol","website":"https://www.turyol.com","timetableURL":"https://www.turyol.com/Home/Tarifeler","logoURL":"https://api.iskelesi.com/logos/turyol.png","timetableUpdated":"2026-11-20T00:15:04.000Z"}],"piers":[{"id":"turyol-eminonu","name":"Eminönü","side":"europe","latitude":41.0177,"longitude":28.9722,"operatorID":"turyol","servedBy":["turyol"]}],"routes":[{"id":"turyol-1a2b3c4d","operatorID":"turyol","name":"Eminönü – Kadıköy Yeni","pierIDs":["turyol-eminonu","turyol-kadikoy-yeni"],"path":[[41.0177,28.9722],[41,29],[40.9927,29.0211]]}]}}}}}}},"/v1/piers/{pierID}/departures":{"get":{"operationId":"getPierDepartures","tags":["Sailings"],"summary":"Next departures from a pier","description":"Up to 40 upcoming calls at the pier that a passenger can board, soonest first, from now into tomorrow. `toPierID` is where the boat ends up and `viaPierIDs` its calls on the way. `skippedPierIDs` are piers on the way that this line usually calls at and this sailing doesn't (Turyol's weekday 17:00 from Eminönü goes straight to Kadıköy Yeni). An unknown pier returns an empty list.","parameters":[{"name":"pierID","in":"path","required":true,"description":"A pier id from `/v1/network`","schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"example":"turyol-eminonu"}],"responses":{"200":{"description":"Departures","content":{"application/json":{"schema":{"type":"object","required":["pierID","departures","generated"],"properties":{"pierID":{"type":"string"},"departures":{"type":"array","items":{"$ref":"#/components/schemas/Departure"}},"generated":{"type":"string","format":"date-time","description":"ISO 8601, UTC"}}},"example":{"pierID":"turyol-eminonu","departures":[{"id":"turyol-timetable:turyol-eminonu:17:00:turyol-kadikoy-yeni:1111100@2026-11-20#0","routeID":"turyol-1a2b3c4d","operatorID":"turyol","fromPierID":"turyol-eminonu","toPierID":"turyol-kadikoy-yeni","viaPierIDs":[],"skippedPierIDs":["turyol-karakoy"],"departs":"2026-11-20T14:00:00.000Z","arrives":"2026-11-20T14:18:00.000Z"}],"generated":"2026-11-20T13:55:00.000Z"}}}}}}},"/v1/sailings":{"get":{"operationId":"getSailings","tags":["Sailings"],"summary":"A day's sailings","description":"Every trip on the water at some point of one Istanbul day, each with all its stops: the ones that start that day and yesterday's still sailing after midnight.","parameters":[{"name":"date","in":"query","required":false,"description":"Istanbul calendar date, from yesterday to seven days ahead. Today by default.","schema":{"type":"string","format":"date"},"example":"2026-11-20"}],"responses":{"200":{"description":"Trips","content":{"application/json":{"schema":{"type":"object","required":["date","trips","generated"],"properties":{"date":{"type":"string","format":"date"},"trips":{"type":"array","items":{"$ref":"#/components/schemas/Trip"}},"generated":{"type":"string","format":"date-time","description":"ISO 8601, UTC"}}},"example":{"date":"2026-11-20","trips":[{"id":"turyol-timetable:turyol-eminonu:17:00:turyol-kadikoy-yeni:1111100@2026-11-20","routeID":"turyol-1a2b3c4d","operatorID":"turyol","stops":[{"pierID":"turyol-eminonu","arrives":null,"departs":"2026-11-20T14:00:00.000Z","boarding":true},{"pierID":"turyol-kadikoy-yeni","arrives":"2026-11-20T14:18:00.000Z","departs":null,"boarding":true}]}],"generated":"2026-11-20T13:55:00.000Z"}}}},"400":{"description":"`date` isn't YYYY-MM-DD, or is out of range","content":{"text/plain":{"schema":{"type":"string"},"example":"date out of range"}}}}}},"/v1/vessels":{"get":{"operationId":"getVessels","tags":["Boats"],"summary":"Boats on the water now","description":"Every sailing that should be under way now, placed on its route by elapsed time. `source` is `estimated` for those. A boat heard on AIS in the last five minutes replaces its estimate and has `source: \"live\"`; at present there is no live feed, so every position is an estimate. Never show an estimate as live.","responses":{"200":{"description":"Vessels","content":{"application/json":{"schema":{"type":"object","required":["vessels","generated"],"properties":{"vessels":{"type":"array","items":{"$ref":"#/components/schemas/Vessel"}},"generated":{"type":"string","format":"date-time","description":"ISO 8601, UTC"}}},"example":{"vessels":[{"id":"turyol-timetable:turyol-eminonu:17:00:turyol-kadikoy-yeni:1111100@2026-11-20","name":"Eminönü – Kadıköy Yeni","operatorID":"turyol","routeID":"turyol-1a2b3c4d","fromPierID":"turyol-eminonu","toPierID":"turyol-kadikoy-yeni","departed":"2026-11-20T14:00:00.000Z","arrives":"2026-11-20T14:18:00.000Z","latitude":41.0052,"longitude":28.9967,"heading":124.5,"source":"estimated","updated":"2026-11-20T14:09:00.000Z","stops":[{"pierID":"turyol-eminonu","arrives":null,"departs":"2026-11-20T14:00:00.000Z","boarding":true},{"pierID":"turyol-kadikoy-yeni","arrives":"2026-11-20T14:18:00.000Z","departs":null,"boarding":true}]}],"generated":"2026-11-20T14:09:00.000Z"}}}}}}},"/v1/health":{"get":{"operationId":"getHealth","tags":["Status"],"summary":"Data sources and their last run","description":"Each source the data is read from, when it last ran and last succeeded, and the last error. A failed run keeps the previous timetable.","responses":{"200":{"description":"Sources","content":{"application/json":{"schema":{"type":"object","required":["sources"],"properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}}}},"example":{"sources":[{"id":"turyol-timetable","kind":"timetable","url":"https://www.turyol.com/Home/Tarifeler","last_run_at":"2026-11-20T00:15:04.000Z","last_ok_at":"2026-11-20T00:15:04.000Z","last_error":null,"rows":515,"operator_id":"turyol"}]}}}}}}},"/logos/{operatorID}.png":{"get":{"operationId":"getOperatorLogo","tags":["Network"],"summary":"An operator's logo","parameters":[{"name":"operatorID","in":"path","required":true,"schema":{"type":"string"},"example":"turyol"}],"responses":{"200":{"description":"PNG image","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"No logo for that operator"}}}}},"components":{"schemas":{"Network":{"type":"object","required":["operators","piers","routes"],"properties":{"operators":{"type":"array","items":{"$ref":"#/components/schemas/Operator"}},"piers":{"type":"array","items":{"$ref":"#/components/schemas/Pier"}},"routes":{"type":"array","items":{"$ref":"#/components/schemas/Route"}}}},"Operator":{"type":"object","required":["id","name","website","timetableURL","logoURL","timetableUpdated"],"properties":{"id":{"type":"string","examples":["sehir-hatlari"]},"name":{"type":"string"},"website":{"type":"string","format":"uri"},"timetableURL":{"type":["string","null"],"format":"uri","description":"The operator's own timetable page"},"logoURL":{"type":["string","null"],"format":"uri"},"timetableUpdated":{"type":["string","null"],"format":"date-time","description":"The last time its timetable was read successfully. null if never"}}},"Pier":{"type":"object","required":["id","name","side","latitude","longitude","operatorID","servedBy"],"properties":{"id":{"type":"string","examples":["kadikoy"]},"name":{"type":"string","examples":["Kadıköy"]},"side":{"type":"string","enum":["europe","asia","islands"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"operatorID":{"type":["string","null"],"description":"Set for an operator's own pier (Turyol's Eminönü); null for a public one"},"servedBy":{"type":"array","items":{"type":"string"},"description":"Operators that sail from it"}}},"Route":{"type":"object","required":["id","operatorID","name","pierIDs","path"],"description":"One stopping pattern and the water it's sailed over","properties":{"id":{"type":"string"},"operatorID":{"type":"string"},"name":{"type":"string"},"pierIDs":{"type":"array","items":{"type":"string"}},"path":{"type":"array","description":"[latitude, longitude] points through every pier in `pierIDs`, in order","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"minItems":2,"maxItems":2}}}},"Stop":{"type":"object","required":["pierID","arrives","departs","boarding"],"properties":{"pierID":{"type":"string"},"arrives":{"type":["string","null"],"format":"date-time","description":"null at the first stop"},"departs":{"type":["string","null"],"format":"date-time","description":"null at the last stop"},"boarding":{"type":"boolean","description":"false where the boat calls but takes no passengers"}}},"Skip":{"type":"object","required":["pierID","after"],"description":"A pier the sailing passes without calling, though the day's usual pattern on that water calls there","properties":{"pierID":{"type":"string"},"after":{"type":"integer","description":"Index in `stops` of the call it comes after"}}},"Trip":{"type":"object","required":["id","routeID","operatorID","stops","usualRouteID","skips"],"description":"One boat's scheduled journey on one day","properties":{"id":{"type":"string"},"routeID":{"type":"string"},"operatorID":{"type":"string"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/Stop"}},"usualRouteID":{"type":["string","null"],"description":"The day's most-sailed pattern this sailing leaves piers out of; null when it runs the usual way"},"skips":{"type":"array","items":{"$ref":"#/components/schemas/Skip"},"description":"The piers it leaves out, in sailing order"}}},"Departure":{"type":"object","required":["id","routeID","operatorID","fromPierID","toPierID","viaPierIDs","skippedPierIDs","departs","arrives"],"properties":{"id":{"type":"string"},"routeID":{"type":"string"},"operatorID":{"type":"string"},"fromPierID":{"type":"string"},"toPierID":{"type":"string","description":"Where the boat ends up"},"viaPierIDs":{"type":"array","items":{"type":"string"},"description":"Its calls on the way"},"skippedPierIDs":{"type":"array","items":{"type":"string"},"description":"Piers on the way its line usually calls at and this sailing doesn't"},"departs":{"type":"string","format":"date-time","description":"ISO 8601, UTC"},"arrives":{"type":"string","format":"date-time","description":"Arrival at `toPierID`"}}},"Vessel":{"type":"object","required":["id","name","operatorID","routeID","fromPierID","toPierID","departed","arrives","latitude","longitude","heading","source","updated","stops","usualRouteID","skips"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"operatorID":{"type":"string"},"routeID":{"type":["string","null"]},"fromPierID":{"type":["string","null"],"description":"The pier it last left"},"toPierID":{"type":["string","null"],"description":"Its next stop"},"departed":{"type":["string","null"],"format":"date-time","description":"ISO 8601, UTC"},"arrives":{"type":["string","null"],"format":"date-time","description":"ISO 8601, UTC"},"latitude":{"type":"number"},"longitude":{"type":"number"},"heading":{"type":["number","null"],"description":"Degrees clockwise from north"},"source":{"type":"string","enum":["estimated","live"],"description":"`estimated`: worked out from the timetable, not observed. `live`: an AIS fix under 5 minutes old"},"updated":{"type":"string","format":"date-time","description":"ISO 8601, UTC"},"stops":{"type":"array","items":{"$ref":"#/components/schemas/Stop"},"description":"Its whole journey"},"usualRouteID":{"type":["string","null"],"description":"As on Trip"},"skips":{"type":"array","items":{"$ref":"#/components/schemas/Skip"},"description":"As on Trip"}}},"Source":{"type":"object","required":["id","kind","url"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["live","timetable","geodata"]},"url":{"type":"string"},"last_run_at":{"type":["string","null"],"format":"date-time","description":"ISO 8601, UTC"},"last_ok_at":{"type":["string","null"],"format":"date-time","description":"ISO 8601, UTC"},"last_error":{"type":["string","null"]},"rows":{"type":["integer","null"]},"operator_id":{"type":["string","null"]}}}}}}