Skip to content

Commit 555265c

Browse files
takbtakb
committed
docs: fix wording, weighting formula, status endpoint response listing
1 parent 0cca183 commit 555265c

File tree

2 files changed

+69
-33
lines changed

2 files changed

+69
-33
lines changed

‎docs/api-reference/endpoints/directions/custom-models.md

+36-33
Original file line numberDiff line numberDiff line change
@@ -45,12 +45,12 @@ directions endpoint:
4545

4646
## Available parameters
4747

48-
| Parameter | Type | Description |
49-
|----------------------|--------|----------------------------------------------------------------------------------------------|
50-
| `distance_influence` | Number | Time in seconds to require for each kilometer of [detour accepted](#weighting-function) |
51-
| `speed` | Array | Set of [rules](#speed-and-priority-rules) determining [speed factor](#weighting-function) |
52-
| `priority` | Array | Set of [rules](#speed-and-priority-rules) determining [priority factor](#weighting-function) |
53-
| `areas` | Object | Map of [geojson features](#areas) used in area-based [rules](#speed-and-priority-rules) |
48+
| Parameter | Type | Description |
49+
|----------------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
50+
| `distance_influence` | Number | Time saved in seconds to require for each kilometer of [detour accepted](#weighting-function), determining [distance influence factor](#weighting-function) |
51+
| `speed` | Array | Set of [rules](#speed-and-priority-rules) determining [speed factor](#weighting-function) |
52+
| `priority` | Array | Set of [rules](#speed-and-priority-rules) determining [priority factor](#weighting-function) |
53+
| `areas` | Object | Map of [GeoJSON Features](#areas) used in area-based [rules](#speed-and-priority-rules) |
5454

5555
## Basic principle
5656

@@ -68,27 +68,27 @@ value will be IGNORED.
6868

6969
The weighting function for each edge is calculated as follows:
7070

71-
```
72-
weight = [edge distance] / ([edge speed] * speed * priority) + [edge distance] * distance_influence
73-
```
71+
weight = distance / (speed * `speed factor` * `priority factor`) + distance * `distance influence factor`
7472

75-
where `speed`, `priority` and `distance_influence` are the values derived from the custom model, and `[edge distance]`
76-
and `[edge speed]` are valued stored in the graph.
73+
where `speed factor`, `priority factor` and `distance influence factor` are values derived from the respective
74+
parameters of the custom model, and distance and speed are values stored in the graph for each edge.
7775

78-
The `distance_influence` parameter is a factor that influences the weight of the edge based on the travel distance. If
79-
set to zero, the distance will not be taken into account in the weighting function. If set to a value greater than zero,
80-
the distance will be multiplied by this factor before being added to the weight. The result of this is that a ratio of
81-
preference between distance and speed can be set. The value provided in the custom model is used such that it
82-
corresponds to the required time saved in seconds per kilometer of detour. If you e.g. set a value of `60`, that means a
83-
faster route by travel time is only returned if it saves at least a minute for every additional kilometer of distance
84-
travelled, therefore a detour to take the highway instead of ordinary roads that adds, say, 2 kilometers, is only
85-
returned as "better" route if this saves at least 2 minutes of time.
76+
The `distance_influence` parameter is used to calculate the `distance influence factor` that influences the weight of
77+
the edge based on the travel distance. If set to zero, the distance will not be taken into account in the weighting
78+
function. If set to a value greater than zero, the distance will be multiplied by the derived factor before being added
79+
to the weight. The result of this is that a ratio of preference between distance and speed can be set. The value
80+
provided in the custom model is used such that it corresponds to the required time saved in seconds per kilometer of
81+
detour. If you e.g. set `distance_influence` to 60, that means a faster route by travel time is only returned if it
82+
saves at least a minute for every additional kilometer of distance travelled, therefore a detour to take the highway
83+
instead of ordinary roads that adds, say, 2 kilometers, is only returned as "better" route if this saves at least 2
84+
minutes of time.
8685

87-
The factors `speed` and `priority` are multiplied with the edge speed. Both are calculated based on the rules provided
88-
in the custom model, the difference being that the `speed` factor also changes the travel time computation, while the
89-
`priority` factor is only used to influence the weight of the edge during route computation and does not change the
90-
travel time. Both parameters expect an array of objects, where each object is a rule consisting of a condition and an
91-
operation to be applied. These are described in more detail in the next section.
86+
The `speed factor` and the `priority factor` are multiplied with the edge speed. Both are calculated based on the rules
87+
provided in the corresponding parameters `speed` and `priority` in the custom model, the difference being that the
88+
`speed factor` also changes the travel time computation, while the `priority factor` is only used to influence the
89+
weight of the edge during route computation and does not change the travel time. Both parameters expect an array of
90+
objects, where each object is a rule consisting of a condition and an operation to be applied. These are described in
91+
more detail in the next section.
9292

9393
## Speed and Priority Rules
9494

@@ -98,8 +98,8 @@ structure:
9898

9999
```json
100100
{
101-
"condition_key": "condition_value",
102-
"operation_key": "operation_value"
101+
"operation_key": "operation_value",
102+
"condition_key": "condition_value"
103103
}
104104
```
105105

@@ -124,22 +124,24 @@ mean to avoid the edge completely, a `1` would mean indeterminate; any number in
124124
favorability, smaller numbers meaning less favorable.
125125

126126
If the key is `limit_to`, the value is interpreted as a maximum speed that can be travelled on the affected edges. Edges
127-
with a lower travel speed stored in the graph will not be affected by this rule.
127+
with a higher speed will have their speeds adjusted, edges with a lower travel speed stored in the graph will not be
128+
affected by this rule.
128129

129130
### Conditions
130131

131132
The `condition_key` is a string with the possible values `if`, `else_if` and `else`. `else_if` and `else` require a
132-
preceding rule with `if`, `else_if` as condition key, and are applied only if the preceding rule's condition did NOT
133+
preceding rule with `if` or `else_if` as condition key, and are applied only if the preceding rule's condition did NOT
133134
match.
134135

135136
The `condition_value` can be a string or boolean value. If it is a string, it can either have the form
136137
`in_[AREA_NAME]` (see [section below](#areas) for details) OR describe a logical statement that can evaluate as true or
137138
false. The logical statement can be a simple comparison of a variable and a value, e.g. `road_class == MOTORWAY`, or a
138-
more complex statement using Java boolean operators, e.g. `max_width <= 2.2 && (road_environment == TUNNEL || roundabout)`.
139+
more complex statement using Java boolean operators, e.g.
140+
`max_width <= 2.2 && (road_environment == TUNNEL || roundabout)`.
139141

140-
The variables that can be used in those statements are called 'encoded values', and different ones are available for
141-
different profiles. The available encoded values can be found in the response to the `status` endpoint, in the array
142-
`profiles.<PROFILE NAME>.encoded_values`. Below is a list of example 'encoded values' and their possible values that are
142+
The variables that can be used in those statements are called `encoded values`, and different ones are available for
143+
different profiles. The available `encoded values` can be found in the response to the [status endpoint](/api-reference/endpoints/status/), in the array
144+
`profiles.<PROFILE NAME>.encoded_values`. Below is a list of example `encoded values` and their possible values that are
143145
available. Note that this list is incomplete and the available variables depend on the profile in question.
144146

145147
| name | Type | Description |
@@ -156,7 +158,8 @@ available. Note that this list is incomplete and the available variables depend
156158
| `max_height` | Numerical | Max height in m |
157159
| `max_width` | Numerical | Max width in m |
158160

159-
Enum type encoded values can be used with the `==` and `!=` operators, while numerical encoded values can be used with the
161+
Enum type encoded values can be used with the `==` and `!=` operators, while numerical encoded values can be used with
162+
the
160163
`==`, `!=`, `<`, `<=`, `>`, `>=` operators. Boolean encoded valued do not require an operator, but can be used with the
161164
`==`, `!=` and `!` operators.
162165

‎docs/api-reference/endpoints/status/index.md

+33
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ The GET request http://localhost:8082/ors/v2/status (host and port are dependent
2020
The profile names are used as path parameters in API requests and as directory names for the graph directories.
2121
Some basic information is shown for each profile:
2222
* `encoder_name`: The vehicle type
23+
* `encoded_values`: The list of available encoded values that can be used in [custom models](/api-reference/endpoints/directions/custom-models)
2324
* `osm_date`: Timestamp of the osm pbf file that was used for building the graph. This is usually the date of the
2425
latest included change.
2526
* `graph_build_date`: The date, when graph building was started for this routing profile.
@@ -106,6 +107,23 @@ This is an example response:
106107
}
107108
},
108109
"encoder_name": "driving-car",
110+
"encoded_values": [
111+
"road_environment",
112+
"car_ors_fastest_with_turn_costs_subnetwork",
113+
"car_ors_fastest_subnetwork",
114+
"car_ors_shortest_with_turn_costs_subnetwork",
115+
"car_ors_shortest_subnetwork",
116+
"car_ors_recommended_with_turn_costs_subnetwork",
117+
"car_ors_recommended_subnetwork",
118+
"roundabout",
119+
"road_class",
120+
"road_class_link",
121+
"max_speed",
122+
"road_access",
123+
"car_ors$access",
124+
"car_ors$average_speed",
125+
"car_ors$turn_cost"
126+
],
109127
"graph_build_date": "2024-10-28T14:42:49Z",
110128
"osm_date": "2023-10-11T20:21:48Z",
111129
"limits": {
@@ -117,6 +135,21 @@ This is an example response:
117135
},
118136
"pedestrian": {
119137
"encoder_name": "foot-walking",
138+
"encoded_values": [
139+
"road_environment",
140+
"pedestrian_ors_fastest_subnetwork",
141+
"pedestrian_ors_shortest_subnetwork",
142+
"pedestrian_ors_recommended_subnetwork",
143+
"roundabout",
144+
"road_class",
145+
"road_class_link",
146+
"max_speed",
147+
"road_access",
148+
"foot_network",
149+
"pedestrian_ors$access",
150+
"pedestrian_ors$average_speed",
151+
"pedestrian_ors$priority"
152+
],
120153
"graph_build_date": "2024-10-11T11:08:44Z",
121154
"osm_date": "2024-01-22T21:21:14Z",
122155
"limits": {

0 commit comments

Comments
 (0)