Cleanest Route API v1

Last updated: Aug 23, 2022

The Cleanest Route API receives multiple routes as input (using polyline representation) and will respond with a single score (0-100) per route, which indicates the route's environmental cleanliness quality.

In addition, the endpoint will return a set of recommendations related to the provided route information, for example, which is the cleanest route.

In order to use it, set the following API POST request:

POST https://api.breezometer.com/insights/v1/cleanest-route?key={YOUR_API_KEY}

Request Parameters

Last updated: Aug 23, 2022

While making an API request some parameters are required, while some are optional.

Parameter

Description

Type

Required / Optional

routes

List of routes (at least 1) the system should provide RACS for.

RACS - Route Air Cleanliness Score.

Object

Required

Show child fields

Parameter

Description

Type

Required / Optional

id

Unique identifier of the route on the consumer systems

String

Required

polyline

Encoded representation of the route geometries.

i.e.

[

[-118.10494, 33.92513],

[-118.10471, 33.92384],

[-118.10524, 33.9215],

[-118.10494, 33.91872],

[-118.10514, 33.91],

[-118.10503, 33.89543],

[-118.10366, 33.87772],

[-118.10275, 33.87542]

]

String

Required

routeDuration

Route estimated duration (in Duration Units).

Integer

Default: N/A

Required

durationUnits

The units in which the duration for each Segment is stated.

Allowed values: s (seconds), m (minutes), h (hours)

Enum

Default: m (minutes)

Optional

lengthUnits

The units in which the length for each Segment is stated.

Allowed values: m (meters), km (kilometers), ft (feet), yd (yard), mi (miles).

Enum

Default: m (meters)

Optional

routesSort

Indicates whether the response will be sorted from the cleanest route to the least, vice versa or returned in the same order as received.

Allowed values: desc, asc, original.

Original means that RACS will be retrieved in the corresponding order of the routes provided in the request.

Enum

Default: original

Required

Examples

Last updated: Aug 23, 2022

JSON Example of endpoint input

  -   {  /* 4 items */  } ,     -     "routes" :  [  /* 3 items */  ] ,     -       {  /* 3 items */  } ,             "id" :  3629494 ,     -         "polyline" :  [  /* 2 items */  ] ,     -           [  /* 2 items */  ] ,                 -74.72596 ,                 40.12516               ] ,     -           [  /* 2 items */  ] ,                 -74.72562 ,                 40.12448               ]             ] ,            "routeDuration" :  8392           } ,     -       {  /* 3 items */  } ,             "id" :  5604766 ,     -         "polyline" :  [  /* 2 items */  ] ,     -           [  /* 2 items */  ] ,                 -74.72596 ,                 40.12516               ] ,     -           [  /* 2 items */  ] ,                 -74.72562 ,                 40.12448               ]             ] ,            "routeDuration" :  8941           } ,     -       {  /* 3 items */  } ,             "id" :  3237095 ,     -         "polyline" :  [  /* 2 items */  ] ,     -           [  /* 2 items */  ] ,                 -74.72596 ,                 40.12516               ] ,     -           [  /* 2 items */  ] ,                 -74.72562 ,                 40.12448               ]             ] ,            "routeDuration" :  8941           }         ] ,        "durationUnits" :  "s" ,         "lengthUnits" :  "m" ,         "routesSort" :  "original"       }  

Response Data Fields

Last updated: Aug 23, 2022

The response data field is an object that includes the following fields:

responseId

String (guid)

ID provided by BM for the response.

The ID is globally unique (e.g. GUID).

time

Timestamp (ISO 8601)

Timestamp in which the calculation completed.

Format should be ISO 8601 compliant.

racss

object

List of RACS (Route Air Cleanliness Score) sorted based on the Sort Descending request parameter.

Show child fields

RACSid

String (guid)

ID provided by BreezoMeter for the RACS calculation.

The ID should be globally unique (e.g. GUID).

routeId

String

The ID provided by the consumer in the request. This is to allow easy reconciliation for the consumer.

RACS

Integer

The score for the route.

Scale of 0-100 (100 is the cleanest).

error

Enum

The error for the RACS calculation.

• Code
• Error Text

Error code 0 means success.
See RACS Errors.

recommendations

Object

List of supported recommendations.

For example, a possible recommendation is the cleanest route.

Show child fields

recommendationId

Enum

Recommendation unique ID.

code

String

Closed list of values of supported recommendations which denotes the recommendation type.

E.g. CleanestRoute

name

String

Short textual description of the recommendation.

E.g. Cleanest Route

text

String

Detailed text description of the recommendation

additionalData

Object

Additional data required to fully understand the recommendation.

• Type
• Value

E.g. Route ID

Show child fields

Type

Enum

Type of additional data.
Allowed values: routeId.

Value

String

Value corresponding to the additional data type.

completionStatus

Enum

Indicates the status of the response.

Allowed values:
Completed,
CompletedWithErrors, Failed

• Completed - RACS calculated for all routes
• CompletedWithErrors - RACS could not be calculated for some routes
• Failed - RACS was not calculated to any route

Examples

Last updated: Aug 23, 2022

The request returns this response:

  -   {  /* 5 items */  } ,     -     "racss" :  [  /* 1 item */  ] ,     -       {  /* 4 items */  } ,             "routeId" :  "1234" ,             "RACS" :  67 ,     -         "error" :  {  /* 2 items */  } ,               "code" :  0 ,               "text" :  ""             } ,            "RACSid" :  "guid-guid"           }         ] ,     -     "recommendations" :  [  /* 1 item */  ] ,     -       {  /* 5 items */  } ,     -         "additionalData" :  {  /* 2 items */  } ,               "value" :  "1234" ,               "type" :  "routeId"             } ,            "recommendationId" :  "guid-guid" ,             "code" :  "CleanestRoute" ,             "name" :  "Cleanest Route" ,             "text" :  "The route with highest RACS"           }         ] ,        "completionStatus" :  "Completed" ,         "time" :  "2022-05-18T15:15:56+01:00" ,         "responseId" :  "guid-guid"       }  

Error Responses

Last updated: Aug 23, 2022

The following are the RACS errors which are added in addition to the Error Responses

Error Code	Error Text	Note
0	EMPTY	RACS calculated successfully
100	Insufficient data to calculate RACS for the provided route information	Not enough sensors along the route to calculate RACS
101	RACS calculation timed out	RACS calculation timed out (specific RACS, not all)
102	Provided route information is not sufficient for accurate RACS calculation	Route information is not granular enough to accurately calculate RACS. Route should be broken to smaller Segments