Observations API

The Observations API provides ground-truth data generated by the Helios analytics. The primary endpoint is the Index 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.

Data value Description
0 Dry. No water or snow coverage was detected on the road surface.
3 Wet. In these cases, the road is usually shiny and road spray may be seen behind vehicles travelling at higher speeds. Roads may have a small percentage of snow on them, but still meet the criteria of a "wet" condition.
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%.
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.
roadweather-1
Comparison of images with dry and wet conditions. The image on the left would produce a road weather metric value of 0 while the image on the right would produce a value of 3.

roadweather-2
Comparison of images with partial snow and full snow conditions. The image on the left would produce a road weather metric value of 6 while the image on the right would produce a value of 10.

visibility

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

Data value Description
0 Poor
0.5 Reduced beta
1 Good beta
visibility
Comparison of images with different levels of visibility. The image on the left would produce a value of 0 (poor), the image in the middle would produce a value of 0.5 (reduced), and the image on the right would produce a value of 1 (good).

precip

The precip metric indicates the presence of active precipitation.

Data value Description
0 Not heavy. Indicates that heavy precipitation conditions were not detected.
1 Heavy. Indicates sufficient precipitation to impact driving conditions, where roads are significantly wet and visibility has been reduced.
precip
The image on the left would produce a precip metric value of 0 while the image on the right would produce a value of 1.

Index

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, specified in UTC as an ISO 8601 string (e.g. 2013-07-01 or 2013-07-01T12:34:56.000Z)
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. While the region is a generalized location, the city represents the actual physical location of the observation. e.g. city=Long Beach, region=Los Angeles
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

{
  "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": 5}
      ]
    }
  }
}

Note: city, state, and country attributes are included on all observations produced by camera-based analytics. These attributes will not be present on any user uploaded observations unless that data is provided by the user with the observation data.


View example

Show

Return the attributes for a single observation

Request

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

Response

HTTP 200, GeoJSON Feature


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 redirect to a signed URL where the attachment file can be retrieved. The signed URL is valid for 15 minutes.

Note: The redirect URL can be followed as-is since it is a signed URL. Do not try to re-add any Helios authorization headers when following the redirect or you will not be able to retrieve the data.


Create beta

Create a new observation record

Request

POST https://api.helios.earth/v1/observations

Params

All request parameters must be specified as attributes in a multipart/form request.

time Observation time in UTC specified as an ISO 8601 string (e.g. 2013-07-01T12:34:56.000Z)
description Description of the location or observation
latitude, longitude Observation coordinates in decimal degrees
sensors List of sensor types and associated data. There should be a data attribute that identifies the primary result of that sensor's measurement. All nested values are specified using square bracket syntax, e.g.

sensors[temperature_celcius][data]=18.5&sensors[humidity][data]=0.56
image Optional JPEG image file to be uploaded

Response

HTTP 201

{"ok": true, "observation_id": "..."}

View example