# πŸš— Routing API The **BeMap Routing API** lets you compute vehicle routes, optimize trips with multiple stops, generate isochrones (travel-time zones), and calculate matrices between locations. ## πŸ“Œ Use Cases - **Standard route A to B** - **Optimized delivery trip with 5 stops** - **Show reachable areas in 15min (isochrone)** - **Avoid toll roads with truck restrictions** - **Estimate toll cost and distance for a bus** ## πŸ”§ Endpoint ``` POST /bgis/service/routing/1.0 ``` Environments: - `https://bemap-beta.benomad.com` - `https://bemap-preprod.benomad.com` - `https://bemap-prod.benomad.com` ## πŸ“₯ Example: Passenger Car Route from Paris to Brussels ```json { "geoserver": "here", "routingMode": "MODE_VIAS", "outputLanguage": "fr", "destinations": [ { "coordinateSat": { "lon": 2.32158, "lat": 48.86533 } }, { "coordinateSat": { "lon": 4.35655, "lat": 50.8447 } } ], "options": [ "POLYLINE" ], "routingVehicleProfile": { "transportMode": "CAR" } } ``` ## πŸ“₯ Example: Truck Avoiding Toll Roads from Brussels to Paris ```json { "routingMode": "MODE_VIAS", "outputLanguage": "fr", "destinations": [ { "coordinateSat": { "lon": 4.35655, "lat": 50.8447 } }, { "coordinateSat": { "lon": 2.32158, "lat": 48.86533 } } ], "options": [ "POLYLINE" ], "routingCriterias": [ "AVOID_TOLLS" ], "routingVehicleProfile": { "transportMode": "TRUCK" } } ``` ## 🧠 Routing Modes The `routingMode` field defines how the route will be calculated, depending on how many origin and destination points you provide, and the type of result you expect. **Default:** `MODE_VIAS`. ```json "routingMode": "MODE_VIAS" ``` | Mode | Description | | --- | --- | | [`MODE_VIAS`](/api-reference/routing/tutorial/routing_mode#mode_vias) | **Standard A ➝ B ➝ C route.**Use this for a basic route with optional waypoints.πŸ“Œ *Example:* From Lyon ➝ Vienne ➝ Valence | | [`MODE_1_TO_N`](/api-reference/routing/tutorial/routing_mode#mode_1_to_n) | **One origin to many destinations.**Computes individual routes from a single point to a list of target points.πŸ“Œ *Example:* From Lyon ➝ Marseille, Lyon ➝ Nice, Lyon ➝ Paris | | [`MODE_N_TO_1`](/api-reference/routing/tutorial/routing_mode#mode_n_to_1) | **Many origins to one destination.**Computes individual routes from multiple points to a single endpoint.πŸ“Œ *Example:* From Annecy ➝ Lyon, Grenoble ➝ Lyon, Dijon ➝ Lyon | | [`MODE_N_TO_N`](/api-reference/routing/tutorial/routing_mode#mode_n_to_n) | **Full NxN matrix.**Calculates all possible routes between each pair of points in a list.πŸ“Œ *Example:* A full delivery coverage from every warehouse to every client | | [`MODE_MATRIX`](/api-reference/routing/tutorial/routing_mode#mode_matrix) | **Distance/time matrix.**Returns a matrix of durations (in seconds), distances (in meters), or energy consumption (in Wh) between origin(s) and destination(s).πŸ“Œ *Example:* How long does it take from each depot to each delivery point? | | [`MODE_ISOCHRONE`](/api-reference/routing/tutorial/routing_mode#mode_isochrone) | **Reachable zone polygon.**Returns an area that can be reached within a given time, distance or energy.πŸ”Ή *With 1 point:* Reachable area starting from Lyon in 30 min.πŸ”Ή *With 2 points:* Reachable area starting from Lyon and ending in Valence, within a time or energy limit. Useful for EV planning. | πŸ‘‰ For detailed examples and usage, [check out the tutorial](/api-reference/routing/tutorial/routing_mode#routing_mode_tutorial). ## βš™οΈ Routing Criterias Comma-separated list (e.g. `"AVOID_TOLLS,FASTEST"`): - [`FASTEST`](/api-reference/routing/tutorial/routing_criterias#criteria_fastest) *(default)*: Find the route which optimizes travel time. - [`SHORTEST`](/api-reference/routing/tutorial/routing_criterias#criteria_shortest): Find the route which optimizes travel distance. - [`AVOID_TOLLS`](/api-reference/routing/tutorial/routing_criterias#criteria_avoid_tolls): Finds a route which avoids tolls. - [`AVOID_FERRIES`](/api-reference/routing/tutorial/routing_criterias#criteria_avoid_ferries): Finds a route which avoids ferries. - [`AVOID_MOTORWAYS`](/api-reference/routing/tutorial/routing_criterias#criteria_avoid_motorways): Finds a route which avoids motorways. - [`AVOID_UNPAVED`](/api-reference/routing/tutorial/routing_criterias#criteria_avoid_unpaved): Finds a route which avoids unpaved roads. - [`AVOID_CROSSING_BORDER`](/api-reference/routing/tutorial/routing_criterias#criteria_avoid_crossing_border): Finds a route which avoids country border crossings (only when all coordinates are in a same country) - [`CARPOOL`](/api-reference/routing/tutorial/routing_criterias#criteria_carpool): Finds a route which avoids roads reserved to carpooling. - [`ECO_ENERGY`](/api-reference/routing/tutorial/routing_criterias#criteria_eco_energy): Find the route which optimizes travel energy consumption. ```json "routingCriterias": [ "FASTEST", "SHORTEST", "AVOID_FERRIES", "AVOID_MOTORWAYS", "AVOID_TOLLS", "AVOID_UNPAVED", "AVOID_CROSSING_BORDER", "CARPOOL", "ECO_ENERGY" ], ``` πŸ‘‰ For detailed examples and usage, [check out the tutorial](/api-reference/routing/tutorial/routing_criterias#routing_criteria_tutorial) ## πŸš› Vehicle Profile (routingVehicleProfile) ```json "routingVehicleProfile": { "transportMode": "CAR", "routingVehicleFeature": { "maxSpeed": 90, "vehicleWeight": 1500, "emissionClass": "EURO6" } } ``` | Field | Description | | --- | --- | | [`transportMode`](/api-reference/routing/tutorial/routing_mode#routing_vehicle_transport_mode) | Defines the transportation mode (e.g., CAR, TRUCK, PEDESTRIAN).Default is `CAR`, except for Traceroute where it’s `EMERGENCY`.This affects routing due to map data constraints like turn restrictions, traffic directions, and accessibility.**Available values:**- `BICYCLE`: Bicycle- `CAR`: Passenger car- `EMERGENCY`: Emergency vehicle- `MOTORCYCLE`: Motorcycle- `PEDESTRIAN`: Pedestrian- `PUBLIC_BUS`: Public bus- `TAXI`: Taxi- `TRUCK`: Truck | | [`routingVehicleFeature`](/api-reference/routing/tutorial/routing_mode#routing_vehicle_feature_tutorial) | Defines physical, legal and toll characteristics of the vehicle. Affects routing and toll calculation. | | [`routingEnergyVehicleFeature`](/api-reference/routing/tutorial/routing_mode#routing_energy_vehicle_feature_tutorial) | For EV routing (optional) | | [`maxSpeeds`](/api-reference/routing/tutorial/routing_mode#routing_vehicle_max_speeds) | This field lets you tell the routing engine how fast your vehicle is allowed to go (in km/h).You can set:- One speed for route calculation (`CAL`)- Another for arrival time estimation (`ETA`)- Or one value for both (`ALL`) | | [`routingSpeedPonderations`](/api-reference/routing/tutorial/routing_mode#routing_speed_ponderation_tutorial) | Adjust road speed classes | πŸ‘‰ For detailed examples and usage, [check out the tutorial](/api-reference/routing/tutorial/routing_mode#routing_vehicle_profile_tutorial) ## πŸ”„ Optimization Options (routingMode) ```json "options": [ "OPTIMIZED_TRIP", "OPTIMIZED_TRIP_CLOSE" ] ``` - [`OPTIMIZED_ROUTE_FOR_CHARGING_STATION`](/api-reference/routing/tutorial/routing_optimized#optimize_route_for_charging_station): Optimizes electric vehicles charges. Checks if the route is feasible with the. current vehicle profile and the given smart routing profile. If not, the method will try to find optimal (according to the criteria used to compute the route) charging stops. - [`OPTIMIZED_TRIP`](/api-reference/routing/tutorial/routing_optimized#optimize_trip): Optimized trip (preserve start/stop) - [`OPTIMIZED_TRIP_CLOSE`](/api-reference/routing/tutorial/routing_optimized#optimize_trip_close): Return to start by closing the loop - [`OPTIMIZED_TRIP_ROUND`](/api-reference/routing/tutorial/routing_optimized#optimize_trip_round): Return to start but don't close loop - [`OPTIMIZED_TRIP_UNDEFSTOP`](/api-reference/routing/tutorial/routing_optimized#optimize_trip_undefstop): Optimized trip with flexible stop πŸ‘‰ For detailed examples and usage, [check out the tutorial](/api-reference/routing/tutorial/routing_mode#routing_optimized_tutorial) ## ⚑ Energy Vehicle (routingEnergyVehicleFeature) | Field | Type | Description | | --- | --- | --- | | `auxConsumption` | int | Instantaneous consumption of auxiliary equipment (in W) | | `batCapacity` | double | Battery capacity (in kWh) | | `crr` | double | Rolling resistance coefficient (T/T) | | `dryWeight` | int | Vehicle’s dry weight (in kg) | | `energyLoad` | double | Initial battery charge (in kWh) | | `engineEfficiency` | double | Engine-to-wheel efficiency ratio (dimensionless) | | `extTemp` | float | External temperature (in Β°C) | | `maxAccel` | double | Maximum acceleration (in m/sΒ²) | | `maxChargePower` | double | Max AC single-phase charge power (in kW) | | `maxChargePowerAc3` | double | Max AC three-phase charge power (in kW) | | `maxChargePowerDc` | double | Max DC charge power (in kW) | | `maxDecel` | double | Maximum deceleration (in m/sΒ²) | | `payload` | int | Additional load weight (in kg) | | `regenerativeBraking` | boolean | Whether vehicle uses regenerative braking | | `scx` | double | SCx = frontal area drag coefficient (in mΒ²) | πŸ‘‰ For detailed examples and usage, [check out the tutorial](/api-reference/routing/tutorial/routing_mode#routing_energy_vehicle_feature_tutorial) ## Routing Speed Coefficient (routingSpeedPond) | Field | Optional | Type | Description | | --- | --- | --- | --- | | `factor` | ❌ | float | Speed coefficient. A value under 1 reduces speed (e.g. 0.8), over 1 increases speed (e.g. 1.3). Default: `1`. | | `level` | ❌ | int | Road level: `0` (all), `1` (main), `2` (secondary), `3` (tertiary), `4` (fourth). | | `pondType` | βœ… | string | Ponderation type. One of: `ALL` (default), `CAL`, `ETA`. | | `roadType` | βœ… | string | Road type. One of: `ALL`, `DEFAULT`, `FERRY`, `MOTORWAY`, `PEDESTRIAN`, `ROUNDABOUNT`, `SLIPROAD`. | πŸ‘‰ For detailed examples and usage, [check out the tutorial](/api-reference/routing/tutorial/routing_mode#routing_speed_ponderation_tutorial) ## 🚐 Vehicle Feature Fields (routingVehicleFeature) | Field | Optional | Description | | --- | --- | --- | | `weight` | βœ… | Total weight in tens of metric tons. Affects route calculation. Type: `int`. | | `width` | βœ… | Width of vehicle in centimeters. Affects route calculation. Type: `int`. | | `height` | βœ… | Height of vehicle in centimeters. Affects route calculation. Physical restriction. Type: `int`. | | `length` | βœ… | Length of vehicle in centimeters. Affects route calculation. Physical restriction. Type: `int`. | | `onlyPhysical` | βœ… | Defines if physical constraints are ignored outside bridges and tunnels. `false` by default. Affects route calculation. Type: `boolean`. | | `nbTrailer` | βœ… | Vehicle's number of trailers (-1: not defined, 0: no trailer). Affects route calculation. Legal restriction. Type: `int`. | | `adrTunnelCategory` | βœ… | ADR tunnel category defines all supported ADR (EU only, European Agreement concerning the International Carriage of Dangerous Goods by Road). Affects route calculation. **Available values:** - `CAT_B`- `CAT_C`- `CAT_D`- `CAT_E`- `NONE` | | `axleWeight` | βœ… | Axle weight in tens of metric tons, i.e.: `12` = 1.2t. Affects route calculation. Legal and physical restrictions. Type: `int`. | | `hazardousMaterials` | βœ… | Hazardous materials carried by the vehicle. Affects route calculation. Legal restriction. **Available values:**- `ALL`- `EXPLOSIVE`- `NONE`- `TUNNEL_CAT_B`- `TUNNEL_CAT_B1000C`- `TUNNEL_CAT_BD`- `TUNNEL_CAT_BE`- `TUNNEL_CAT_C`- `TUNNEL_CAT_C5000D`- `TUNNEL_CAT_CD`- `TUNNEL_CAT_CE`- `TUNNEL_CAT_D`- `TUNNEL_CAT_DE`- `TUNNEL_CAT_E`- `US_CORROSIVE`- `US_EXPLOSIVES`- `US_FLAM`- `US_FLAM_SOL`- `US_GAS`- `US_ORGANIC`- `US_OTHER`- `US_PIH`- `US_POISON`- `US_RADIO_ACTIVE`- `WATER` | | `caravan` | βœ… | Defines if the vehicle has a caravan. Affects toll calculation. `UNDEFINED` by default. **Available values:** - `NO`- `UNDEFINED`- `YES` | | `cial` | βœ… | Defines if vehicle is a commercial vehicle. Affects toll calculation. `UNDEFINED` by default. **Available values:**- `NO`- `UNDEFINED`- `YES` | | `disEquipped` | βœ… | Defines if vehicle is equipped for disabled people. Affects toll calculation. `UNDEFINED` by default. **Available values:**- `NO`- `UNDEFINED`- `YES` | | `emissionClass` | βœ… | Defines vehicle's emission type (optional). Affects toll calculation. **Available values:**- `ELECTRIC`- `EURO0`- `EURO1`- `EURO2`- `EURO2_PRC`- `EURO3`- `EURO3_PRC`- `EURO4`- `EURO5`- `EURO6`- `EURO6_CO2_1`- `EURO6_CO2_2`- `EURO6_CO2_3`- `EURO6_CO2_4`- `EURO6_CO2_5`- `EURO_EEV`- `MAX`- `UNDEFINED` | | `hov` | βœ… | Defines if vehicle is a High Occupancy Vehicle (USA only). Affects toll calculation. `UNDEFINED` by default. **Available values:**- `NO`- `UNDEFINED`- `YES` | | `hybrid` | βœ… | Defines if vehicle has a hybrid engine. Affects toll calculation. `UNDEFINED` by default. **Available values:**- `NO`- `UNDEFINED`- `YES` | | `nbPassengers` | βœ… | Defines the number of passengers (optional). Affects toll calculation. Type: `int`. | | `nbTires` | βœ… | Defines the number of tires (optional). Affects toll calculation. Type: `int`. | | `nbTrailAxles` | βœ… | Defines the number of axles of the trailer (optional). Affects toll calculation. Type: `int`. | | `nbVehAxles` | βœ… | Defines the number of axles of the vehicle (optional). Affects toll calculation. Type: `int`. | | `pollMin` | βœ… | Defines if vehicle has minimal pollution. Affects toll calculation. `UNDEFINED` by default. **Available values:** `NO`, `UNDEFINED`, `YES` | | `tollTransportCategory` | βœ… | Defines the toll vehicle category. Affects toll calculation. `UNDEFINED` by default. **Available values:**- `AUTO` - `BUS` - `DLV_TRUCK` - `MINIBUS` - `MOTOR_HOME` - `MOTORCYCLE` - `PICK_UP` - `SIDECAR` - `SNOWMOBILE` - `TRACTOR` - `TRICYCLE` - `TRUCK` - `UNDEFINED` | | `trailHeight` | βœ… | Trailer's height in centimeters. Affects toll calculation. Type: `int`. | | `vehHeight` | βœ… | Vehicle's height in centimeters. Affects toll calculation. Type: `int`. | | `vehWeight` | βœ… | Vehicle's weight in tens of tons. Affects toll calculation. Type: `int`. | πŸ‘‰ For detailed examples and usage, [check out the tutorial](/api-reference/routing/tutorial/routing_mode#routing_vehicle_feature_tutorial) ## πŸ“‘ EVENT Options – Route Segment Events The `EVENT` option enriches the routing response by including detailed **per-segment information** about the computed path. This is particularly useful for applications needing granular insight into road conditions, elevation, traffic, costs, and more. Activating `EVENT` adds an array of event entries to the response. Each entry corresponds to a segment of the route and can include various attributes depending on the sub-options (`EVT_XXXX`) selected. ## πŸ“‹ List of `EVENT` Sub-options The `EVENT` option enriches the routing response with detailed road segment information. Below are its sub-options: ```json "options": [ "EVENT", "EVT_ELEVATION2", "EVT_TRAFFIC" ] ``` | Option | Description | | --- | --- | | `EVENT` | Enables structure of events along the route. Returns segments with metadata such as distance, time, and country code. | | [`EVT_DUPLICATE_FILTER`](/api-reference/routing/tutorial/routing_event#evt_duplicate_filter) | Filters repeated values to avoid duplication across unchanged segments. | | [`EVT_DURATION`](/api-reference/routing/tutorial/routing_event#evt_duration) | Adds estimated travel duration of each segment (in seconds). | | [`EVT_ELEVATION2`](/api-reference/routing/tutorial/routing_event#evt_elevation2) | Returns elevation data in one entry: altitude at the beginning and end of the segment. | | [`EVT_ENCODED_POLYLINE`](/api-reference/routing/tutorial/routing_event#evt_polyline) | Returns polyline geometry encoded. | | [`EVT_ENERGY_CONSUMPTION`](/api-reference/routing/tutorial/routing_event#evt_energy_consumption) | Estimates energy usage. Requires `routingEnergyVehicleFeature`. Returns autonomy limit (`energyEndOfAutonomyAt`, `energyEndOfAutonomyCoord`). | | [`EVT_ENERGY_CONSUMPTION_SAMPLE`](/api-reference/routing/tutorial/routing_event#evt_energy_consumption_sample) | Returns sampled energy data every second (dist, speed, slope, pos, etc.). Requires `routingEnergyVehicleFeature`. | | [`EVT_ENTRY_VALUE_AS_OBJECT`](/api-reference/routing/tutorial/routing_event#evt_entry_value_as_object) | Outputs entries as JSON objects instead of strings. | | [`EVT_GEOELEMENT_TYPE`](/api-reference/routing/tutorial/routing_event#evt_geoelement_type) | Includes road classification: `FOURTH_ROAD`, `TERTIARY_ROAD`, `MOTORWAY`, `FERRY`, etc. | | [`EVT_LENGTH`](/api-reference/routing/tutorial/routing_event#evt_length) | Adds segment length in meters. | | [`EVT_OBJECTID_BASE64`](/api-reference/routing/tutorial/routing_event#evt_objectid_base64) | Adds a base64 Object ID related to the map release. | | [`EVT_POLYLINE`](/api-reference/routing/tutorial/routing_event#evt_polyline) | Returns unencoded polyline geometry. | | [`EVT_PROHIBITED_DRIVING`](/api-reference/routing/tutorial/routing_event#evt_prohibited_driving) | Shows prohibited driving data (e.g. wrong direction, blocked passage). | | [`EVT_ROAD_FEATURE`](/api-reference/routing/tutorial/routing_event#evt_road_feature) | Adds road details: speed limit, number of lanes, tunnels, bridges, etc. | | [`EVT_ROUTESHEET`](/api-reference/routing/tutorial/routing_event#evt_routesheet) | Adds turn-by-turn route sheet instructions in the event structure. | | [`EVT_SEGMENT_INFO`](/api-reference/routing/tutorial/routing_event#evt_segment_info) | Returns segment ID and whether it's traversed in reverse. | | [`EVT_TAX_COST`](/api-reference/routing/tutorial/routing_event#evt_tax_cost) | Returns tax cost. Requires specific vehicle profile and map data. | | [`EVT_TOLL_COST`](/api-reference/routing/tutorial/routing_event#evt_toll_cost) | Returns toll cost. Requires specific vehicle profile and map data. | | [`EVT_TRAFFIC`](/api-reference/routing/tutorial/routing_event#evt_traffic) | Adds real-time traffic data: jam factor, speed, etc. Does NOT affect routing. | | [`EVT_TRAFFIC_HISTORICAL`](/api-reference/routing/tutorial/routing_event#evt_traffic_historical) | (Beta) Historical traffic based on past departure time. Does NOT affect routing. | | [`EVT_TRAFFIC_SIGNS`](/api-reference/routing/tutorial/routing_event#evt_signs) | Displays traffic signs info (e.g. STOP, YIELD, pedestrian crossing). | | [`EVT_WAYPOINTS`](/api-reference/routing/tutorial/routing_event#evt_waypoints) | Adds route waypoints with coordinates and metadata. | πŸ‘‰ For detailed examples and usage, [check out the tutorial](/api-reference/routing/tutorial/routing_mode#routing_event_tutorial) ## 🧭 Tips for Non-Developers - You can use Postman to test routes visually. - The more fields you provide, the more precise the results. - Start simple (origin/destination + mode) and add filters. ## πŸ”— API Playground You can test this API endpoint directly in our dedicated BeMap documentation environment. πŸ‘‰ [Go to BeMap API Playground](https://bemap-preprod.benomad.com/bgis/documentation/#subpage-rest_1_0_0-examples-routing-service-v1_0_0.md)