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.

{ "results": { // Contains aggregated results for this calculation "routeLengthKm": 8.29, // The total length of the calculated route "travelTimeS": 684.91, // The number of seconds the vehicle used to traverse this route "averageSpeedKmH": 43.55, // The average speed of the vehicle throughout this route "regenerationKwH": 0, // The amount of energy the vehicle regenerated "engineWorkKwH": 1.15, // The amount of work performed by the engine "brakeWorkKwH": 0.11, // The amount of work performed by the brakes "engineConsumptionKwH": 5.81, // The total amount of energy consumed by the vehicle "fuelConsumption": [ // Contains a summary of the fuel consumption for all fuels { // (usually just one, but for hybrids it will be two). "fuel": "gasoline", // The identifier of this fuel "fuelNameNorwegian": "Bensin", // The Norwegian name of this fuel "fuelName": "Gasoline", // The English name of this fuel "consumption": 0.64, // The amount of fuel consumed in fuel units (0.64 L in this case) "consumptionKg": 0.48, // The amount of fuel consumed in kilograms "unit": "L", // The unit of this fuel "co2G": 1514.92, // The direct CO2 emissions from this fuel (grams) "noxG": 4.16, // The direct NOx emissions from this fuel (grams) } ], "emissions": { // Contains the total emissions from this route "co2": { // Contains CO2 emissions from this route "vehicleManufacturingG": 656.65, // The indirect emissions from vehicle manufacturing, based on LCA assumptions and kilometers driven (grams). "vehicleMaintenanceG": 79.34, // The indirect emissions from vehicle maintenance, based on LCA assumptions and kilometers driven (grams). "fuelProductionG": 373.39, // The indirect emissions from fuel production, based on LCA assumptions and amount of fuel consumed (well-to-tank, grams). "tailpipeG": 1514.92, // The direct emissions from the tail pipe during this route (tank-to-wheel, grams). "totalLifecycleG": 2544.96 // The sum of all the above emissions. (grams) }, "nox": { // Contains NOx emissions from this route "tailpipeG": 4.16 // The direct emissions from the tail pipe during this route. (grams) } } }, "versionCode": 8 // The version of the API that was used for this calculation. Can be used to retrieve more details about the Energymodule and dataset versions. }

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.

When using the built-in routing, be aware that the routing algorithm is very simple, and may not always pick the most practical route. There may also be errors in the road network, which could cause the Energymodule to calculate an unintended route. The road network will be updated regularly, which may cause different results. Always check your results to ensure they are reasonable.

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.

SpeedLimitKmH must be a valid speed limit, which means it should be rounded to the nearest 10, and lower than 140. If you need to specify other speed limits, you can use calculationConfig.exceptionMode to override the speed limit check.

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.

Note that enabling linkResults or segmentResults will significantly increase the size of the response, and thereby also the time spent generating and transferring the response back to you.

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

Routing is only relevant when the route is specified as waypoints or stopIds. Only modify the routing options if you know what you are doing.

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.