The Observations API provides ground-truth data generated by the Helios analytics. The primary endpoint is the Search method, which allows users to view all sensor outputs and associated metadata. Additional methods provide advanced observation functionality, such as the ability to upload new data for inclusion in Helios.

Sensor Types

road_weather

The road weather metric provides a full picture of the condition of the road, with metric values indicating if dry, wet, or snow conditions were detected on the road surface.

Icon	Value	Description
	10	Full snow. In these cases, vehicle tracks and bare pavement may be seen in lanes of a multi-lane road, but more than 50% of the road surface is covered.
	6	Partial snow. In these cases, bare pavement is visible in at least one lane. Total snow coverage across the road is approximately 30-50%.
	3	Ponding. The road appears exceptionally wet, with noticeable road spray as vehicles pass through areas of pooling water.
	2	Wet. In these cases, the road is usually shiny and some road spray may be seen behind vehicles traveling at higher speeds.
	1	Moist. Minor amounts of moisture may be seen on the road, but not enough to meet the "wet" criteria.
	0	Dry. No water or snow coverage was detected on the road surface.
	-1	No report due to image quality or content.

visibility

The visibility metric provides an estimate of the overall scene visibility.

Icon	Value	Description	Approximate range
	0	Poor	0 to 0.3 miles
	0.2	Reduced	0.3 to 0.7 miles
	0.5	Hazy	0.7 to 1.5 miles
	1	Good	1.5+ miles
	-1	No report due to image quality or content

precip

The precip metric indicates the presence of active precipitation.

Icon	Value	Description
	1	Heavy. Indicates sufficient precipitation to impact driving conditions, where roads are significantly wet and visibility has been reduced.
	0	Not heavy. Indicates that heavy precipitation conditions were not detected.
	-1	No report due to image quality or content.

Search

Return a list of sensor observations matching the provided spatial, text, or metadata filters

Request

GET  https://api.helios.earth/v1/observations  or
POST https://api.helios.earth/v1/observations/_search

Query Parameters

When submitting a search using a GET request, all query parameters are specified as part of the query string. For POST requests, query parameters can either be submitted using a content type of application/json or x-www-form-urlencoded. See API Basics for more information.

sensors[visibility]=1

sensors[visibility][min]=0&sensors[visibility][max]=1

# transition from dry to wet roads
  sensors[road_weather][data]=3&sensors[road_weather][prev]=0 

# transition from dry/wet to partial/fully-covered snow roads
  sensors[road_weather][data][min]=6&sensors[road_weather][prev][max]=3 

aggs[]=state&aggs[]=time

aggs=state,time

aggs=sensors.visibility,sensors.road_weather

aggs=sensors.road_weather,sensors.road_weather.prev

Response

GeoJSON Feature Collection

HTTP 200
application/json

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "CADOT-807986_2017-07-21T22:10:00.000Z",
      "geometry": {
        "coordinates": [
          -117.4887542724609,
          34.14170455932617
        ],
        "type": "Point"
      },
      "properties": {
        "camera_id": "CADOT-807986",
        "prev_id": "CADOT-807986_2017-07-21T22:00:00.000Z",
        "description": "Cherry Avenue",
        "city": "Fontana",
        "state": "California",
        "country": "United States",
        "time": "2017-07-21T22:10:00.000Z",
        "sensors": {
          "visibility": {
            "data": 1
          },
          "road_weather": {
            "data": 3,
            "prev": 0
          }
        }
      }
    }
  ],
  "properties": {
    "total": 20,
    "skip": 0,
    "limit": 1,
    "aggs": {
      "state": [
        {"key": "New York", "doc_count": 10},
        {"key": "California", "doc_count": 10}
      ]
    }
  }
}

Tile

Return the current observations in Mapbox Vector Tile format

Request

GET https://api.helios.earth/v1/observations/{z}/{x}/{y}.mvt

Query Parameters

Response

A single vector tile for the specified geographic area (512x512 size). See the Mapbox documentation for more info.

HTTP 200
application/x-protobuf

All

Return all Helios observations (worldwide, all sensor types) for the given time as a single response

Request

GET https://api.helios.earth/v1/observations/_all/:time.json

URL Parameters

Response

HTTP 302

Note: The redirect URL is a signed URL that is valid for 15 minutes. Do not try to re-add any Helios authorization headers when following the redirect or you will not be able to retrieve the data.

Redirect Response

GeoJSON Feature Collection

HTTP 200
application/json

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "CADOT-807986_2017-07-21T22:10:00.000Z",
      "geometry": {
        "coordinates": [
          -117.4887542724609,
          34.14170455932617
        ],
        "type": "Point"
      },
      "properties": {
        "image": "https://api.helios.earth/v1/cameras/CADOT-807986/images/CADOT-807986_20170721221005134.jpg",
        "camera_id": "CADOT-807986",
        "description": "Cherry Avenue",
        "city": "Fontana",
        "state": "California",
        "country": "United States",
        "time": "2017-07-21T22:10:00.000Z",
        "sensor.visibility": 1,
        "sensor.road_weather": 3
      }
    }
  ]
}

Show

Return the attributes for a single observation

Request

GET https://api.helios.earth/v1/observations/:id

Response

GeoJSON Feature

HTTP 200
application/json

Preview

Return a preview image for the observation. This API call will attempt to filter out unusable images (e.g. full image text/logos, etc.) and will return the most recent image for the observation time period.

Request

GET https://api.helios.earth/v1/observations/:id/preview

Response

HTTP 302

Note: The redirect URL is a signed URL that is valid for 15 minutes. Do not try to re-add any Helios authorization headers when following the redirect or you will not be able to retrieve the data.

Redirect Response

HTTP 200
image/jpeg