Observations API

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
road-snow 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.
road-snow-partial 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%.
road-ponding 3 Ponding. The road appears exceptionally wet, with noticeable road spray as vehicles pass through areas of pooling water.
road-wet 2 Wet. In these cases, the road is usually shiny and some road spray may be seen behind vehicles traveling at higher speeds.
road-moist 1 Moist. Minor amounts of moisture may be seen on the road, but not enough to meet the "wet" criteria.
road-dry 0 Dry. No water or snow coverage was detected on the road surface.
road-no-report -1 No report due to image quality or content.
roadweather-wet
Images with different road weather conditions: dry (top-left), moist (top-right), wet (bottom-left), ponding (bottom-right).
roadweather-snow
Images with different road weather conditions during winter: partial snow (left), full snow (right).

visibility

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

Icon Value Description Approximate range
visibility-poor 0 Poor 0 to 0.3 miles
visibility-reduced 0.2 Reduced 0.3 to 0.7 miles
visibility-hazy 0.5 Hazy 0.7 to 1.5 miles
visibility-good 1 Good 1.5+ miles
visibility-no-report -1 No report due to image quality or content
visibility
Images with different levels of visibility: good (top-left), hazy (top-right), reduced (bottom-left), poor (bottom-right).

precip

The precip metric indicates the presence of active precipitation.

Icon Value Description
precip-rain 1 Heavy. Indicates sufficient precipitation to impact driving conditions, where roads are significantly wet and visibility has been reduced.
precip-none 0 Not heavy. Indicates that heavy precipitation conditions were not detected.
precip-no-report -1 No report due to image quality or content.
precip
Images with different levels of precipitation: not heavy (left), heavy (right).

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.


bbox Geospatial bounding box query, specified in GeoJSON format e.g. -180,-90,180,90
polygon Comma separated coordinate pairs. Each coordinate pair consists of the longitude and latitude, separated by a space. It is recommended that the first and last coordinate pairs be equal to properly close the polygon.

e.g. -105 40,-100 36,-110 38,-105 40
lat, lon, radius Geospatial point radius query. lat and lon are specified in degrees. Radius is optional and can be specified in either meters (no units), kilometers, or miles e.g. 10000 or 10km or 10mi. If no radius is specified, a default value of 10km is assumed.
polyline, polyline_precision, polyline_radius Geospatial polygon search using the encoded polyline format used by routing providers. The polyline_precision defaults to a precision of 5, which is used by Google Maps. For OSRM-based routing providers like Mapbox Directions, use a precision value of 6. The polyline_radius provides a buffer around the supplied polyline and is specified in kilometers, with a default value of 1.

Note: Polylines can be quite large for complex routes and there is a limit on the size of a query string for GET requests, so it is recommended that you use POST requests to submit searches that include this parameter.
sensors

Sensor types, specified as a nested query parameter. Any of the sensor types listed in the section at the top of this page can be specified. Sensors can either be queried for an exact match or for a range of values by including the min/max nested params.

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

(beta)
In addition to the current sensor value, each observation also includes the previous value. We can query those previous values in a similar fashion, allowing us to identify areas of weather transitions.

To ensure that any current and previous sensor values are properly interpreted in our query, we must now nest the current value in a data parameter:

# 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 
time_min, time_max Observation time (UTC), specified as an ISO 8601 datetime (e.g. 2018-01-01T12:30:00.000Z) or as a time-only string in HH:MM format (e.g 12:30).
date_min, date_max Observation date (UTC) in yyyy-mm-dd format.
q Query string that searches across multiple text fields e.g. q=south
country Country where the observation is located e.g. United States, Canada
state State where the observation is located e.g. California, New York
city City name where the observation is located e.g. Rochester
camera_id Camera ID
limit Limit value for pagination. Defaults to 10. Max value of 100 is allowed.
skip Skip value for pagination. Defaults to 0. Max value of 4000 is allowed.
sort Sort parameter: country, state, city, time, distance are currently allowed. Note that distance is only valid for cases when the lat and lon query parameters are also supplied.
sort_dir Sort direction: asc or desc (default is asc)
aggs

Aggregate and summarize the results set based on the following attributes: country, state, city, camera_id, time.

Multiple aggregations can be requested using array syntax or by listing them comma-delimited, e.g:

aggs[]=state&aggs[]=time
aggs=state,time

For each requested aggregation, up to ten values and their respective observation counts will be returned. For instance, if the state aggregation is requested, the results will include the ten states with the highest number of observations matching the specified search query parameters, along with the total count for each of those states.

When performing a time aggregation, results will be aggregated by day by default. If a time query is performed (using the time_min and time_max parameters) and the query interval is less than or equal to 2 days, the results will be aggregated by hour instead.

To aggregate by the current sensor value, specify each desired sensor using a sensors.<sensor_name> syntax. For instance, to aggregate by the visibility and road weather sensors, specify:

aggs=sensors.visibility,sensors.road_weather

(beta)
In addition to the current sensor value, each observation also includes the previous sensor value and we can aggregate by those previous values in a similar fashion:

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}
      ]
    }
  }
}

View example
This API method is currently in beta and subject to change.

Tile

Return a set of observations in Mapbox Vector Tile format

Request

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

Query Parameters

sort_dir By default, the features array contained within the tile will be sorted in descending time order. Setting this value to asc will reverse the order, which may be desired for certain map types.

Response

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

HTTP 200
application/x-protobuf

This API method is currently in beta and subject to change.

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

time ISO8601 time in minutes. Data files are provided "on the tens" (2018-08-01T12:00Z, 2018-08-01T12:10Z, etc.) and are generally available 10 minutes after the given time period.

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