{ "swagger": "2.0", "schemes": ["https"], "securityDefinitions": { "HeaderTokenAuth": { "in": "header", "name": "Authorization", "type": "apiKey" }, "QueryTokenAuth": { "in": "query", "name": "key", "type": "apiKey" } }, "basePath": "/routing/v1", "host": "api.geops.io", "info": { "description": "API for finding a route geometry for a given mode of transport between two or more stops (railway station or bus stop, etc.) or points. The API is optimized for public transport (rail, bus, tram etc.) and pedestrian routing between or inside stations/stops/platforms. The Routing API is unaware of any public transport schedules and serves a likely route for a single vehicle/person in the infrastructure network for each request.\n", "title": "Routing API", "version": "0.0.1" }, "paths": { "/": { "get": { "description": "Returns a route as a GeoJSON `FeatureCollection`. For public transport routing, each GeoJSON `Feature` corresponds to a leg between two stops/points. For pedestrian routing, each feature corresponds to an edge or a partial edge in the routing graph where edges are interrupted at each input stop/point. What makes up an edge is an implementation detail. Levels are always constant along a feature for pedestrian routing but multiple features can be returned although the level does not change between them.\n\nThe different output models for public transport routing and pedestrian routing are due to backward compatibility. We aim to consolidate the output models in a future version of the API (with breaking changes).\n\nNote: The output is not a valid GeoJSON `FeatureCollection` according to the standard since it contains a `properties` key. This will be also addressed in a future version.\n", "parameters": [ { "name": "via", "in": "query", "required": true, "type": "string", "description": "A pipe separated list of stops or points to visit in the given order. A stop (railway station or bus stop, etc.) can be given as\n - a name like `Basel SBB` or `Bern, Bahnhof`\n - an ID prefixed with `!` like `!8507000` or `!FRBR` or `!de:08311:6508`\n or `!ch:1:sloid:7000` or `!7e7dbbe3be4bc3a6`\n - latitude and longitude (WGS84/EPSG:4326) prefixed with `@` like\n `@47.99770,7.84117` (snapped to the closest stop)\n\n\nA point can be given by latitude and longitude (WGS84/EPSG:4326) without any prefix like `47.99770,7.84117`. Points will be snapped to a suitable edge in the routing graph.\n\nA stop point (platform/track) can be specified by appending a platform code separated by `$` to the stop like `Basel SBB$6` or `!8507000$49` or `@46.948105,7.440209$D` and so on. DHIDs and SLOIDs are currently truncated at the level of \"Haltestelle\" (DHID) or \"Location\" (SLOID) for all modes of transport. Platform codes are currently ignored for pedestrian routing.\n\nStop names do not need to match exactly the names in the database that is used for routing. The correct names are searched for by simple normalization, by lookup of synonyms or abbreviations as well as fuzzy algorithms.\n\nThe usage of different schemes of IDs used by the transit agencies is handled to a large part. A stop can be found by all IDs known to us. E.g. the station Basel Bad Bf can be found with the ID 8500090 that is used by Swiss Federal Railways SBB and by 8000026, the number used by German Railways DB. The usage of numbers used by the UIC is supported for many stations. We also support german DHIDs and swiss SLOIDs. On top of that, geOps stop UIDs from our [Stops API](https://developer.geops.io/apis/stops) can also be used. If you need an additional numbering scheme please contact us.\n\nExample for a valid via with two legs between three stops from Freiburg (Breisgau) Hbf via Basel SBB to Bern:\n - `!8000107|basel sbb|Bern`\n" }, { "name": "levels", "in": "query", "required": false, "type": "string", "allowEmptyValue": true, "description": "A pipe separated list of levels for pedestrian routing. Empty strings can be used if a level is unknown. The number of items in the list has to be either zero (empty string) or match the number of items in the `via` parameter. An empty string/list means that all levels are unknown.\n\nExamples:\n - `1|-1|0`: level 1 for first via item, level -1 for second via item,\n level 0 for third via item\n - `1|2||0|`: level 1 for first via item, level 2 for second via item,\n unknown level for third via item, level 0 for fourth via item, unknown\n level for fifth via item\n - `|-2`: unknown level for first via item, level -2 for second via item\n\n\nThe parameter is ignored for public transport routing.\n" }, { "name": "mot", "in": "query", "required": true, "type": "string", "enum": [ "rail", "subway", "tram", "bus", "coach", "gondola", "funicular", "ferry", "foot" ], "description": "Mode of transport. `foot` selects pedestrian routing. Everything else selects public transport routing.\n" }, { "name": "graph", "in": "query", "required": false, "allowEmptyValue": true, "default": "osm", "type": "string", "enum": ["osm", "gen1", "gen2", "gen3", "gen4", ""], "description": "The graph used for routing. Useful for obtaining different route geometries that match on different maps or zoom levels of our [Maps API](https://developer.geops.io/apis/maps). The default is `osm` which means the detailed network based on OpenStreetMap and is available for all modes of transport. `gen1` to `gen4` provide networks with increasing levels of generalization. They are available for the following modes of transport:\n - `gen1`: `rail, subway, tram, gondola, funicular`\n - `gen2`: `rail`\n - `gen3`: `rail`\n - `gen4`: `rail`\n\nThe empty string is equivalent to not setting the parameter and will default to `osm`.\n" }, { "name": "line", "in": "query", "required": false, "allowEmptyValue": true, "type": "string", "description": "A line name like `S1` or `RE 7` that should be preferred for public transport routing. Edges in the network that are not used by this line according to OpenStreetMap data receive a penalty in the shortest path search. Normalization and fuzzy string matching is used to compare the input to line names from OpenStreetMap.\n\nThis parameter is ignored for generalized graphs and for pedestrian routing.\n" }, { "name": "line-from", "in": "query", "required": false, "allowEmptyValue": true, "type": "string", "description": "When using the `line` parameter, `line-from` can be used to prefer a specific branch of the given line by providing the name of the origin stop. Edges in the network that are not used by the line with the given origin according to OpenStreetMap data receive a penalty in the shortest path search. Normalization and fuzzy string matching is used to compare the input to origin names from OpenStreetMap.\n" }, { "name": "line-to", "in": "query", "required": false, "allowEmptyValue": true, "type": "string", "description": "Same as `line-from` but for the destination stop of the line branch.\n" }, { "name": "simplify", "in": "query", "required": false, "default": 0.5, "type": "number", "format": "double", "description": "Tolerance parameter in web mercator units for Douglas-Peucker simplification of output geometries.\n" }, { "name": "max-skip-hop-ratio", "in": "query", "required": false, "default": 0.5, "type": "number", "format": "double", "description": "Maximum allowed ratio of input stops/points to skip if not found. The first and last stop/point can never be skipped and does not count in the ratio numerator and denominator. Note that the number of output features will be reduced accordingly if stops/points are skipped.\n" }, { "name": "hops", "in": "query", "required": false, "default": false, "type": "boolean", "description": "Whether to split the output features at stops along the route even when they were not part of the input in `via`. Ignored for pedestrian routing.\n" }, { "name": "beeline-fallback", "in": "query", "required": false, "default": true, "type": "boolean", "description": "Whether to use beelines (straight lines) as a fallback for public transport routing.\n\nWhen enabled, it works as follows:\n\nEach routing request is processed in two steps: First, all stop definitions passed in the `via` parameter are resolved into known stops for the specified mode of transport. Then these stops are passed to a routing backend to compute the route between the input stops and points.\n\nIf a stop definition could not be resolved in the first step, resolving the stop definition is attempted a second time but without a specific mode of tranpsort. When this is not possible, the request will fail at this point.\n\nOtherwise, the stops will be sent to the routing backend. The routing backend will replace portions of the route between consecutive stops by beelines, if the stops are in different connected components of the routing graph for the given mode of transport.\n\nThe routing backend might still be unable to find a route at all, e.g. when a stop was looked up allowing all modes of transport in the first step or when a route is not possible due to restrictions inside the same connected component of the routing graph. In this case, the whole route will be replaced by beelines between coordinates of the stops.\n\nWhen using `resolve-hops=false`, the first step is bypassed. In this case, a failure from the routing backend will always lead to a failing request.\n\nThe parameter is ignored for pedestrian routing which always uses a backend-side beeline fallback.\n" }, { "name": "coord-radius", "in": "query", "required": false, "default": -1, "type": "number", "format": "double", "maximum": 500, "description": "Search radius for candidate edges for projecting points to the routing graph in public transport routing. A negative value (the default) means picking a suitable radius that depends on the given mode of transport. The shortest path between all combinations of different projected points of the different `via` items is picked. The distance to travel from the input points to the respective projected points on the candidate edges in the network is also accounted for (see `coord-punish` parameter).\n\nNote that this is specifically for pure point inputs (`via` items without `@` prefix) and it has nothing to do with via stops referenced by coordinates.\n\nThe parameter is ignored for pedestrian routing which always uses only the nearest edge for projecting and does not try different candidate edges.\n" }, { "name": "coord-punish", "in": "query", "required": false, "default": -1, "type": "number", "format": "double", "maximum": 100000, "description": "When selecting between multiple candidates for projected points (see `coord-radius`), the cost for traveling from the input point to the respective projected point is proportional to `coord-punish`. Therefore large values will prefer snapping to near edges and small values will prefer short routes in the network (measured from the projected point(s)).\n\nA negative value (the default) will apply a punishment that is equivalent to using a straight edge from the input point to the projected point with the slowest edge category of the graph for the given mode of transport.\n\nThe parameter is ignored for pedestrian routing (see `coord-radius`).\n" }, { "name": "atlas", "in": "query", "required": false, "default": false, "type": "boolean", "description": "When enabled, every item in the `via` parameter must be a SLOID (Swiss Location ID) in the `!{sloid}` syntax (e.g. `!ch:1:sloid:7000:1:5`). Only supported with `mot=foot` or a public-transport mot.\nEach SLOID is looked up in our atlas dataset. For `mot=foot` a hit is routed directly from the atlas coordinates. For public transport the stop is resolved to a geOps stop UID and routed by public transport, falling back to the atlas coordinates when the exact stop or platform is unknown; pass `coord-fallback=false` to opt out of that fallback. SLOIDs that are not found in the atlas are resolved like a normal stop id.\nFor every response station that came from one of these SLOIDs, the station `id` is set to the SLOID and `ident_source` to `\"query\"` (indicating the `id` came from your request input). Foot responses additionally get a synthesised `station_from` / `station_to` with the SLOID `id`, `ident_source` and `latitude` / `longitude`. Defaults to `false`.\n" }, { "name": "resolve-hops", "in": "query", "required": false, "default": true, "type": "boolean", "description": "Whether to resolve stops in the `via` parameter to geOps stop UIDs using our [Stops API](https://developer.geops.io/apis/stops) for public transport routing. If disabled, the only supported IDs are geOps stop UIDs. So if you already have geOps stop UIDs at hand (for example if you resolve user input using our [Stops API](https://developer.geops.io/apis/stops) in your application, you can use `resolve-hops=false` to get slightly better latency.\n\nAnother use case for `resolve-hops=false` is map matching of stops that are referenced by coordinates (with `@` prefix, see `via` parameter): By default, only the nearest stop of the selected mode of transport is picked within a radius of 10 kilometers. When using `resolve-hops=false`, multiple candidate stops of the given mode of transport are considered for each input within a significantly smaller radius suitable for the given mode of transport and the shortest path between all combinations of all candidates for different stops is computed (similar to routing by pure points). This is the best option for routing when no reliable IDs are available.\n\nDisabling this option is ignored for pedestrian routing. For pedestrian routing, stops are always resolved.\n\nThe value of the parameter has no effect on pure points (without `@` prefix).\n" }, { "name": "coord-fallback", "in": "query", "required": false, "default": false, "type": "boolean", "description": "When map matching stops that are referenced by coordinates in public transport routing (see `resolve-hops` parameter), enabling `coord-fallback` will employ a fallback to a pure point if an input stop has zero candidates in the network.\n\nThe parameter is ignored for pedestrian routing.\n" }, { "name": "elevation", "in": "query", "required": false, "default": false, "type": "boolean", "description": "Whether to decorate the route with SRTM elevation data. If enabled, elevation data is stored in the z-component of the GeoJSON geometries. Units are meters above EPSG:4326 reference ellipsoid. Elevation data is not available everywhere. Missing data has elevation 0 by default. This fallback can be controlled using the `elevation_fallback` parameter.\n" }, { "name": "elevation_fallback", "in": "query", "required": false, "default": 0, "type": "number", "format": "double", "description": "Fallback elevation value for missing data when `elevation` is enabled.\n" }, { "name": "length", "in": "query", "required": false, "default": false, "type": "boolean", "description": "Whether to decorate the route with distance travelled at each vertex. The individual length of each feature is stored in the `line_length` feature property and the cumulative segment lengths at the vertices are stored in the `vertex_distances` feature property.\n\nIn other words: `vertex_distances[i]` is the distance traveled along all `LineString`s from vertex `0` of the first feature to vertex `i` of the current feature.\n\nThe distance between the last vertex of the previous feature and the first vertex of the current feature is also taken into account in case there is a gap between consecutive features for some reason. Values are in meters and rounded to 2 decimal places.\n\nEarth curvature is taken into accout using the EPSG:4326 reference ellipsoid.\n\nElevation differences are taken into account if present (see `elevation`). Note that noise in the elevation data can deteriorate the results.\n\nDistances from input points to points projected onto the network of the selected mode of transport are not accounted for.\n" }, { "name": "travel-time", "in": "query", "required": false, "default": false, "type": "boolean", "description": "Whether to decorate the route with travel time properties. The constant speed can be set with the `travel-time-speed` parameter. Travel times are calculated based on length calculations (see `length` parameter). Enabling `travel-time` automatically enables `length`. The penalty for changing levels can be set with the `travel-time-floor-change-penalty` parameter.\n\nEach feature will have its travel time written to the `travel_time` property (in seconds). The total travel time is available in the `travel_time` property of the feature collection.\n\nNote: Travel times are currently only intended for pedestrian routing where the assumption of a constant speed makes sense.\n" }, { "name": "travel-time-speed", "in": "query", "required": false, "default": 1.1, "type": "number", "format": "double", "description": "Constant travel speed in meters per second for travel time calculation (see `travel-time` parameter).\n" }, { "name": "travel-time-floor-change-penalty", "in": "query", "required": false, "default": 30, "type": "integer", "format": "int32", "description": "The penalty in seconds per floor level change for travel time calculation ( see `travel-time` parameter).\n" }, { "name": "only-stations", "in": "query", "required": false, "default": true, "type": "boolean", "description": "In our stations database which the [Stops API](https://developer.geops.io/apis/stops) is based upon, some entries are marked as not being a true stop/station (for example if the data source is not reliable or it cannot be used by regular passengers). By default, such entries are ignored. By disabling `only-stations`, those entries will also be considered when resolving stops.\n" }, { "name": "prefagencies", "in": "query", "required": false, "allowEmptyValue": true, "type": "string", "description": "If not empty, this parameter is forwarded to the [Stops API](https://developer.geops.io/apis/stops) when resolving stops.\n" } ], "produces": ["application/json"], "responses": { "200": { "description": "A successful response.", "schema": { "type": "object", "required": ["type", "features", "properties"], "properties": { "type": { "type": "string", "enum": ["FeatureCollection"] }, "features": { "type": "array", "items": { "type": "object", "required": ["geometry", "properties", "type"], "properties": { "geometry": { "type": "object", "required": ["type", "coordinates"], "properties": { "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "number" }, "maxItems": 3, "minItems": 2 }, "example": [ [7.8958421, 47.9816362], [7.9048287, 47.9796056] ] }, "type": { "type": "string", "enum": ["LineString"] } } }, "properties": { "type": "object", "properties": { "beeline": { "type": "boolean", "description": "Whether this feature is a beeline fallback. Only available for public transport routing. Missing for pedestrian routing. For pedestrian routing, beelines can be identified by the `network` feature property.\n" }, "lines": { "type": "array", "items": { "type": "object", "required": ["name", "prob"], "description": "Line probabilities for this feature.\nOnly available for public transport routing. Missing for pedestrian routing.\n", "properties": { "name": { "example": "ICE", "type": "string" }, "prob": { "example": 0.99, "type": "number" } } } }, "station_from": { "type": "object", "description": "The stop at the start of the feature (if the feature starts at a stop).\n", "properties": { "id": { "description": "Requested stop ID.", "example": "8507000", "type": "string" }, "routed_id": { "description": "Actual geOps stop UID from the routing result.\n", "example": "7e7dbbe3be4bc3a6", "type": "string" }, "ident_source": { "description": "The `ident_source` from the [Stops API](https://developer.geops.io/apis/stops) response used to resolve the stop.\n", "example": "sbb", "type": "string" }, "name": { "description": "Stop name (for `resolve-hops=false`, this is the normalized name from the routing backend).\n", "example": "Bern", "type": "string" }, "platform": { "example": "1", "type": "string", "description": "The platform code of the platform/track." }, "latitude": { "type": "number", "description": "Latitude of the stop, in EPSG:4326" }, "longitude": { "type": "number", "description": "Longitude of the stop, in EPSG:4326" } } }, "station_to": { "type": "object", "description": "The stop at the end of the feature (if the feature ends at a stop).\n", "properties": { "id": { "description": "Requested stop ID.", "example": "8507000", "type": "string" }, "routed_id": { "description": "Actual geOps stop UID from the routing result.\n", "example": "7e7dbbe3be4bc3a6", "type": "string" }, "ident_source": { "description": "The `ident_source` from the [Stops API](https://developer.geops.io/apis/stops) response used to resolve the stop.\n", "example": "sbb", "type": "string" }, "name": { "description": "Stop name (for `resolve-hops=false`, this is the normalized name from the routing backend).\n", "example": "Bern", "type": "string" }, "platform": { "example": "1", "type": "string", "description": "The platform code of the platform/track." }, "latitude": { "type": "number", "description": "Latitude of the stop, in EPSG:4326" }, "longitude": { "type": "number", "description": "Longitude of the stop, in EPSG:4326" } } }, "node_from": { "type": "object", "description": "The node in the routing graph at the start of the feature.\nOnly available for public transport routing. Missing for pedestrian routing.\n", "properties": { "edge_fraction": { "type": "number", "minimum": 0, "maximum": 1, "description": "The fraction of the projected point on the starting edge.\n" }, "external_id": { "type": "string", "example": "2b126830-bc98-4b24-b0f1-175fe67795dc", "description": "A stable node ID. Only available for generalized graphs.\n" }, "id": { "type": "string", "example": "0x7f57e47eb170", "description": "An ID for the node that depends on the backend instance that processed the request. Comparing those IDs between different responses does not make sense.\n" }, "is_via": { "type": "boolean", "description": "Whether the start of the feature is at a requested stop/point (see `hops` query parameter).\n" }, "via_index": { "type": "integer", "minimum": 0, "description": "The index into the `via` list if the start of the feature is at a requested stop/point. Null otherwise." } } }, "node_to": { "type": "object", "description": "The node in the routing graph at the end of the feature.\nOnly available for public transport routing. Missing for pedestrian routing.\n", "properties": { "edge_fraction": { "type": "number", "minimum": 0, "maximum": 1, "description": "The fraction of the projected point on the final edge.\n" }, "external_id": { "type": "string", "example": "2b126830-bc98-4b24-b0f1-175fe67795dc", "description": "A stable node ID. Only available for generalized graphs.\n" }, "id": { "type": "string", "example": "0x7f57e47eb170", "description": "An ID for the node that depends on the backend instance that processed the request. Comparing those IDs between different responses does not make sense.\n" }, "is_via": { "type": "boolean", "description": "Whether the end of the feature is at a requested stop/point (see `hops` query parameter).\n" }, "via_index": { "type": "integer", "minimum": 0, "description": "The index into the `via` list if the end of the feature is at a requested stop/point. Null otherwise." } } }, "line_length": { "description": "Length of the LineString in meters. See `length` query parameter.\n", "example": 707.85, "type": "number" }, "vertex_distances": { "type": "array", "description": "Total distance travelled at LineString vertices in meters. See `length` query parameter.\n", "example": [0, 707.85], "items": { "type": "number" } }, "travel_time": { "type": "integer", "description": "Travel time of this feature in seconds (see `travle-time` query parameter).\n" }, "floor": { "type": "string", "example": "-1.0", "description": "The level of a pedestrian routing feature as a string. Note that levels are internally represented as floats in the pedestrian routing backend. The string is a representation of this float rounded to 1 digit.\nOnly available for pedestrian routing. Missing for public transport routing.\n" }, "type": { "type": "string", "enum": ["line_hpedestrian"], "example": "line_hpedestrian", "description": "The edge type of a pedestrian routing feature.\nOnly available for pedestrian routing. Missing for public transport routing.\n" }, "network": { "type": "string", "enum": ["beeline-fallback"], "description": "Indicator for beeline-fallback for pedestrian routing.\n\nUsually, this property is missing. If it is set, the only possible value is `beeline-fallback` indicating that this pedestrian feature is a beeline.\n\nAlways missing for public transport routing.\n" }, "src": { "type": "array", "description": "The coordinates of the source node of the pedestrian routing feature.\n\nCoordinates are longitude, latitude in EPSG:4326.\n\nOnly available for pedestrian routing. Missing for public transport routing.\n", "minItems": 2, "maxItems": 2, "example": [9.18155, 48.78692], "items": { "type": "number" } }, "trg": { "type": "array", "description": "The coordinates of the target node of the pedestrian routing feature.\n\nCoordinates are longitude, latitude in EPSG:4326.\n\nOnly available for pedestrian routing. Missing for public transport routing.\n", "minItems": 2, "maxItems": 2, "example": [9.18155, 48.78692], "items": { "type": "number" } } } }, "type": { "type": "string", "enum": ["Feature"] } } } }, "properties": { "type": "object", "required": ["network"], "properties": { "lines": { "type": "array", "description": "Total line probabilities.\nOnly available for public transport routing. Missing for pedestrian routing.\n", "items": { "type": "object", "required": ["name", "prob"], "properties": { "name": { "example": "ICE", "type": "string" }, "prob": { "type": "number", "example": 0.99 } } } }, "network": { "type": "string", "description": "Graph used for routing (internal identifier not compatible with `graph` in query parameter).\n", "example": "osm-eu-rail" }, "skippedVias": { "type": "array", "description": "Via items that have been skipped (see `max-skip-hop-ratio` query parameter).\nOnly available for public transport routing. Missing for pedestrian routing.\n", "items": { "type": "string", "description": "The via item that was skipped." } }, "travel_time": { "type": "integer", "description": "Total travel time in seconds (see `travle-time` query parameter).\n" } } } } } }, "400": { "description": "Bad request. The request could not be understood.", "schema": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string", "description": "Error message." } } } }, "404": { "description": "Not found. The request was valid but no route was found.", "schema": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string", "description": "Error message." } } } } }, "security": [ { "QueryTokenAuth": [] }, { "HeaderTokenAuth": [] } ] } } } }