The Cameras API provides access to all cameras in the Helios Network. The primary endpoints are the Index
and Live methods, which provide the user with the ability to search for cameras and view current images.
With these two simple calls, developers can include real-time camera images in their applications.
Additional methods provide advanced camera functionality, such as the ability to access historical imagery that has been archived by Helios for analytics.
Index
Return a list of cameras matching the provided spatial, text, or metadata filters
Request
GET https://api.helios.earth/v1/cameras or POST https://api.helios.earth/v1/cameras/_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.
| q | Query string that searches across multiple text fields e.g. q=south |
| bbox | GeoJSON format bounding box 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. |
| country | Country where the camera is located, e.g. United States, Canada |
| state | State where the camera is located, e.g. California, New York |
| city | City name where the camera is located, e.g. Rochester |
| provider | Camera provider e.g. New York State DOT |
| 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: city, region,
state, country, direction,
and 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: Multiple aggregations can be requested using array syntax or by listing them comma-delimited, e.g: aggs[]=state&aggs[]=city aggs=state,city For each requested aggregation, up to ten values and their respective camera counts will be returned. For instance,
if the |
Response
GeoJSON Feature Collection
HTTP 200
{
"type": "FeatureCollection",
"bbox": [...],
"features": [
{
"type": "Feature",
"id": "VADOT-85975",
"geometry": {
"type": "Point",
"coordinates": [-76.19457, 36.82146]
},
"properties": {
"country": "United States",
"state": "Virginia",
"city": "Virginia Beach",
"provider": "VA DOT",
"description": "I-64 / MM 285 / WB / OL TWIN BRIDGES & PROVIDENCE",
"video": true
}
}
],
"properties": {
"limit": 1,
"skip": 0,
"total": 15,
"aggs": {
"state": [
["key": "Virginia", "doc_count": 10]
]
}
}
}
View example
Tile beta
Return a set of cameras in Mapbox Vector Tile format
Request
GET https://api.helios.earth/v1/cameras/{z}/{x}/{y}.mvt
URL Parameters
None
Response
A single vector tile for the specified geographic area (512x512 size). See here for more info.
Show
Return the attributes for a single camera
Request
GET https://api.helios.earth/v1/cameras/:id
Response
HTTP 200, GeoJSON Feature
Live
Return the current image for a camera
Request
GET https://api.helios.earth/v1/cameras/:id/live
Response
HTTP 200 image/jpeg, HTTP 200 image/png, or HTTP 302 redirect (varies by camera)
Note: 302 redirects are to a signed URL that is valid for 15 minutes. The redirect URL can be followed as-is. Do not try to re-add any Helios authorization headers when following the redirect or you will not be able to retrieve the data.
View example
Live Video beta
Access a current video stream for the camera using HTTP Live Streaming (HLS)
Note: Only select cameras in the Helios network currently offer a
video stream. Availability will be denoted by the presence of a
video: true attribute in the camera properties.
Initial Playlist Request
The initial playlist should be requested using the following format:
GET https://api.helios.earth/v1/cameras/:id/live/playlist.m3u8
Media and Chunked Playlists
HLS clients should automatically request future playlists and media files (e.g. chunklist_*.m3u8, media_*.ts) using the following format:
GET https://api.helios.earth/v1/cameras/:id/live/:file
Response
HTTP 200 application/vnd.apple.mpegurl, HTTP 200 video/MP2T
Images
Return the image times available for a given camera in the media cache. The media cache contains all recent images archived by Helios, either for internal analytics or for end user recording purposes.
Request
GET https://api.helios.earth/v1/cameras/:id/images
Query String Parameters
| time | Starting image timestamp, specified in UTC as an ISO 8601 string (e.g. 2014-08-01 or 2014-08-01T12:34:56.000Z). |
| limit | Number of images to be returned, up to a max of 500. |
Response
HTTP 200
{
total: 500,
times: [
"2017-08-01T12:34:56.000Z",
...
]
}
View example
Show Image
Return a single image from the media cache. The media cache contains all recent images archived by Helios, either for internal analytics or for end user recording purposes.
Request
GET https://api.helios.earth/v1/cameras/:id/images/:time
URL Parameters
| id | Camera ID |
| time | Image time, specified in UTC as an ISO 8601 string (e.g. 2017-08-01 or 2017-08-01T12:34:56.000Z). The image with the closest matching timestamp will be returned. |
Response
HTTP 302 redirect to a signed URL where the camera image 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.
View example