feat: Feature Store

docs/.vitepress/config.js

@@ -146,7 +146,8 @@ export default withMermaid(defineVersionedConfig({
                                         {text: 'Isochrones', link: '/api-reference/endpoints/isochrones/'},
                                         {text: 'Matrix', link: '/api-reference/endpoints/matrix/'},
                                         {text: 'Snapping', link: '/api-reference/endpoints/snapping/'},
-                                        {text: 'Export (not live)', link: '/api-reference/endpoints/export/'},
+                                        {text: 'Export', link: '/api-reference/endpoints/export/'},
+                                        {text: 'Matching', link: '/api-reference/endpoints/matching/'},
                                         {text: 'Health (not live)', link: '/api-reference/endpoints/health/'},
                                         {text: 'Status (not live)', link: '/api-reference/endpoints/status/'},
                                         {text: 'POI', link: '/api-reference/endpoints/poi/'},

docs/api-reference/endpoints/export/index.md

@@ -1,15 +1,5 @@
----
-cbf: [2,4,5]
----
-
 # Export Endpoint
 
-:::warning NOTE
-This endpoint is not available in the public API,
-but you can use it when running an own instance of openrouteservice.
-You can easily create requests with the [swagger-ui](/api-reference/index.md#swagger-ui).
-:::
-
 Export the base graph for different modes of transport.
 
 In the request, the desired routing profile is specified as the penultimate path parameter, and the desired format as

docs/api-reference/endpoints/index.md

@@ -13,12 +13,13 @@ Openrouteservice offers a set of endpoints for different spatial purposes:
 * [Isochrones Service](isochrones/index.md): Obtain areas of reachability from given locations
 * [Matrix Service](matrix/index.md): Obtain one-to-many, many-to-one and many-to-many matrices for time and distance
 * [Snapping Service](snapping/index.md): Snap coordinates to the road network
+* [Export Service](export/index.md): Export the routing graph for different modes of transport
 
 ## Technical Endpoints
 
 Furthermore, there are technical endpoints that are :warning: _not available_ in our live API:
 
-* [Export Service](export/index.md): Export the base graph for different modes of transport
+* [Matching Service](matching/index.md): Match spatial features to the road network
 * [Health Service](health/index.md): Get information on the health of the running openrouteservice instance
 * [Status Service](status/index.md): Get information on the status of the openrouteservice instance
 

docs/api-reference/endpoints/matching/index.md

@@ -0,0 +1,127 @@
+# Matching Endpoint
+
+:::warning NOTE
+This endpoint is not available in the public API, but you can use it when running an own instance of openrouteservice.
+:::
+
+The matching endpoint can be used to match point, linear and polygonal spatial features to the edges of the routing graph representing the street network for a specific means of transportation.
+
+The matching of point geometries is performed by snapping to the nearest edge in the graph, similar to the [snapping endpoint](../snapping/index.md).
+Linear geometries are matched using a Hidden Markov Model (HMM) based map matching algorithm.
+Polygon geometries are matched by intersecting them with the edges of the routing graph.
+
+The routing profile has to be specified as path parameter.
+The geometric `features` for matching are provided formatted as a GeoJSON `FeatureCollection` object.
+
+The endpoint returns a JSON containing a list of matched edge ids.
+
+:::warning HINT
+The returned edge ids are the internal ids of the routing graph and can be used for further processing, e.g. with the [export endpoint](../export/index.md). They shall not be confused with OpenStreetMap way ids.
+:::
+
+
+## Sample query and result
+
+Request:
+```shell
+curl -X 'POST' \
+  'http://localhost:8082/ors/v2/match/driving-car' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "features": {
+    "type": "FeatureCollection",
+    "features": [
+      {
+        "type": "Feature",
+        "properties": {
+          "type": "bridge"
+        },
+        "geometry": {
+          "type": "Point",
+          "coordinates": [
+            8.685990,
+            49.40267
+          ]
+        }
+      },
+      {
+        "type": "Feature",
+        "geometry": {
+          "type": "LineString",
+          "coordinates": [
+            [
+              8.684963,
+              49.40252
+            ],
+            [
+              8.684932,
+              49.40199
+            ],
+            [
+              8.685466,
+              49.40126
+            ],
+            [
+              8.686026,
+              49.40092
+            ]
+          ]
+        }
+      },
+      {
+        "type": "Feature",
+        "geometry": {
+          "type": "Polygon",
+          "coordinates": [
+            [
+              [
+                8.684143,
+                49.40336
+              ],
+              [
+                8.684779,
+                49.40302
+              ],
+              [
+                8.685354,
+                49.40340
+              ],
+              [
+                8.684697,
+                49.40380
+              ],
+              [
+                8.684143,
+                49.40336
+              ]
+            ]
+          ]
+        }
+      }
+    ]
+  }
+}'
+```
+
+Response:
+```json
+{
+  "edge_ids":[
+    7472,
+    11185,
+    2242,
+    5908,
+    741,
+    5913,
+    5914,
+    11548,
+    7471
+  ],
+  "graph_timestamp":"2025-11-17T14:18:55Z"
+}
+```
+
+:::warning NOTE
+Internal edge ids are subject to change between graph rebuilds.
+:::

docs/api-reference/error-codes.md

@@ -16,7 +16,6 @@ The following table describes the supported HTTP status codes.
 | 503              | The server is currently unavailable due to overload or maintenance.                                                                        |
 
 
-
 ## Internal Error Codes
 
 The following sections describes the list of possible internal error codes that might be provided by different openrouteservice
@@ -133,3 +132,17 @@ Endpoints.
 |    8010    | Point not found.                                      |
 |    8011    | Unknown parameter.                                    |
 |    8099    | Unknown internal error.                               |
+
+### Matching API
+
+[//]: # (keep in sync with org.heigit.ors.matching.MatchingErrorCodes)
+
+| Error Code | Description                                           |
+|:----------:|-------------------------------------------------------|
+|    9000    | Unable to parse JSON request.                         |
+|    9001    | Required parameter is missing.                        |
+|    9002    | Invalid parameter format.                             |
+|    9003    | Invalid parameter value.                              |
+|    9007    | Unsupported export format.                            |
+|    9011    | Unknown parameter.                                    |
+|    9099    | Unknown internal error.                               |

ors-api/src/main/java/org/heigit/ors/api/config/EndpointsProperties.java

@@ -145,6 +145,7 @@ public static class EndpointSnapProperties {
     @Setter(AccessLevel.PACKAGE)
     public static class EndpointMatchProperties {
         private boolean enabled;
+        private int maximumSearchRadius;
         private String attribution;
     }
 

ors-api/src/main/java/org/heigit/ors/api/controllers/MatchingAPI.java

@@ -15,6 +15,10 @@
 
 package org.heigit.ors.api.controllers;
 
+import com.fasterxml.jackson.databind.exc.InvalidDefinitionException;
+import com.fasterxml.jackson.databind.exc.InvalidFormatException;
+import com.fasterxml.jackson.databind.exc.MismatchedInputException;
+import com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.media.Content;
@@ -28,16 +32,17 @@
 import org.heigit.ors.api.responses.matching.MatchingResponse;
 import org.heigit.ors.api.services.MatchingService;
 import org.heigit.ors.common.EncoderNameEnum;
-import org.heigit.ors.exceptions.MissingParameterException;
-import org.heigit.ors.exceptions.ParameterValueException;
-import org.heigit.ors.exceptions.StatusCodeException;
+import org.heigit.ors.exceptions.*;
 import org.heigit.ors.matching.MatchingErrorCodes;
 import org.heigit.ors.matching.MatchingRequest;
 import org.json.simple.JSONObject;
+import org.springframework.core.convert.ConversionFailedException;
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
+import org.springframework.http.converter.HttpMessageConversionException;
+import org.springframework.http.converter.HttpMessageNotReadableException;
 import org.springframework.web.bind.annotation.*;
 
 @RestController
@@ -131,6 +136,28 @@ public ResponseEntity<String> postMatching(@Parameter(description = "Specifies t
         return new ResponseEntity<>(jsonResponse.toJSONString(), headers, HttpStatus.OK);
     }
 
+    @ExceptionHandler({HttpMessageNotReadableException.class, HttpMessageConversionException.class, Exception.class})
+    public ResponseEntity<Object> handleReadingBodyException(final Exception e) {
+        final Throwable cause = e.getCause();
+        if (cause instanceof UnrecognizedPropertyException exception) {
+            return errorHandler.handleUnknownParameterException(new UnknownParameterException(MatchingErrorCodes.UNKNOWN_PARAMETER, exception.getPropertyName()));
+        } else if (cause instanceof InvalidFormatException exception) {
+            return errorHandler.handleStatusCodeException(new ParameterValueException(MatchingErrorCodes.INVALID_PARAMETER_FORMAT, exception.getValue().toString()));
+        } else if (cause instanceof InvalidDefinitionException exception) {
+            return errorHandler.handleStatusCodeException(new ParameterValueException(MatchingErrorCodes.INVALID_PARAMETER_VALUE, exception.getPath().get(0).getFieldName()));
+        } else if (cause instanceof MismatchedInputException exception) {
+            return errorHandler.handleStatusCodeException(new ParameterValueException(MatchingErrorCodes.INVALID_PARAMETER_FORMAT, exception.getPath().get(0).getFieldName()));
+        } else if (cause instanceof ConversionFailedException exception) {
+            return errorHandler.handleStatusCodeException(new ParameterValueException(MatchingErrorCodes.INVALID_PARAMETER_VALUE, (String) exception.getValue()));
+        } else {
+            // Check if we are missing the body as a whole
+            if (e.getLocalizedMessage() != null && e.getLocalizedMessage().startsWith("Required request body is missing")) {
+                return errorHandler.handleStatusCodeException(new EmptyElementException(MatchingErrorCodes.MISSING_PARAMETER, "Request body could not be read"));
+            }
+            return errorHandler.handleGenericException(e);
+        }
+    }
+
     @ExceptionHandler(StatusCodeException.class)
     public ResponseEntity<Object> handleException(final StatusCodeException e) {
         return errorHandler.handleStatusCodeException(e);