docs: avoid_borders build

CHANGELOG.md

@@ -28,6 +28,7 @@ Releasing is documented in RELEASE.md
 ## [unreleased]
 
 ### Added
+- documentation on how to create country border files for avoid borders feature ([#2133](https://github.com/GIScience/openrouteservice/issues/2133)
 
 ### Changed
 

docs/run-instance/data.md

@@ -29,6 +29,18 @@ Data relating to the avoid borders features is derived from administrative bound
 Configuration parameters: [
 `ors.engine.profiles.<PROFILE-NAME>.ext_storages.Borders`](configuration/engine/profiles/build.md#borders)
 
+To ensure `avoid_borders` functions correctly, the following are required:
+
+- **CSV headers & column order:** The loader skips the first row (header). Columns are positional (header text is not used to map fields).
+  - `ids_iso.csv` (3 columns): `id`, `name`, `name:en`.
+  - `open_borders.csv` (2 columns): `name:en` (country A), `name:en` (country B).
+- Formatting & encoding: Comma-separated, double-quote fields when needed (e.g. names with commas). Use UTF-8 and trim whitespace; names are compared by exact string equality (case-sensitive).
+- Rebuild: Any change to border files requires a full graph rebuild.
+
+- **Performance considerations:**  
+  Large or highly detailed polygons can make graph creation slow or stall.  
+  For extensive regions, borders should be simplified or subdivided into smaller polygons. See [this tutorial](example-setups/countries_grid.md) for guidance.
+
 ### GTFS
 The public transport profile integrates [GTFS](https://developers.google.com/transit/gtfs) data for the public transit part. GTFS feeds can be obtained e.g. from sites like https://gtfs.de/ (for Germany), or from local public transport operators.
 
@@ -62,6 +74,3 @@ which can be configured with the property [`ors.engine.elevation.cache_path`](co
 
 Log output is written to auto-rotated log files.
 See chapter [logging](configuration/logging.md) for details on configuring the location of log files.
-
-
-

docs/run-instance/example-setups/countries_grid.md

@@ -0,0 +1,107 @@
+# Creating a Country-Based Grid for openrouteservice
+
+This tutorial explains how to prepare a country-based grid dataset for openrouteservice.
+
+## Step 1: Prepare the Country Data
+
+1. Load your country dataset into **QGIS**.
+2. If your data consists of multiple **GeoJSON** files, merge them into a single vector layer:
+
+    * Go to **Vector → Data Management Tools → Merge Vector Layers**.
+    * Under *Input Layers*, select all GeoJSON files.
+
+## Step 2: Create Grids
+
+You will create two rectangular grids covering the same extent as your country layer.
+
+1. Go to **Vector → Research Tools → Create Grid**.
+2. For the first grid:
+
+    * Type: *Rectangle (Polygon)*
+    * Grid size: **10 degrees**
+    * Extent: *Same as the country layer*
+    * Save as: *hierarchy grid*
+3. For the second grid:
+
+    * Type: *Rectangle (Polygon)*
+    * Grid size: **1 degree**
+    * Extent: *Same as the country layer*
+    * Save as: *cell grid*
+    * 
+![grid_africa_grid](../../public/grid_africa_grid.png)
+
+![grid_africa_hierarchy](../../public/grid_africa_hierarchy.png)
+
+## Step 3: Assign Hierarchy IDs
+
+Join the two grids so that each 1° cell knows which 10° cell it belongs to.
+
+1. Go to **Vector → Data Management Tools → Join Attributes by Location**.
+2. Set the parameters:
+
+    * **Base layer:** cell grid
+    * **Join layer:** hierarchy grid
+    * **Geometric predicate:** *intersect*
+3. Run the tool.
+4. In the output, rename the joined field `id_2` to `hierarchy`:
+
+    * Right-click the layer → *Properties → Fields* → click the *edit pencil* and rename.
+
+## Step 4: Clip to Country Borders
+
+1. Go to **Vector → Geoprocessing Tools → Clip**.
+2. Set the parameters:
+
+    * **Input layer:** grid created in the previous step
+    * **Overlay layer:** country layer
+3. Run the tool.
+
+    * The output will be a grid clipped by country borders (some cells remain square, others follow borders).
+
+![grid_africa_clip](../../public/grid_africa_clip.png)
+
+## Step 5: Combine Country Names and Grid Attributes
+
+1. Go to **Vector → Geoprocessing Tools → Union**.
+2. Set the parameters:
+
+    * **Input layer:** the clipped grid
+    * **Overlay layer:** the country layer
+3. Run the union.
+
+    * This step combines country names with hierarchy and cell IDs.
+    * It may take some time depending on your dataset size.
+
+![grid_africa_join.png](../../public/grid_africa_join.png)
+
+The attribute table should now look like this:
+
+| id | hierarchy | NAME    |
+| -- |-----------| ------- |
+| 1  | 1         | Morocco |
+| 2  | 1         | Morocco |
+| 3  | 2         | Algeria |
+| 4  | 2         | Algeria |
+| 5  | 3         | Tunisia |
+| 6  | 3         | Tunisia |
+| 7  | 4         | Libya   |
+| 8  | 4         | Libya   |
+| 9  | 5         | Egypt   |
+| 10 | 5         | Egypt   |
+
+
+## Step 6: Export the Final Dataset
+
+Export the final union layer as a **GeoJSON** file.
+When exporting, ensure that at least the following fields are included:
+
+* **name** – country name
+* **hierarchy** – hierarchy ID
+
+This GeoJSON file can now be used within openrouteservice or related workflows.
+
+## Step 7: Manually merge inner country cells (optional)
+
+By selecting and merging inner country cells, you can reduce the number of features in the final GeoJSON file.
+
+![grid_africa_manual_merge.png](../../public/grid_africa_manual_merge.png)