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. Route search uses Overpass to find relation IDs by route metadata.

GET/api/search?q=TEXT&mode=TYPE

Search worldwide for public transport route and route_master relations. Required q is 2–100 characters. Route numbers (ref) match exactly; names, termini, operators and networks match literal substrings, case-insensitively. Optional mode filters by a supported transport type.

Optional south, west, north and east coordinates restrict the search to routes with mapped members within a bounding box, including their parent route masters. All four coordinates are required together. Routes may extend outside the box. Bounds must be finite and ordered, span at most 20 degrees in either direction, and must not cross the date line.

Returns {"routes": [...], "truncated": false}. Each result has id, name, ref, from, to, operator, network, route (transport type) and type (relation type). At most 50 results are returned; truncated indicates more matches. No matches returns an empty list. Invalid input returns 400 invalid_query; upstream failures return 502 osm_error.

GET /api/search?q=M11&mode=subway

GET /api/search?q=24&mode=bus&south=51.39&west=-2.73&north=51.55&east=-2.51

GET/api/locations?q=PLACE

Find up to five candidate places using Nominatim. Required q is 2–100 characters. Returns {"locations": [{"label": "...", "bounds": [south, west, north, east]}]}. An empty list means no matching location. Invalid input returns 400 invalid_query; upstream failures return 502 osm_error. Location lookups are submitted explicitly, cached and limited to one upstream request per second per application process.

GET /api/locations?q=Bristol%2C+UK

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