diff --git a/docs/http.md b/docs/http.md index ff4b24602..0beabf6bb 100644 --- a/docs/http.md +++ b/docs/http.md @@ -21,7 +21,7 @@ GET /{service}/{version}/{profile}/{coordinates}[.{format}]?option=value&option= | `version` | Version of the protocol implemented by the service. `v1` for all OSRM 5.x installations | | `profile` | Mode of transportation, is determined statically by the Lua profile that is used to prepare the data using `osrm-extract`. Typically `car`, `bike` or `foot` if using one of the supplied profiles. | | `coordinates`| String of format `{longitude},{latitude};{longitude},{latitude}[;{longitude},{latitude} ...]` or `polyline({polyline}) or polyline6({polyline6})`. | -| `format`| Only `json` is supported at the moment. This parameter is optional and defaults to `json`. | +| `format`| `json` or `flatbuffers`. This parameter is optional and defaults to `json`. | Passing any `option=value` is optional. `polyline` follows Google's polyline format with precision 5 by default and can be generated using [this package](https://www.npmjs.com/package/polyline). @@ -944,3 +944,174 @@ Object used to describe waypoint on a route. ] } ``` + +## Flatbuffers format + +Default response format is `json`, but OSRM supports binary [`flatbuffers`](https://google.github.io/flatbuffers/) format, which +is much faster in serialization/deserialization, comparing to `json`. + +The format itself is described in message descriptors, located at `include/engine/api/flatbuffers directory`. Those descriptors could +be compiled to provide protocol parsers in Go/Javascript/Typescript/Java/Dart/C#/Python/Lobster/Lua/Rust/PHP/Kotlin. Precompiled +protocol parser for C++ is supplied with OSRM. + +`Flatbuffers` format provides exactly same data, as `json` format with a slightly different layout, which was optimized to minimize +in-transfer size. + +### Root object + +Root object is the only object, available from a 'raw' `flatbuffers` buffer. It can be constructed with a following call: + + auto osrm = osrm::engine::api::fbresult::GetFBResult(some_input_buffer); + +**Properties** + +- `error`: `bool` Marks response as erroneous. Erroneus response should include `code` field set, all the other field may not present. +- `code`: `Error` Error description object, only present, when `error` is `true` +- `waypoints`: `[Waypoint]` Array of `Waypoint` objects. Should present for every service call. Table service will put `sources` array here. +- `routes`: `[RouteObject]` Array of `RouteObject` objects. May be empty or absent. Should present for Route/Trip/Match services call. +- `table`: `Table` Table object, may absent. Should be present in case of Table service call. + +### Error object + +Contains error information. + +**Properties** + +- `code`: `string` Error code +- `message`: `string` Detailed error message + +### Waypoint object + +Almost same as `json` Waypoint object. The following properties differ: + +- `location`: `Position` Same as `json` location field, but different format. +- `nodes`: `Uint64Pair` Same as `json` nodes field, but different format. + +### RouteObject object + +Almost same as `json` Route object. The following properties differ: + +- `polyline`: `string` Same as `json` geometry.polyline or geometry.polyline6 fields. One field for both formats. +- `coordinates`: `[Position]` Same as `json` geometry.coordinates field, but different format. +- `legs`: `[Leg]` Array of `Leg` objects. + +### Leg object + +Almost same as `json` Leg object. The following properties differ: + +- `annotations`: `Annotation` Same as `json` annotation field, but different format. +- `steps`: `[Step]` Same as `step` annotation field, but different format. + +### Step object + +Almost same as `json` Step object. The following properties differ: + +- `polyline`: `string` Same as `json` geometry.polyline or geometry.polyline6 fields. One field for both formats. +- `coordinates`: `[Position]` Same as `json` geometry.coordinates field, but different format. +- `maneuver`: `StepManeuver` Same as `json` maneuver field, but different format. + +| `type` | Description | +|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `Turn` | a basic turn into direction of the `modifier` | +| `NewName` | no turn is taken/possible, but the road name changes. The road can take a turn itself, following `modifier`. | +| `Depart` | indicates the departure of the leg | +| `Arrive` | indicates the destination of the leg | +| `Merge` | merge onto a street (e.g. getting on the highway from a ramp, the `modifier specifies the direction of the merge`) | +| `OnRamp` | take a ramp to enter a highway (direction given my `modifier`) | +| `OffRamp` | take a ramp to exit a highway (direction given my `modifier`) | +| `Fork` | take the left/right side at a fork depending on `modifier` | +| `EndOfRoad` | road ends in a T intersection turn in direction of `modifier` | +| `Continue` | Turn in direction of `modifier` to stay on the same road | +| `Roundabout` | traverse roundabout, if the route leaves the roundabout there will be an additional property `exit` for exit counting. The modifier specifies the direction of entering the roundabout. | +| `Rotary` | a traffic circle. While very similar to a larger version of a roundabout, it does not necessarily follow roundabout rules for right of way. It can offer `rotary_name` and/or `rotary_pronunciation` parameters (located in the RouteStep object) in addition to the `exit` parameter (located on the StepManeuver object). | +| `RoundaboutTurn` | Describes a turn at a small roundabout that should be treated as normal turn. The `modifier` indicates the turn direciton. Example instruction: `At the roundabout turn left`. | +| `Notification` | not an actual turn but a change in the driving conditions. For example the travel mode or classes. If the road takes a turn itself, the `modifier` describes the direction | +| `ExitRoundabout` | Describes a maneuver exiting a roundabout (usually preceeded by a `roundabout` instruction) | +| `ExitRotary` | Describes the maneuver exiting a rotary (large named roundabout) | + +- `driving_side`: `bool` Ttrue stands for the left side driving. +- `intersections`: `[Intersection]` Same as `json` intersections field, but different format. + +### Intersection object + +Almost same as `json` Intersection object. The following properties differ: + +- `location`: `Position` Same as `json` location property, but in different format. +- `lanes`: `[Lane]` Array of `Lane` objects. + +### Lane object + +Almost same as `json` Lane object. The following properties differ: + +- `indications`: `Turn` Array of `Turn` enum values. + +| `value` | Description | +|------------------------|---------------------------------------------------------------------------------------------------------------------------| +| `None` | No dedicated indication is shown. | +| `UTurn` | An indication signaling the possibility to reverse (i.e. fully bend arrow). | +| `SharpRight` | An indication indicating a sharp right turn (i.e. strongly bend arrow). | +| `Right` | An indication indicating a right turn (i.e. bend arrow). | +| `SlightRight` | An indication indicating a slight right turn (i.e. slightly bend arrow). | +| `Straight` | No dedicated indication is shown (i.e. straight arrow). | +| `SlightLeft` | An indication indicating a slight left turn (i.e. slightly bend arrow). | +| `Left` | An indication indicating a left turn (i.e. bend arrow). | +| `SharpLeft` | An indication indicating a sharp left turn (i.e. strongly bend arrow). | + +### StepManeuver object + +Almost same as `json` StepManeuver object. The following properties differ: + +- `location`: `Position` Same as `json` location property, but in different format. +- `type`: `ManeuverType` Type of a maneuver (enum) + +| `type` | Description | +|------------------|--------------------------------------------------------------| +| `Turn` | a basic turn into direction of the `modifier` | +| `NewName` | no turn is taken/possible, but the road name changes. The road can take a turn itself, following `modifier`. | +| `Depart` | indicates the departure of the leg | +| `Arrive` | indicates the destination of the leg | +| `Merge` | merge onto a street (e.g. getting on the highway from a ramp, the `modifier specifies the direction of the merge`) | +| `OnRamp` | take a ramp to enter a highway (direction given my `modifier`) | +| `OffRamp` | take a ramp to exit a highway (direction given my `modifier`) | +| `Fork` | take the left/right side at a fork depending on `modifier` | +| `EndOfRoad` | road ends in a T intersection turn in direction of `modifier`| +| `Continue` | Turn in direction of `modifier` to stay on the same road | +| `Roundabout` | traverse roundabout, if the route leaves the roundabout there will be an additional property `exit` for exit counting. The modifier specifies the direction of entering the roundabout. | +| `Rotary` | a traffic circle. While very similar to a larger version of a roundabout, it does not necessarily follow roundabout rules for right of way. It can offer `rotary_name` and/or `rotary_pronunciation` parameters (located in the RouteStep object) in addition to the `exit` parameter (located on the StepManeuver object). | +| `RoundaboutTurn` | Describes a turn at a small roundabout that should be treated as normal turn. The `modifier` indicates the turn direciton. Example instruction: `At the roundabout turn left`. | +| `Notification` | not an actual turn but a change in the driving conditions. For example the travel mode or classes. If the road takes a turn itself, the `modifier` describes the direction | +| `ExitRoundabout` | Describes a maneuver exiting a roundabout (usually preceeded by a `roundabout` instruction) | +| `ExitRotary` | Describes the maneuver exiting a rotary (large named roundabout) | + +- `modifier`: `Turn` Maneuver turn (enum) + +### Annotation object + +Exactly same as `json` annotation object. + + +### Position object + +A point on Earth. + +***Properties*** +- `longitute`: `double` Point's longitude +- `latitude`: `double` Point's latitude + +### Uint64Pair + +A pair of long long integers. Used only by `Waypoint` object. + +***Properties*** +- `first`: `uint64` First pair value. +- `second`: `uint64` Second pair value. + +### Table object + +Almost same as `json` Table object. The main difference is that 'sources' field is absent and root's object 'waypoints' field is +used instead. All the other differences follow: + +- `durations`: `[float]` Flat representation of a durations matrix. Element at row;col can be adressed as [row * cols + col] +- `destinations`: `[float]` Flat representation of a destinations matrix. Element at row;col can be adressed as [row * cols + col] +- `rows`: `ushort` Number of rows in durations/destinations matrices. +- `cols`: `ushort` Number of cols in durations/destinations matrices.