diff --git a/CHANGELOG.md b/CHANGELOG.md index 2745696f0..23b7f171f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,12 @@ - API: - new parameter `annotate` for `route` and `match` requests. Returns additional data about each coordinate along the selected/matched route line. + - Introducing Intersections for Route Steps. This breaks the API format in multiple ways. + - `bearing_before`/`bearing_after` are no longer supplied with a StepManeuver + - `exit` is no longer supplied for turns other than roundabouts + - `location` is no longer supplied for StepManeuvers + - every RouteStep is supplied with a list of at least one `Intersection`. + - Intersections offer the removed values from StepManeuver - Profile changes: - duration parser now accepts P[n]DT[n]H[n]M[n]S, P[n]W, PTHHMMSS and PTHH:MM:SS ISO8601 formats. diff --git a/docs/http.md b/docs/http.md index fd4f18fcf..c874e5604 100644 --- a/docs/http.md +++ b/docs/http.md @@ -377,7 +377,7 @@ Represents a route between two waypoints. - `duration`: The estimated travel time, in `float` number of seconds. - `summary`: Summary of the route taken as `string`. Depends on the `steps` parameter: - | steps | | + | summary | | |--------------|-----------------------------------------------------------------------| | true | Names of the two major roads used. Can be empty if route is too short.| | false | empty `string` | @@ -432,18 +432,38 @@ step. - `name`: The name of the way along which travel proceeds. - `mode`: A string signifying the mode of transportation. - `maneuver`: A `StepManeuver` object representing the maneuver. +- `intersections`: A list of `Intersections` that are passed along the segment, the very first belonging to the StepManeuver #### Example +``` +{ + "distance":152.3, + "duration":15.6, + "name":"Lortzingstraße", + "maneuver":{ + "type":"depart", + "modifier":"left" + }, + "geometry":"{lu_IypwpAVrAvAdI", + "mode":"driving", + "intersections":[ + {"location":[13.39677,52.54366], + "out":1, + "bearings":[66,246], + "entry":["true","true"]}, + {"location":[13.394718,52.543096], + "in":0, + "out":2, + "bearings":[60,150,240,330], + "entry":["false","true","true","true"] + } +]} +``` + ### StepManeuver #### Properties - -- `location`: A `[longitude, latitude]` pair describing the location of the turn. -- `bearing_before`: The clockwise angle from true north to the - direction of travel immediately before the maneuver. -- `bearing_after`: The clockwise angle from true north to the - direction of travel immediately after the maneuver. - `type` A string indicating the type of maneuver. **new identifiers might be introduced without API change** Types unknown to the client should be handled like the `turn` type, the existance of correct `modifier` values is guranteed. @@ -497,11 +517,38 @@ step. | `type` | Description | |------------------------|---------------------------------------------------------------------------------------------------------------------------| | `roundabout` | Number of the roundabout exit to take. If exit is `undefined` the destination is on the roundabout. | - | `turn` or `end of road`| Indicates the number of intersections passed until the turn. Example instruction: `at the fourth intersection, turn left` | New properties (potentially depending on `type`) may be introduced in the future without an API version change. +### Intersections + +An intersection gives a full representation of any cross-way the path passes bay. For every step, the very first intersection (`intersections[0]`) corresponds to the +location of the StepManeuver. Further intersections are listed for every cross-way until the next turn instruction. + +#### Properties + +- `location`: A `[longitude, latitude]` pair describing the location of the turn. +- `bearings`: A list of bearing values (e.g. [0,90,180,270]) that are available at the intersection. The bearings describe all available roads at the intersection. +- `entry`: A list of entry flags, corresponding in a 1:1 relationship to the bearings. A value of `true` indicates that the respective road could be entered on a valid route. + `false` indicates that the turn onto the respective road would violate a restriction. +- `in`: index into bearings/entry array. Used to calculate the bearing just before the turn. Namely, the clockwise angle from true north to the + direction of travel immediately before the maneuver/passing the intersection. Bearings are given relative to the intersection. To get the bearing + in the direction of driving, the bearing has to be rotated by a value of 180. The value is not supplied for `depart` maneuvers. +- `out`: index into the bearings/entry array. Used to extract the bearing just after the turn. Namely, The clockwise angle from true north to the + direction of travel immediately after the maneuver/passing the intersection. The value is not supplied for `arrive` maneuvers. + +#### Example +``` +{ + "location":[13.394718,52.543096], + "in":0, + "out":2, + "bearings":[60,150,240,330], + "entry":["false","true","true","true"] +} +``` + ### Waypoint Object used to describe waypoint on a route.