API Documentation

JSON API for fetching OSM public transport routes as GeoJSON.

All endpoints are read-only and require no authentication. Data is fetched live from the OSM API v0.6. Relation IDs can be found on openstreetmap.org — search for a route and click through to its relation page.

All error responses return JSON with at least error (machine-readable code) and message (human-readable description) fields.

GET /api/route/<relation_id>

Returns the full route as a GeoJSON FeatureCollection, the ordered list of stops, and links to sibling routes in the same route_master (if any).

Path parameters

Parameter	Type	Description
relation_id	integer	OSM relation ID of a public transport route.

Success response 200 OK

{
  "name": "M11: Arnavutköy Hastane → Gayrettepe",
  "ref": "M11",
  "stops": [
    { "name": "Arnavutköy Hastane", "lat": 41.1234, "lon": 28.7654 },
    { "name": "İstanbul Havalimanı", "lat": 41.2701, "lon": 28.7519 },
    ...
  ],
  "geojson": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": { "type": "LineString", "coordinates": [[28.765, 41.123], ...] },
        "properties": { "name": "M11: Arnavutköy Hastane → Gayrettepe",
                        "ref": "M11", "from": "Arnavutköy Hastane",
                        "to": "Gayrettepe", "route": "subway" }
      },
      {
        "type": "Feature",
        "geometry": { "type": "Point", "coordinates": [28.765, 41.123] },
        "properties": { "name": "Arnavutköy Hastane" }
      },
      ...
    ]
  },
  "other_directions": [
    { "id": 15083964, "name": "M11: Gayrettepe → Arnavutköy Hastane", "ref": "M11" }
  ]
}

The geojson field is a FeatureCollection containing one LineString for the route geometry followed by one Point per stop. The LineString carries the route tags as properties (name, ref, from, to, route). Each Point has a name property.

other_directions lists sibling routes from the same route_master relation. It is an empty array if the route has no parent route_master.

Error responses

Status	error	When
404	osm_error	Relation not found on OpenStreetMap.
422	is_route_master	Relation is a route_master. Use /api/route_master/<id> instead.
422	not_public_transport	Relation exists but is not a supported public transport route.
502	osm_error	OSM API returned an unexpected error.

Example

GET /api/route/15083963

GET /api/segment/<relation_id>

Returns a GeoJSON FeatureCollection for the portion of the route between two named stops. Stops are matched case-insensitively.

Path parameters

Parameter	Type	Description
relation_id	integer	OSM relation ID of a public transport route.

Query parameters

Parameter	Required	Description
from	Yes	Name of the start stop (case-insensitive).
to	Yes	Name of the end stop (case-insensitive).
stops	No	Include stop Point features. 1 (default) to include, 0 to omit.

Success response 200 OK

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "LineString", "coordinates": [[28.800, 41.259], ...] },
      "properties": { "name": "M11: Arnavutköy Hastane → Gayrettepe",
                      "ref": "M11", "from": "Arnavutköy Hastane",
                      "to": "Gayrettepe", "route": "subway" }
    },
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [28.800, 41.259] },
      "properties": { "name": "İstanbul Havalimanı" }
    },
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [28.820, 41.247] },
      "properties": { "name": "Hasdal" }
    }
  ]
}

The LineString is trimmed to the shortest path between the two stops along the route geometry. The from stop is treated as the start regardless of the order the names are supplied — the segment always follows the route direction.

Error responses

Status	error	When
400	missing_params	from or to parameter is absent.
404	osm_error	Relation not found on OpenStreetMap.
404	station_not_found	One or both stop names were not found. The response includes an available array listing valid stop names.
422	not_public_transport	Relation is not a supported public transport route.
502	osm_error	OSM API returned an unexpected error.

Example

GET /api/segment/15083963?from=İstanbul+Havalimanı&to=Hasdal

GET /api/segment/15083963?from=İstanbul+Havalimanı&to=Hasdal&stops=0

GET /api/route_master/<relation_id>

Returns all member routes of an OSM route_master relation, each with its GeoJSON geometry (stops omitted). Use this to display all directions of a line on a map.

Path parameters

Parameter	Type	Description
relation_id	integer	OSM relation ID of a route_master relation.

Success response 200 OK

{
  "name": "M11",
  "ref": "M11",
  "routes": [
    {
      "id": 15083963,
      "name": "M11: Arnavutköy Hastane → Gayrettepe",
      "ref": "M11",
      "from": "Arnavutköy Hastane",
      "to": "Gayrettepe",
      "geojson": {
        "type": "FeatureCollection",
        "features": [
          {
            "type": "Feature",
            "geometry": { "type": "LineString", "coordinates": [[28.765, 41.123], ...] },
            "properties": { "name": "M11: Arnavutköy Hastane → Gayrettepe", ... }
          }
        ]
      }
    },
    {
      "id": 15083964,
      "name": "M11: Gayrettepe → Arnavutköy Hastane",
      "ref": "M11",
      "from": "Gayrettepe",
      "to": "Arnavutköy Hastane",
      "geojson": { ... }
    }
  ]
}

Each entry in routes contains the individual route's id, name, ref, from, to tags, and a geojson FeatureCollection with only the LineString geometry (no stop points). If a member route cannot be fetched, it is included with "geojson": null.

Error responses

Status	error	When
404	osm_error	Relation not found on OpenStreetMap.
422	osm_error	Relation exists but is not a route_master.
502	osm_error	OSM API returned an unexpected error.

Example

GET /api/route_master/15083966

Supported route types

The following OSM route tag values are accepted:

bus   ferry   funicular   light_rail   monorail   subway   train   tram   trolleybus