docs: describe GeoJSON fields in directions response (#2154)

aoles · web-flow · commit 698f938bc806 · 2025-11-22T02:10:00.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -28,7 +28,7 @@ Releasing is documented in RELEASE.md
 ## [unreleased]
 
 ### Added
-
+- documentation on the fields of JSON and GeoJSON responses of the directions endpoint ([#2084](https://github.com/GIScience/openrouteservice/issue/2084))
 - docs: comment on API key usage ([#2179](https://github.com/GIScience/openrouteservice/pull/2179))
 - type-specific filtering for mapping point features to graph edges ([#2156](https://github.com/GIScience/openrouteservice/pull/2156))
 - documentation on the matching endpoint ([#2156](https://github.com/GIScience/openrouteservice/pull/2156))
diff --git a/docs/api-reference/endpoints/directions/instruction-types.md b/docs/api-reference/endpoints/directions/instruction-types.md
@@ -5,12 +5,12 @@
 
 The following table contains the encoding of the instruction types present in the `type`-field of a directions response in a step of a segment of a route.
 
-JSON-Path in json response:
+JSONPath in JSON response:
 ```jsonpath
 $.routes[*].segments[*].steps[*].type
 ```
 
-JSON-Path in geojson response:
+JSONPath in GeoJSON response:
 ```jsonpath
 $.features[*].properties.segments[*].steps[*].type
 ```
diff --git a/docs/api-reference/endpoints/directions/requests-and-return-types.md b/docs/api-reference/endpoints/directions/requests-and-return-types.md
@@ -18,16 +18,43 @@ Additionally, there is one simple GET request that does not allow advanced reque
 
 ### JSON 
 
-The **JSON** return type is best suited for further processing.
+The **JSON** output format is the most flexible and best suited one for further processing.
+Its top level structure consists of three main fields:
 
-### GPX
+| Field          | Description                                                                                                                           |
+|----------------|---------------------------------------------------------------------------------------------------------------------------------------|
+| **`bbox`**     | Bounding box `[minLon, minLat, maxLon, maxLat]` covering all of the routes in the response.                                           |
+| **`routes`**   | List of routes.                                                                                                                       |
+| **`metadata`** | Additional details about the request and routing engine, including `attribution`, `service`, `timestamp`, `query`, and `engine` info. |
+
+Each of the `routes` entries can contain the following fields.
+
+| Field            | Description                                                                                                                                                           |
+|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **`summary`**    | Properties of the route such as total `distance` (m) and `duration` (s).                                                                                              |
+| **`segments`**   | List of route sections between waypoints, each with `distance`, `duration`, and `steps` containing turn-by-turn navigation instructions if these have been requested. |
+| **`bbox`**       | Bounding box of the route.                                                                                                                                            |
 
-The **GPX** return type is an XML dialect from openrouteservice based on the [GPS Exchange Format](https://www.topografix.com/gpx.asp) with an own [XML Schema](https://raw.githubusercontent.com/GIScience/openrouteservice-schema/main/gpx/v2/ors-gpx.xsd).
-It is a very old standard for lightweight interchange of GPS data and thus being used by hundreds of software programs and Web services.
+Furthermore, if route geometry has been requested (which is the default), the following fields are present.
+
+| Field            | Description                                                                                                                                                                                    |
+|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **`geometry`**   | The path of the route. In JSON it is [encoded](https://developers.google.com/maps/documentation/utilities/polylinealgorithm), while in GeoJSON it is a `LineString` with explicit coordinates. |
+| **`way_points`** | Indices of way points corresponding to the `geometry`.                                                                                                                                         |
 
 ### GeoJSON
 
-**GeoJSON** is a format for encoding a variety of geographic data structures, see [geojson.org](https://datatracker.ietf.org/doc/html/rfc7946).
-It is widely used and can therefore be easily processed or displayed in many applications, e.g. in [QGIS](https://qgis.org/) or on [geojson.io](http://geojson.io/)
+**GeoJSON** is a standardized format for encoding a variety of geographic data structures, see [geojson.org](https://datatracker.ietf.org/doc/html/rfc7946).
+It is widely used and can therefore be easily processed or displayed in many applications, e.g. in [QGIS](https://qgis.org/) or on [geojson.io](http://geojson.io/).
+
+The **GeoJSON** output contains the same routing information as its **JSON** counterpart, but organized in slightly different way.
+
+In the **GeoJSON** format, the route data is structured as a standard **FeatureCollection** where individual routes are represented as `features`.
+Each **Feature** includes a `geometry` of type `LineString` and `properties` that contain the same fields as the `routes` elements in the JSON format, i.e. `summary`, `segments`, `way_points`, etc.
+
+### GPX
+
+The **GPX** return type is an XML dialect from openrouteservice based on the [GPS Exchange Format](https://www.topografix.com/gpx.asp) with its own [XML Schema](https://raw.githubusercontent.com/GIScience/openrouteservice-schema/main/gpx/v2/ors-gpx.xsd).
+It is a very old standard for lightweight interchange of GPS data and thus being used by a wide range of software applications and Web services.
 
-More information about the result types can be found in the [API Playground](https://openrouteservice.org/dev/#/api-docs/directions_service).
+More details on the structure of the different return types can be found in the [API Playground](https://openrouteservice.org/dev/#/api-docs/directions_service).
diff --git a/docs/api-reference/endpoints/directions/routing-options.md b/docs/api-reference/endpoints/directions/routing-options.md
@@ -34,7 +34,7 @@ A string array of features to avoid. The available features are :
 | `steps`    | cycling-\*, foot-\*, wheelchair             |
 
 ### `options.avoid_polygons` 
-Comprises areas to be avoided for the route. Formatted as [geojson polygon](https://datatracker.ietf.org/doc/html/rfc7946#appendix-A.3) or [geojson multipolygon](https://datatracker.ietf.org/doc/html/rfc7946#appendix-A.6).
+Comprises areas to be avoided for the route. Formatted as [GeoJSON polygon](https://datatracker.ietf.org/doc/html/rfc7946#appendix-A.3) or [GeoJSON multipolygon](https://datatracker.ietf.org/doc/html/rfc7946#appendix-A.6).
 
 ### `options.profile_params`
 An object of additional routing parameters for all profiles except `driving-car`: 
diff --git a/docs/api-reference/endpoints/export/index.md b/docs/api-reference/endpoints/export/index.md
@@ -35,10 +35,10 @@ curl -X 'POST' \
 }'
 ```
 
-The json response contains nodes and edges in the bounding box relevant for this routing profile.
+The JSON response contains nodes and edges in the bounding box relevant for this routing profile.
 The edge entry `weight` contains the fastest car duration in seconds.
 
-The json response for the above request looks like this:
+The JSON response for the above request looks like this:
 
 ```json
 {
diff --git a/docs/api-reference/error-codes.md b/docs/api-reference/error-codes.md
@@ -75,7 +75,7 @@ Endpoints.
 |    4000    | Invalid JSON object in request.                     |
 |    4001    | Category or category group ids missing.             |
 |    4002    | Geometry is missing.                                |
-|    4003    | Bounding box and or geojson not present in request. |
+|    4003    | Bounding box and or GeoJSON not present in request. |
 |    4004    | Buffer is missing.                                  |
 |    4005    | Geometry length does not meet the restrictions.     |
 |    4006    | Unsupported HTTP method.                            |
diff --git a/docs/api-reference/index.md b/docs/api-reference/index.md
@@ -21,7 +21,7 @@ Use the form "API Server" on the top left to select and edit "Development Server
 ![Development server usage](/playground-select-server.png "Development server usage"){ style="display: block; margin: 0 auto"}
 
 The responses of your sample requests are visualized on a small map on the bottom right,
-but can also be shown as json, table or downloaded as file:
+but can also be shown as JSON, table or downloaded as file:
 ![Example request visualization](/playground-map.png "Example request visualization"){ style="display: block; margin: 0 auto"}
 
 ::: warning Hint
diff --git a/docs/run-instance/configuration/engine/profiles/build.md b/docs/run-instance/configuration/engine/profiles/build.md
@@ -159,7 +159,7 @@ country borders, compatible with any profile type.
 
 | key          | type    | description                                                                                                                                                                                                                             | example value            |
 |--------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------|
-| boundaries   | string  | The path to a geojson file containing polygons representing country borders. Ignored if `preprocessed = true` is set.                                                                                                                   | `borders.geojson.tar.gz` |
+| boundaries   | string  | The path to a GeoJSON file containing polygons representing country borders. Ignored if `preprocessed = true` is set.                                                                                                                   | `borders.geojson.tar.gz` |
 | preprocessed | boolean | Indicates whether the source OSM file has been enriched with country data. If set to `true` then country codes are read from `country` node tags rather than being resolved at build time based on geometries provided in `boundaries`. | `true`                    |
 | 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`        |
diff --git a/ors-api/src/main/java/org/heigit/ors/api/responses/routing/IndividualRouteResponse.java b/ors-api/src/main/java/org/heigit/ors/api/responses/routing/IndividualRouteResponse.java
@@ -19,13 +19,13 @@
 import org.heigit.ors.routing.RouteResult;
 import org.locationtech.jts.geom.Coordinate;
 
-public class IndividualRouteResponse {
+public abstract class IndividualRouteResponse {
     protected Coordinate[] routeCoordinates;
     protected boolean includeElevation = false;
     protected boolean isPtRequest = false;
 
 
-    public IndividualRouteResponse(RouteResult result, RouteRequest request) {
+    protected IndividualRouteResponse(RouteResult result, RouteRequest request) {
         if (result.getGeometry() != null)
             this.routeCoordinates = result.getGeometry();
 
diff --git a/ors-api/src/main/java/org/heigit/ors/api/responses/routing/JSONBasedIndividualRouteResponse.java b/ors-api/src/main/java/org/heigit/ors/api/responses/routing/JSONBasedIndividualRouteResponse.java
@@ -13,12 +13,14 @@
  * if not, see <https://www.gnu.org/licenses/>.
  */
 
-package org.heigit.ors.api.responses.routing.json;
+package org.heigit.ors.api.responses.routing;
 
 import org.heigit.ors.api.requests.routing.RouteRequest;
 import org.heigit.ors.api.responses.common.boundingbox.BoundingBox;
 import org.heigit.ors.api.responses.common.boundingbox.BoundingBoxFactory;
-import org.heigit.ors.api.responses.routing.IndividualRouteResponse;
+import org.heigit.ors.api.responses.routing.json.JSONExtra;
+import org.heigit.ors.api.responses.routing.json.JSONLeg;
+import org.heigit.ors.api.responses.routing.json.JSONSegment;
 import org.heigit.ors.common.DistanceUnit;
 import org.heigit.ors.exceptions.StatusCodeException;
 import org.heigit.ors.routing.RouteExtraInfo;
@@ -32,10 +34,10 @@
 import java.util.List;
 import java.util.Map;
 
-public class JSONBasedIndividualRouteResponse extends IndividualRouteResponse {
+public abstract class JSONBasedIndividualRouteResponse extends IndividualRouteResponse {
     protected BoundingBox bbox;
 
-    public JSONBasedIndividualRouteResponse(RouteResult result, RouteRequest request) throws StatusCodeException {
+    protected JSONBasedIndividualRouteResponse(RouteResult result, RouteRequest request) throws StatusCodeException {
         super(result, request);
         if (request.hasUseElevation() && request.getUseElevation())
             includeElevation = true;
@@ -44,7 +46,7 @@ public JSONBasedIndividualRouteResponse(RouteResult result, RouteRequest request
     }
 
     protected List<JSONSegment> constructSegments(RouteResult routeResult, RouteRequest request) {
-        List segments = new ArrayList<>();
+        List<JSONSegment> segments = new ArrayList<>();
         for (RouteSegment routeSegment : routeResult.getSegments()) {
             segments.add(new JSONSegment(routeSegment, request, routeResult.getSummary().getDistance()));
         }
diff --git a/ors-api/src/main/java/org/heigit/ors/api/responses/routing/RouteResponse.java b/ors-api/src/main/java/org/heigit/ors/api/responses/routing/RouteResponse.java
@@ -23,7 +23,7 @@
 
 import java.util.List;
 
-public class RouteResponse {
+public abstract class RouteResponse {
     @JsonIgnore
     protected RouteResponseInfo responseInformation;
 
@@ -33,7 +33,7 @@ public class RouteResponse {
     @JsonIgnore
     protected List<IndividualRouteResponse> routeResults;
 
-    public RouteResponse(RouteRequest request, SystemMessageProperties systemMessageProperties, EndpointsProperties endpointsProperties) {
+    protected RouteResponse(RouteRequest request, SystemMessageProperties systemMessageProperties, EndpointsProperties endpointsProperties) {
         responseInformation = new RouteResponseInfo(request, systemMessageProperties, endpointsProperties);
     }
 
@@ -44,8 +44,4 @@ public RouteResponseInfo getResponseInformation() {
     public BoundingBox getBbox() {
         return bbox;
     }
-
-    public List<IndividualRouteResponse> getRouteResults() {
-        return routeResults;
-    }
 }
diff --git a/ors-api/src/main/java/org/heigit/ors/api/responses/routing/geojson/GeoJSONGeometry.java b/ors-api/src/main/java/org/heigit/ors/api/responses/routing/geojson/GeoJSONGeometry.java
@@ -0,0 +1,48 @@
+/*  This file is part of Openrouteservice.
+ *
+ *  Openrouteservice is free software; you can redistribute it and/or modify it under the terms of the
+ *  GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1
+ *  of the License, or (at your option) any later version.
+
+ *  This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ *  without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ *  See the GNU Lesser General Public License for more details.
+
+ *  You should have received a copy of the GNU Lesser General Public License along with this library;
+ *  if not, see <https://www.gnu.org/licenses/>.
+ */
+
+package org.heigit.ors.api.responses.routing.geojson;
+
+import com.fasterxml.jackson.annotation.JsonAnyGetter;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
+import org.json.simple.JSONObject;
+
+public class GeoJSONGeometry {
+
+    private final JSONObject json;
+
+    public GeoJSONGeometry(String type, Object coordinates) {
+        this.json = new JSONObject();
+        this.json.put("type", type);
+        this.json.put("coordinates", coordinates);
+    }
+
+    @Schema(description = "The geometry type", example = "LineString")
+    @JsonProperty("type")
+    public String getType() {
+        return (String) json.get("type");
+    }
+
+    @Schema(description = "The coordinates array for the geometry")
+    @JsonProperty("coordinates")
+    public Object getCoordinates() {
+        return json.get("coordinates");
+    }
+
+    @JsonAnyGetter
+    public JSONObject getJson() {
+        return json;
+    }
+}
diff --git a/ors-api/src/main/java/org/heigit/ors/api/responses/routing/geojson/GeoJSONIndividualRouteResponse.java b/ors-api/src/main/java/org/heigit/ors/api/responses/routing/geojson/GeoJSONIndividualRouteResponse.java
@@ -19,17 +19,17 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 import io.swagger.v3.oas.annotations.media.Schema;
 import org.heigit.ors.api.requests.routing.RouteRequest;
-import org.heigit.ors.api.responses.routing.json.JSONBasedIndividualRouteResponse;
+import org.heigit.ors.api.responses.routing.JSONBasedIndividualRouteResponse;
 import org.heigit.ors.api.responses.routing.json.JSONSegment;
 import org.heigit.ors.exceptions.StatusCodeException;
 import org.heigit.ors.geojson.GeometryJSON;
 import org.heigit.ors.routing.RouteResult;
-import org.json.simple.JSONObject;
 
 import java.util.List;
 import java.util.Map;
 
 public class GeoJSONIndividualRouteResponse extends JSONBasedIndividualRouteResponse {
+    @Schema(description = "A GeoJSON 'Feature' representing a single route returned from the request")
     @JsonProperty("type")
     public final String type = "Feature";
 
@@ -45,21 +45,20 @@ public GeoJSONIndividualRouteResponse(RouteResult routeResult, RouteRequest requ
         properties = new GeoJSONSummary(routeResult, segments, extras, this.includeElevation, this.isPtRequest, constructLegs(routeResult));
     }
 
-    @Schema(implementation = JSONObject.class, description = "The geometry of the route. For GeoJSON route responses this is a JSON LineString.")
+    @Schema(description = "The geometry of the route. For GeoJSON route responses this is a JSON LineString.")
     @JsonProperty("geometry")
-    public JSONObject getGeometry() {
-        JSONObject geoJson = new JSONObject();
-        geoJson.put("type", "LineString");
-        geoJson.put("coordinates", GeometryJSON.toJSON(this.routeCoordinates, includeElevation));
-
-        return geoJson;
+    public GeoJSONGeometry getGeometry() {
+        return new GeoJSONGeometry("LineString", GeometryJSON.toJSON(this.routeCoordinates, includeElevation));
     }
 
+    @JsonProperty("properties")
+    @Schema(description = "Contains routing segments with navigation steps, overall route summary, waypoint indices, and related metadata.")
     public GeoJSONSummary getProperties() {
         return properties;
     }
 
     @JsonProperty("bbox")
+    @Schema(description = "Bounding box that covers all returned routes", example = "[49.414057, 8.680894, 49.420514, 8.690123]")
     @JsonInclude(JsonInclude.Include.NON_EMPTY)
     public double[] getBBox() {
         return bbox.getAsArray();
diff --git a/ors-api/src/main/java/org/heigit/ors/api/responses/routing/geojson/GeoJSONRouteResponse.java b/ors-api/src/main/java/org/heigit/ors/api/responses/routing/geojson/GeoJSONRouteResponse.java
@@ -33,6 +33,7 @@
 import java.util.List;
 
 public class GeoJSONRouteResponse extends RouteResponse {
+    @Schema(description = "A GeoJSON 'FeatureCollection' representing the routes returned from the request")
     @JsonProperty("type")
     public final String type = "FeatureCollection";
 
@@ -64,8 +65,8 @@ public GeoJSONRouteResponse(RouteResult[] routeResults, RouteRequest request, Sy
     }
 
     @JsonProperty("features")
-    public List getRoutes() {
-        return routeResults;
+    public GeoJSONIndividualRouteResponse[] getRoutes() {
+        return routeResults.toArray(new GeoJSONIndividualRouteResponse[0]);
     }
 
     @JsonProperty("metadata")
diff --git a/ors-api/src/main/java/org/heigit/ors/api/responses/routing/geojson/GeoJSONSummary.java b/ors-api/src/main/java/org/heigit/ors/api/responses/routing/geojson/GeoJSONSummary.java
diff --git a/ors-api/src/main/java/org/heigit/ors/api/responses/routing/json/JSONIndividualRouteResponse.java b/ors-api/src/main/java/org/heigit/ors/api/responses/routing/json/JSONIndividualRouteResponse.java
diff --git a/ors-api/src/main/java/org/heigit/ors/api/responses/routing/json/JSONRouteResponse.java b/ors-api/src/main/java/org/heigit/ors/api/responses/routing/json/JSONRouteResponse.java
diff --git a/ors-api/src/main/java/org/heigit/ors/api/responses/routing/json/JSONSummary.java b/ors-api/src/main/java/org/heigit/ors/api/responses/routing/json/JSONSummary.java
