From 34ed5adb0f444a0de9014df37dcd8f469a11865a Mon Sep 17 00:00:00 2001
From: aoles <andrzej.oles@gmail.com>
Date: Mon, 25 Mar 2024 15:48:47 +0100
Subject: [PATCH] docs: document A* config parameters

---
 CHANGELOG.md                                  |  2 ++
 .../configuration/ors/engine/profiles.md      | 29 +++++++++++++------
 2 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 03a2781e60..80c8b35b12 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -34,6 +34,8 @@ RELEASING:
  -->
 
 ## [Unreleased]
+### Added
+- documentation for A* config parameters ([#1759](https://github.com/GIScience/openrouteservice/pull/1759))
 
 ## [8.0.0] - 2024-03-21
 ### Added
diff --git a/docs/run-instance/configuration/ors/engine/profiles.md b/docs/run-instance/configuration/ors/engine/profiles.md
index ecc9962abd..1af7d1c8b1 100644
--- a/docs/run-instance/configuration/ors/engine/profiles.md
+++ b/docs/run-instance/configuration/ors/engine/profiles.md
@@ -53,15 +53,15 @@ Properties for each (enabled) profile are set under `ors.engine.profiles.<profil
 
 Properties beneath `ors.engine.profiles.*.encoder_options`:
 
-| key                      | type    | profiles         | description                                                                                                                                                                                                                   | example value |
-|--------------------------|---------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
-| block_fords              | boolean | *                | Do not route through fords.                                                                                                                                                                                                   | `true`        |
-| consider_elevation       | boolean | bike-*           | The maximum possible speed is the bike-type specific maximum downhill speed, which is higher than the usual maximum speed.                                                                                                    | `true`        |
-| maximum_grade_level      | number  | car, hgv         | Relates to the quality of tracks as described in [tracktype](https://wiki.openstreetmap.org/wiki/Key:tracktype). Specifying e.g. maximum_grade_level=1 means that tracktype=grade2 and below won't be considered for routing. | `3`           |
-| preferred_speed_factor   | number  | wheelchair       | Travel speeds on edges classified as preferable for wheelchair users are multiplied by this factor, use to set faster traveling speeds on such ways                                                                           | `1.2`         |
-| problematic_speed_factor | number  | wheelchair       | Travel speeds on edges classified as problematic for wheelchair users are multiplied by this factor, use to set slow traveling speeds on such ways                                                                            | `0.7`         |
-| turn_costs               | boolean | car, hgv, bike-* | Should turn restrictions be respected.                                                                                                                                                                                        | `true`        |
-| use_acceleration         | boolean | car, hgv         | Models how a vehicle would accelerate on the road segment to the maximum allowed speed. In practice it reduces speed on shorter road segments such as ones between nearby intersections in a city.                            | `true`        |
+| key                      | type    | profiles         | description                                                                                                                                                                                                                  | example value |
+|--------------------------|---------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
+| block_fords              | boolean | *                | Do not route through fords                                                                                                                                                                                                   | `true`        |
+| consider_elevation       | boolean | bike-*           | The maximum possible speed is the bike-type specific maximum downhill speed, which is higher than the usual maximum speed                                                                                                    | `true`        |
+| maximum_grade_level      | number  | car, hgv         | Relates to the quality of tracks as described in [tracktype](https://wiki.openstreetmap.org/wiki/Key:tracktype). Specifying e.g. maximum_grade_level=1 means that tracktype=grade2 and below won't be considered for routing | `3`           |
+| preferred_speed_factor   | number  | wheelchair       | Travel speeds on edges classified as preferable for wheelchair users are multiplied by this factor, use to set faster traveling speeds on such ways                                                                          | `1.2`         |
+| problematic_speed_factor | number  | wheelchair       | Travel speeds on edges classified as problematic for wheelchair users are multiplied by this factor, use to set slow traveling speeds on such ways                                                                           | `0.7`         |
+| turn_costs               | boolean | car, hgv, bike-* | Should turn restrictions be respected                                                                                                                                                                                        | `true`        |
+| use_acceleration         | boolean | car, hgv         | Models how a vehicle would accelerate on the road segment to the maximum allowed speed. In practice it reduces speed on shorter road segments such as ones between nearby intersections in a city                            | `true`        |
 
 ## preparation
 
@@ -113,6 +113,17 @@ Properties beneath `ors.engine.profiles.*.preparation.methods.core`:
 
 Properties beneath `ors.engine.profiles.*.execution` are relevant when querying services.
 
+### methods.astar
+
+Parameters for beeline approximation in the A* routing algorithm.
+
+Properties beneath `ors.engine.profiles.*.execution.methods.astar`:
+
+| key           | type   | description                                                                                                                                 | default value           |
+|---------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------|-------------------------| 
+| approximation | string | Method to use for distance approximation. Can be either the faster `BeelineSimplification` or the more precise but slower `BeelineAccurate` | `BeelineSimplification` |
+| epsilon       | number | Factor to use for distance approximation                                                                                                    | `1`                     |
+
 ### methods.lm
 
 Settings for using landmarks in routing.