Skip to content

Commit

Permalink
docs: improvements to external storage documentation (#1811)
Browse files Browse the repository at this point in the history
  • Loading branch information
@takb
takb authored Sep 30, 2024
2 parents 557c7b6 + b4f17be commit 9093cce
Show file tree
Hide file tree
Showing 7 changed files with 59 additions and 19 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ RELEASING:
### Added
### Changed
- refactor: cleanup routing profile management ([#1850](https://github.com/GIScience/openrouteservice/pull/1850)
- improved documentation on the configuration of external storages ([#1811](https://github.com/GIScience/openrouteservice/pull/1811)))
### Deprecated
### Removed
### Fixed
Expand Down
1 change: 1 addition & 0 deletions docs/api-reference/endpoints/directions/extra-info/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ Some values are not available in all routing profiles:
| cycling-regular | x | x | x | x | x | | x | | | | | | |
| cycling-mountain | x | x | x | x | x | | x | | | | | | |
| cycling-road | x | x | x | x | x | | x | | | | | | |
| cycling-electric | x | x | x | x | x | | x | | | | | | |
| foot-walking | x | x | x | x | x | | x | | | | x | x | x |
| foot-hiking | x | x | x | x | x | | x | | | | x | x | x |
| wheelchair | x | x | x | x | x | | x | x | | | | | |
Expand Down
3 changes: 3 additions & 0 deletions docs/api-reference/endpoints/directions/routing-options.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ With the request body parameter `options`, advanced routing options can be speci
The `options` parameter is a JSON object, multiple of the here mentioned parameters can be set.
For structure refer to the [examples](#examples).

::: warning
Some of the options below rely on auxiliary data included in the graph, see [External storages](../../../run-instance/configuration/ors/engine/profiles.md#ext_storages)
:::

## Available parameters

Expand Down
67 changes: 48 additions & 19 deletions docs/run-instance/configuration/ors/engine/profiles.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -160,28 +160,51 @@ Properties beneath `ors.engine.profiles.*.execution.methods.core`:

## ext_storages

For each profile it can be defined which external storages for extra info should be included in the graph.
This makes those information available as `extra_info` in a routing response.

It can be defined for each profile which auxiliary metadata should be included in the graph.
This information is made available as `extra_info` in a routing response.
To do so, add a key from the list below.
Leave its value empty, unless you want to specify further options (currently only available for
`RoadAccessRestrictions`, `Borders` and `Wheelchair`).

Properties beneath `ors.engine.profiles.*.ext_storages`:
[RoadAccessRestrictions](#roadaccessrestrictions), [Borders](#borders), [Wheelchair](#wheelchair) and [HeavyVehicle](#heavyvehicle)).

| key | type | description | example value |
|------------------------|--------|------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
| WayCategory | object | Returns the way category in the route response, Compatible for any profile type | |
| WaySurfaceType | object | Returns the way surface in the route response, Compatible for any profile type | |
| HillIndex | object | Returns the ascent/descent in the route response, Compatible for any profile type | |
| TrailDifficulty | object | Returns the trail difficulty in the route response, Compatible for profile-hiking | |
| RoadAccessRestrictions | object | RoadAccessRestrictions are where roads are restricted to certain vehicles to certain circumstances, e.g. access=destination. | [RoadAccessRestrictions](#roadaccessrestrictions) |
| Wheelchair | object | Compatible for wheelchair | [Wheelchair](#wheelchair) |
| OsmId | object | Returns the OsmId of the way, Compatible for wheelchair | |
| Borders | object | Borders allows the restriction of routes to not cross country borders, compatible for any profile type | [Borders](#borders) |
::: warning
In addition to providing the information in query response, data from `WayCategory` and `Tollways` storages is being
used to filter out certain roads via the
[`options.avoid_features`](../../../../api-reference/endpoints/directions/routing-options.md#options-avoid-features)
query parameter, and `Borders` is necessary for the functionality behind
[`options.avoid_borders`](../../../../api-reference/endpoints/directions/routing-options.md#options-avoid-borders) and
[`options.avoid_countries`](../../../../api-reference/endpoints/directions/routing-options.md#options-avoid-countries)
query parameters. Options from
[`options.profile_params.restrictions`](../../../../api-reference/endpoints/directions/routing-options.md#options-profile-params-restrictions)
require `HeavyVehicle` or `Wheelchair` storages being enabled. Furthermore, hgv profile-specific access restrictions specified in
[`options.vehicle_type`](../../../../api-reference/endpoints/directions/routing-options.md#options-vehicle-type) parameter
rely on the `HeavyVehicle` storage.
:::

Properties beneath `ors.engine.profiles.*.ext_storages`:

Have a look at [this table](../../../../api-reference/endpoints/directions/extra-info/index.md#extra-info-availability) to check which external storages are enabled for the which profile by default.
| key | type | description | example value |
|------------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
| WayCategory | object | Returns the way category in the route response, compatible with any profile type | |
| WaySurfaceType | object | Returns the way surface in the route response, compatible with any profile type | |
| Tollways | object | Returns way tolls in the route response, compatible with driving profiles | |
| Borders | object | Borders allows the restriction of routes to not cross country borders, compatible with any profile type | [Borders](#borders) |
| RoadAccessRestrictions | object | Information on restriction of roads to certain vehicles or circumstances, e.g. `access=destination` | [RoadAccessRestrictions](#roadaccessrestrictions) |
| HeavyVehicle | object | Heavy vehicle-specific storage compatible only with that profile; it contains weight and size limits as well as vehicle-type access restrictions | [HeavyVehicle](#heavyvehicle) |
| HillIndex | object | Returns the ascent/descent in the route response, compatible with any profile type | |
| TrailDifficulty | object | Returns the trail difficulty in the route response, compatible with walking and cycling profiles | |
| Wheelchair | object | Wheelchair-specific attributes compatible only with that profile | [Wheelchair](#wheelchair) |
| OsmId | object | Returns the OsmId of the way, compatible only with wheelchair profile | |

Check [this table](../../../../api-reference/endpoints/directions/extra-info/index.md#extra-info-availability) for extra info availability.
The following table summarizes which storages are enabled for which profile by default.

| | WayCategory | WaySurfaceType | Tollways | Borders | RoadAccessRestrictions | HeavyVehicle | HillIndex | TrailDifficulty | Wheelchair | OsmId |
|:------------|:-----------:|:--------------:|:--------:|---------|:----------------------:|:------------:|:---------:|:---------------:|:----------:|:-----:|
| driving-car | x | x | x | | x | | | | | |
| driving-hgv | x | x | x | | | x | | | | |
| cycling-* | x | x | | | | | x | x | | |
| foot-* | x | x | | | | | x | x | | |
| wheelchair | x | x | | | | | | | x | x |


### RoadAccessRestrictions
Expand All @@ -199,10 +222,16 @@ The `use_for_warnings` parameter tells the ors that this storage can be used for

### Borders

Properties beneath `ors.engine.profiles.*.ext_storages.Borders` allows to define restriction of routes to not cross country borders, compatible for any profile type.:
Properties beneath `ors.engine.profiles.*.ext_storages.Borders` allows to define restriction of routes to not cross country borders, compatible with any profile type.

| key | type | description | example value |
|-------------|--------|-----------------------------------------------------------------------------------------------------|--------------------------|
| boundaries | string | The path to a file containing geojson data representing the borders of countries | `borders.geojson.tar.gz` |
| boundaries | string | The path to a geojson file containing polygons representing country borders | `borders.geojson.tar.gz` |
| ids | string | Path to a csv file containing a unique id for each country, its local name and its English name | `ids.csv` |
| openborders | string | Path to a csv file containing pairs of countries where the borders are open (i.e. Schengen borders) | `openborders.csv` |

### HeavyVehicle

| key | type | description | example value |
|--------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
| restrictions | boolean | Encode certain size and weight limits such as ones contained in `maxheight`, `maxlength`, `maxwidth`, `maxweight` and `maxaxleload` OSM way tags. Includes also access restrictions for vehicles carrying hazardous materials as provided by the `hazmat` tag. | `true` |
2 changes: 2 additions & 0 deletions ors-api/src/main/resources/application.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,7 @@ ors:
WayCategory:
HeavyVehicle:
WaySurfaceType:
Tollways:
RoadAccessRestrictions:
use_for_warnings: true
hgv:
Expand Down Expand Up @@ -219,6 +220,7 @@ ors:
HeavyVehicle:
restrictions: true
WaySurfaceType:
Tollways:
bike-regular:
profile: cycling-regular
encoder_options:
Expand Down
2 changes: 2 additions & 0 deletions ors-config.env
View file
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,7 @@ ors.engine.source_file=ors-api/src/test/files/heidelberg.osm.gz
#ors.engine.profiles.car.ext_storages.WayCategory=
#ors.engine.profiles.car.ext_storages.HeavyVehicle=
#ors.engine.profiles.car.ext_storages.WaySurfaceType=
#ors.engine.profiles.car.ext_storages.Tollways=
#ors.engine.profiles.car.ext_storages.RoadAccessRestrictions.use_for_warnings=true
ors.engine.profiles.car.enabled=true
#ors.engine.profiles.hgv.profile=driving-hgv
Expand All @@ -138,6 +139,7 @@ ors.engine.profiles.car.enabled=true
#ors.engine.profiles.hgv.ext_storages.WayCategory=
#ors.engine.profiles.hgv.ext_storages.HeavyVehicle.restrictions=true
#ors.engine.profiles.hgv.ext_storages.WaySurfaceType=
#ors.engine.profiles.hgv.ext_storages.Tollways=
#ors.engine.profiles.bike-regular.profile=cycling-regular
#ors.engine.profiles.bike-regular.encoder_options.consider_elevation=true
#ors.engine.profiles.bike-regular.encoder_options.turn_costs=true
Expand Down
2 changes: 2 additions & 0 deletions ors-config.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,7 @@ ors:
# WayCategory:
# HeavyVehicle:
# WaySurfaceType:
# Tollways:
# RoadAccessRestrictions:
# use_for_warnings: true
enabled: true
Expand Down Expand Up @@ -213,6 +214,7 @@ ors:
# HeavyVehicle:
# restrictions: true
# WaySurfaceType:
# Tollways:
# bike-regular:
# profile: cycling-regular
# encoder_options:
Expand Down

0 comments on commit 9093cce

Please sign in to comment.