Added short flatbuffers introduction.
This commit is contained in:
Denis Chaplygin
parent
73f544d4da
commit
5888894787
173
docs/http.md
173
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 |
|
| `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. |
|
| `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})`. |
|
| `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).
|
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.
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user