The Energymodule REST API
The API takes input data describing the route, the vehicle, and various calculation configurations, and returns estimated driving speed, energy consumption and emissions. Results can be detailed (for each 20-meter segment along the route), aggregated to road links, or totals for the entire route.
Both the input (for endpoints accepting any input) and output format is JSON. The exact structure of the JSON input and output depends on the endpoint.
The API is available at https://emapi.sintef.no/api/v1, with Swagger documentation available here.
Authentication
In order to use the API, you need to provide an authentication key in the AuthKey header field. An authentication key can be obtained by contacting energimodul@sintef.no.
For example:
Basic calculation
In order to run a calculation, you must provide at least a vehicle and a route. There are multiple ways of defining both, as shown in the sections below. The following example is the most basic calculation, using a vehicle defined in the online database, and a route defined by its start and end coordinates:
Calculation response
The default calculation response aggregates results over the entire route. The code block below shows an example of a calculation response with explanations for each value.
The response can be expanded with more details; see Response specification further down.
Vehicle definitions
There are multiple ways of defining a vehicle:
- Using a pre-defined vehicle from the online database
- Using a pre-defined vehicle with modifications
- Defining the entire vehicle in the request
Pre-defined vehicle from the online database
When using a pre-defined vehicle, the vehicle definition must be the vehicle's UUID prefixed by "web:". The SINTEF vehicles have human readable UUIDs, while vehicles created by others (for now, at least) have randomly generated UUIDs. The example below shows how to calculate using the average electrical private vehicle.
A full list of pre-defined vehicles can be seen on the Vehicles page.
Pre-defined vehicle with modifications
You can also provide the web:UUID inside a vehicle definition object, and override the wanted properties.
Defining the entire vehicle in the request
Or you can provide the entire vehicle definition as part of the request.
Route definitions
Waypoints
A route can be defined using two or more waypoints. The Energymodule will find the shortest route between these waypoints using a simple routing algorithm. By default, the waypoints are defined in WGS84, or EPSG:4326.
Waypoints in another coordinate system
By default, the waypoints are defined in WGS84, or EPSG:4326 (lat/lng). The API currently supports all coordinate systems supported by ProjNet.SRID. If you are providing coordinates in another coordinate system, or want the output in another coordinate system, you can change the behaviour by setting sourceSrid and outputSrid, respectively.
Public transport stops (Norway only)
Routes can also be provided as Stops or Quays from the National Stop Register by defining the route as a stopIds array. The public transport stops will be translated into coordinates (using the Stop's/Quay's centroid), and then the Energymodule will pick the shortest route in the same manner as when using waypoints.
Manual link definitions
In order to have full control over the input data, a route can also be described using links. A link is a stretch of road (or rail), with homogenous properties (speed limit, road width, lane information, etc). Links are defined with a list of 3D coordinates that describe the geometry as accurately as possible, as well as some road properties that are required for the speed and energy calculations. If there are changes in the road properties in the route, for example, the speed limit changes, you must create a new link to continue with another speed limit. All links will be split into smaller link segments during the calculation, where speed, energy use and emissions will be calculated for each segment.
When using link definitions, coordinates must be defined in the sourceSrid, and will be converted to EPSG:32633 internally. The sourceSrid is 4326 by default, but can be set in the request object like in the coordinate system example above. Links will be split into segments internally, and if linkResults or segmentResults are requested, their coordinates will be converted to the outputSrid before being returned.
Manual segment definitions
A route can also be described using link segments directly. A link segment is the calculation unit in the energy and emission calculations. You can provide coordinates for the start and end points of the segment (x1, y1, z1, x2, y2, z2) for results visualization, but this is not used for anything inside the calculations.
When using segment definitions, coordinates must be defined in the sourceSrid, and will be converted to EPSG:32633 internally. The sourceSrid is 4326 by default, but can be set on the request object like in the coordinate system example above. Links will be split into segments internally, and if linkResults or segmentResults are requested, their coordinates will be converted to the outputSrid before being returned. Since the segments are expected to already contain the information derived from the coordinates, they are not required, but they are useful if you want to show the results on a map.
Other configuration options
In addition to specifying the vehicle and route to be calculated, you can also specify which results you want in the response, how the routing should be performed, and adjust some parameters of the speed and energy calculation.
Response specification
The most basic response includes aggregated speed, energy and emission results. If you want to visualize any of the results along the route in charts or on a map, you can tell the Energymodule to return detailed results on road links or segments (20 meter stretches).
The interactive web calculator uses timing, vehicle, segmentResults and routingDetails in order to visualize the calculation on the map, in charts, and with details about timing, routing and the full vehicle.
- calculationSteps: Include a list of calculation steps with details.
- vehicle: Include the full vehicle definition used in the energy calculation.
- timings: Include timings for the various parts of the calculation.
- version: Include full version information (in addition to the versionCode, which is always included). The full version information can always be retrieved through the /version/[versionCode] API.
- segmentResults: Include all road segments that were processed as part of the energy calculation, with energy, consumption and emission results for each segment.
- linkResults: Include all road links that were processed as part of the energy calculation, with energy, consumption and emission results for each link.
- linkReferences: Include a list of link references for the route that was calculated. Can be used as input for future calls to skip the routing step. Can be useful if you need to know which links that was returned by the automatic routing between waypoints.
- routingDetails: Include detailed information about any performed routing.
- request: Include the exact request. Useful if you need to repeat the calculation later.
Calculation configuration
Here are the most commonly used options:
- driverProfile: "Careful", "Normal" or "Aggressive". Decides how hard the driver accelerates and brakes.
- exceptionMode: "UseSpeedLimit", "Throw", or "UseExceptionSpeed". Decides how the Energymodule should handle links with invalid speed limits or other problems that make it impossible to calculate a target speed.
- exceptionSpeedKmH: The target speed that will be used on links with invalid speed limits or other problems that make it impossible to calculate a target speed if exceptionMode is set to "UseExceptionSpeed".
- minimumSpeedKmH: The lowest possible target speed in the speed calculation. Will override exceptionSpeedKmH.
- speedIn: The speed the vehicle should enter the route with. By default -1, which means the vehicle enters using the speed limit of the first link.
- speedOut: The speed the vehicle should exit the route with. By default -1, which means the vehicle exits using the speed limit of the last link.
- logLevel: "Normal", "Detailed" or "Debug". The log level for the debug log on segments. Only relevant when response.segmentResults is true.
- electricityPriceArea: The pricing area for electricity.
Routing configuration
By default, the built-in routing first finds the nearest point in the network for each waypoint. If a waypoint is too far from any point in the network, routing will fail. This threshold can be adjusted by setting the maxSearchRadius parameter. Note that high maxSearchRadius values will increase the search time, and may result in routes starting or stopping in unexpected locations. It is usually reasonable to keep the search radius low to avoid this.
Between the located points in the network, the routing can use A* or Djikstra pathfinding algorithms to find the the shortest route based on driving time. Due to the computational demand of using Djikstra algorithm, A* is the default algorithm used by the routing configuration. In certain cases, A* may not find the optimal route, however, the returned route is usually very close to optimal. If you need the guaranteed optimal route (based on the time heuristic), you can set algorithm to Dijkstra instead. However, this will increase the routing time. You may set maxSearchDurationMs to abort the routing if it takes too long.
Multiple calculations simultaneously
When running large numbers of calculations, you can save a lot of time by sending them in batches of a few hundred or a few thousand calculations at a time. The /energy/matrix endpoints allows you to define one or more vehicles and one or more routes, and then calculates all combinations of these vehicles and routes.
The calculations are identical to the single-calculation /energy endpoint, and all inputs and outputs are also defined in the exact same way, except that you provide a 'vehicles' array instead of a single 'vehicle', and a 'routes' array instead of a single 'route'.
Results will be returned for all combinations of vehicles and routes, in an undefined order (due to parallel processing). Use the id property of vehicles and routes to identify results.
Multiple vehicles on a single route
When given multiple vehicles and/or multiple routes, you will get a result for each combination of vehicles and routes.
Multiple vehicles on a multiple routes
When given multiple vehicles and/or multiple routes, you will get a result for each combination of vehicles and routes.
Multiple vehicles on an all waypoint combinations
As a shortcut for defining a lot of routes from a list of waypoints to all other waypoints, you can also provide an AllToAllWaypoints list. When this is given, one route will be generated for all possible combinations of two waypoints. For example, given three waypoints A, B and C, you will get results for the routes A-B, A-C, B-A, B-C, C-A and C-B.
Shortcut for defining separate routes for each leg of a bus route
If you need to look at the results for each leg of a bus route, you can define separate routes for all pairs of stops. Instead of doing this manually, you can also define it as a single route, then use the splitIntoParts property to make the API split the route into legs for each sequential pair of stops.
For example, given the splitIntoParts flag, the route A-B-C-D will be split into three routes: A-B, B-C, C-D, and you will get separate results for each of these three legs.