# 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
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

  -   {     -     "routes" [     -       {             "id" 3629494 ,     -         "polyline" [     -           [                 -74.72596 ,                 40.12516               ] ,     -           [                 -74.72562 ,                 40.12448               ]             ] ,            "routeDuration" 8392           } ,     -       {             "id" 5604766 ,     -         "polyline" [     -           [                 -74.72596 ,                 40.12516               ] ,     -           [                 -74.72562 ,                 40.12448               ]             ] ,            "routeDuration" 8941           } ,     -       {             "id" 3237095 ,     -         "polyline" [     -           [                 -74.72596 ,                 40.12516               ] ,     -           [                 -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
recommendations
Object
List of supported recommendations.

For example, a possible recommendation is the cleanest route.
Show child fields
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:

  -   {     -     "racss" [     -       {             "routeId" "1234" ,             "RACS" 67 ,     -         "error" {               "code" 0 ,               "text" ""             } ,            "RACSid" "guid-guid"           }         ] ,     -     "recommendations" [     -       {     -         "additionalData" {               "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

Integrate BreezoMeter's data in your products today