Add Eco:Speed™ to Your Website and Mobile Apps
The Eco:Speed Web API returns Eco:Speed™ data for any route - anywhere on the planet where there's a road. You supply details of the route and how much energy you want to save and we'll return the ideal Eco:Speed™.
Software developers can use the API to add Eco:Speed™ to their website or mobile apps to provide:
- Optimized Map Directions
- Onboard Navigation
- Real-Time Energy Consumption and Route Tracking
To start using the Eco:Speed API, request an API Key as part of our Free Developer Trial.
API Quotas
API requests for the Free Developer Trial are limited to 25,000 calls per month. For higher expected volumes, please contact us.
API Sample Code
Sample code illustrating how to call the Eco:Speed API can be found here.
Eco:Speed API Inputs
The Eco:Speed API takes two data elements as inputs: an APIKey parameter and a JSON routeData object containing data and route parameters for calculating Eco:Speed results, as well as two subcomponents: a routes object array containing a list of routes and detailed route segment data, and a vehicle object containing detailed vehicle information.
Eco:Speed API Parameters
| Parameter | Description | |
|---|---|---|
| APIKey | Specifies your Eco:Speed API Key | Required |
| routeData object | A JSON object containing data and route parameters for calculating Eco:Speed results. For more details, see routeData object below | Required |
routeData Object
| Parameter | Description | |
|---|---|---|
| routes object array | A JSON object array containing a list of one or more routes and detailed route segment data. For more details, see routes object array below | Required |
| vehicle object | A JSON object containing detailed vehicle information. For more details, see vehicle object below | Required |
| quantizer | Specifies the personal Eco:Speed setting, valid values are: 0, 32, 64, 96, 128 and 256, where 0 results in no savings and 256 results in the greatest energy savings. A quantizer value of 64 is usually the ideal balance between energy savings and trip duration, what we call your ideal Eco:Speed | Required |
| sensor | Specifies whether the application requesting optimized route data is using a sensor to determine the current location, valid values are: true/false. Applications that determine current location via a sensor must set sensor=true. Applications that do not use a sensor should set sensor=false. | Required |
| dataSource | Specifies the data source data being used to determine the current location, for example:
|
Required |
| locale | Specifies the language-country locale used to localize any text/links returned by the Eco:Speed API | Optional |
routes Object Array
| Parameter | Description | |
|---|---|---|
| routeSegments object array | A JSON object array containing detailed route segment data. For more details, see routeSegments object array below | Required |
routeSegments Object Array
| Parameter | Description | |
|---|---|---|
| duration | Specifies the route segment duration in seconds | Required |
| distance | Specifies the route segment distance in meters | Required |
| startLocationLAT | Specifies the latitude of the start location | Required |
| startLocationLON | Specifies the longitude of the start location | Required |
| endLocationLAT | Specifies the latitude of the end location | Required |
| endLocationLON | Specifies the longitude of the end location | Required |
| polyline | Specifies the encoded polyline for the route segment coordinates. If the application or mapping service does not provide an encoded polyline or the encoded polyline is unknown, set polyline = -1 (for more details on encoded polylines click here). | Required |
| roadType | Specifies the type of road, valid values are:
| Required |
| heading | Specifies the direction heading for the route segment, valid values are: 0-359. If the application or mapping service does not provide heading or heading is unknown, set heading = -1 | Required |
| Vi | Specifies the speed at start of the route segment in meters per second | Optional |
| Vf | Specifies the speed at end of the route segment in meters per second | Optional |
| avgGrade | Specifies the average grade of the route segment in percent, valid values are: 0-100 | Optional |
| acceleration | Specifies the vehicle acceleration in meters per second squared | Optional |
| deceleration | Specifies the vehicle deceleration in meters per second squared | Optional |
vehicle Object
| Parameter | Description | |
|---|---|---|
| kg | Specifies the vehicle mass in kg (not including vehicle occupants) | Optional |
| occupants | Specifies the number of vehicle occupants | Optional |
| propulsionType | Specifies the vehicle propulsion type, valid values are:
| Optional |
| regenEnabled | Specifies whether the vehicle propulsion type supports regeneration, valid values: true/false | Optional |
| regenEfficiency | Specifies the regeneration efficiency in percent, valid values are: 0-100 | Optional |
| inertialMoment | Specifies the inertial moment of the vehicle and drive train, if known | Optional |
| Cf | Specifies the coefficient of friction the vehicle tires | Optional |
| CfAlpha | Specifies the coefficient of friction alpha of the vehicle tires, if known | Optional |
| CfBeta | Specifies the coefficient of friction beta of the vehicle tires, if known | Optional |
| CdA | Specifies the drag area of the vehicle in meters squared (note: this is effective drag area - frontal area x vehicle Cd) | Optional |
Eco:Speed API Output
The Eco:Speed API returns a JSON object containing the following outputs: a status object containing the API call status, a routeIndex property, a routeSegments object array containing optimized route segment data, a routeDuration property, an energySavings property and a resources object containing resource locations for Eco:Speed images and localized text strings.
Route Data Object
| Parameter | Description |
|---|---|
| status object | Returns a JSON object containing the API call status. For more details, see status object below |
| routeIndex | Depending on the number of routes submitted to the API in the routes object array, this returns the index of the optimal route calculated by the API. |
| routeSegments object array | Returns a JSON object array containing optimized route segment data. For more details, see routeSegments object array below |
| routeDuration | Returns the duration of the trip from start to end |
| energySavings | Returns the energy savings for the trip from start to end for a given energy savings level |
| resources object | Returns a JSON object containing resource locations for Eco:Speed images and localized text strings. For more details, see resources object below |
status Object
| Parameter | Description |
|---|---|
| statusCode | Returns a status code. If the call is successful the API returns 0. If an error occurs the API returns -1 |
| statusText | Returns a status text string. If the call is successful the API returns 'OK'. If an error occurs the API returns a text string describing the error. |
routeSegments Object Array
| Parameter | Description |
|---|---|
| Vmax | Returns the optimal maximum speed in meters per second for the route segment |
resources Object
| Parameter | Description |
|---|---|
| speedString | Specifies the text string that precedes the Eco:Speed result (note: this is a required branding component) |
| speedLogoSRC | Specifies the resource location for the Eco:Speed logo that follows the Eco:Speed result (note: this is a required branding component) |
| moreInfoHREF | Specifies the resource location for the Eco:Speed moreInfo web page (note: this is a required branding component) |
| markerImagePath | Specifies the resource location for the Eco:Speed map markers (note: this is a required branding component when displaying map data) |
| energySavingsString | Specifies the text string that precedes the Eco:Speed Energy Savings result (note: this is a required branding component when displaying energy savings data) |
| energySavingsLogoSRC | Specifies the resource location for the Eco:Speed Energy Savings logo that follows the Eco:Speed Energy Savings result (note: this is a required branding component when displaying energy savings data) |
| copyrights | Specifies the copyright text string that accompanies the Eco:Speed result (note: this is a required branding component) |
Branding Requirements
All implementations using the Eco:Speed API must comply with the following branding requirements:
- Display the Eco:Speed result followed by the approved eco:Speed logo returned by the Eco:Speed API (speedLogoSRC)
- Link the Eco:Speed result, approved Eco:Speed logo, Eco:Speed Energy Savings and approved Eco:Speed Energy Savings Logo to the Eco:Speed moreInfo page (moreInfoHREF)