Core APIs

Alerts

Helios Alerts API.

Methods are meant to represent the core functionality in the developer documentation. Some may have additional functionality for convenience.

class helios.alerts_api.Alerts(session=None)[source]

Helios alerts provide real-time severe weather alerts.

National Weather Service:

  • Severe weather alerts for the United States are provided by the National Weather Service. These alerts cover events such as Flood Warnings, Severe Thunderstorm Warnings, and Special Weather Statements.

Helios:

  • Alerts generated by Helios are based on the sensor measurements from the Observations API. These alerts represent regional areas with a high detection confidence and currently include: Road Wetness Watch, Poor Visibility Watch, and Heavy Precip Watch.
index(**kwargs)[source]

Get alerts matching the provided spatial, text, or metadata filters.

The maximum skip value is 4000. If this is reached, truncated results will be returned. You will need to refine your query to avoid this.

Parameters:**kwargs – Any keyword arguments found in the alerts_index_documentation.
Returns:AlertsFeatureCollection
show(alert_ids)[source]

Get attributes for alerts.

Parameters:alert_ids (str or sequence of strs) – Helios alert ID(s).
Returns:AlertsFeatureCollection
class helios.alerts_api.AlertsFeature(feature)[source]

Individual Alert GeoJSON feature.

area_description

str – ‘areaDesc’ value for the feature.

bbox

sequence of floats – ‘bbox’ value for the feature.

category

str – ‘category’ value for the feature.

certainty

str – ‘certainty’ value for the feature.

country

str – ‘country’ value for the feature.

description

str – ‘description’ value for the feature.

effective

str – ‘effective’ value for the feature.

event

str – ‘event’ value for the feature.

expires

str – ‘expires’ value for the feature.

headline

str – ‘headline’ value for the feature.

id

str – ‘id’ value for the feature.

json

dict – Raw ‘json’ for the feature.

origin

str – ‘origin’ value for the feature.

severity

str – ‘severity’ value for the feature.

states

sequence of strs – ‘states’ value for the feature.

status

str – ‘status’ value for the feature.

urgency

str – ‘urgency’ value for the feature.

class helios.alerts_api.AlertsFeatureCollection(content, records)[source]

Iterable for GeoJSON features obtained via the Alerts API.

All features within IndexResults are instances of AlertsFeature

area_description

‘areaDesc’ values for every feature.

bbox

‘bbox’ values for every feature.

category

‘category’ values for every feature.

certainty

‘certainty’ values for every feature.

country

‘country’ values for every feature.

description

‘description’ values for every feature.

effective

‘effective’ values for every feature.

event

‘event’ values for every feature.

expires

‘expires’ values for every feature.

failed

Records for queries that failed.

headline

‘headline’ values for every feature.

id

‘id’ values for every feature.

json

Raw ‘json’ for every feature.

origin

‘origin’ values for every feature.

severity

‘severity’ values for every feature.

states

‘states’ values for every feature.

status

‘status’ values for every feature.

succeeded

Records for queries that succeeded.

urgency

‘urgency’ values for every feature.

Cameras

Helios Cameras API.

Methods are meant to represent the core functionality in the developer documentation. Some may have additional functionality for convenience.

class helios.cameras_api.Cameras(session=None)[source]

The Cameras API provides access to all cameras in the Helios Network.

images(camera_id, start_time, end_time=None, limit=500)[source]

Get 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.

Parameters:
  • camera_id (str) – Camera ID.
  • start_time (str) – Starting image timestamp, specified in UTC as an ISO 8601 string (e.g. 2014-08-01 or 2014-08-01T12:34:56.000Z).
  • end_time (str, optional) – Ending image timestamp, specified in UTC as an ISO 8601 string (e.g. 2014-08-01 or 2014-08-01T12:34:56.000Z).
  • limit (int, optional) – Number of images to be returned, up to a max of 500. Defaults to 500.
Returns:

Image times.

Return type:

sequence of strs

index(**kwargs)[source]

Get cameras matching the provided spatial, text, or metadata filters.

The maximum skip value is 4000. If this is reached, truncated results will be returned. You will need to refine your query to avoid this.

Parameters:**kwargs – Any keyword arguments found in the cameras_index_documentation.
Returns:CamerasFeatureCollection
show(camera_ids)[source]

Get attributes for cameras.

Parameters:camera_ids (str or sequence of strs) – Helios camera ID(s).
Returns:CamerasFeatureCollection
show_image(camera_id, times, out_dir=None, return_image_data=False)[source]

Get images from the media cache.

The media cache contains all recent images archived by Helios, either for internal analytics or for end user recording purposes.

Parameters:
  • camera_id (str) – Camera ID.
  • times (str or sequence of strs) – Image times, 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.
  • out_dir (optional, str) – Directory to write images to. Defaults to None.
  • return_image_data (optional, bool) – If True images will be returned as numpy.ndarrays. Defaults to False.
Returns:

ImageCollection

class helios.cameras_api.CamerasFeature(feature)[source]

Individual Camera GeoJSON feature.

city

str – ‘city’ value for the feature.

country

str – ‘country’ value for the feature.

description

str – ‘description’ value for the feature.

direction

str – ‘direction’ value for the feature.

id

str – ‘id’ value for the feature.

json

dict – Raw ‘json’ for the feature.

region

str – ‘region’ value for the feature.

state

str – ‘state’ value for the feature.

video

bool – ‘video’ value for the feature.

class helios.cameras_api.CamerasFeatureCollection(content, records)[source]

Iterable for GeoJSON features obtained via the Cameras API.

All features within ShowResults are instances of CamerasFeature

city

‘city’ values for every feature.

coordinates

‘coordinate’ values for every feature.

country

‘country’ values for every feature.

description

‘description’ values for every feature.

direction

‘direction’ values for every feature.

failed

Records for queries that failed.

id

‘id’ values for every feature.

json

Raw ‘json’ for every feature.

region

‘region’ values for every feature.

state

‘state’ values for every feature.

succeeded

Records for queries that succeeded.

video

‘video’ values for every feature.

Collections

Helios Collections API.

Methods are meant to represent the core functionality in the developer documentation. Some may have additional functionality for convenience.

class helios.collections_api.Collections(session=None)[source]

The Collections API allows users to group and organize individual image frames.

Collections are intended to be short-lived resources and will be accessible for 90 days from the time the collection was created. After that time period has expired, the collection and all associated imagery will be removed from the system.

add_image(collection_id, assets)[source]

Add images to a collection from Helios assets.

assets dictionary templates:

# Asset examples that can be included in the `assets` input list.
{'camera_id': ''}
{'camera_id': '', 'time': ''}
{'observation_id': ''}
{'collection_is': '', 'image': ''}

Usage example:

import helios
collections = helios.Collections()
camera_id = '...'
times = [...] # List of image times.
destination_id = '...'
data = [{'camera_id': camera_id, 'time': x} for x in times]
collections.add_image(destination_id, data)
Parameters:
  • collection_id (str) – Collection ID.
  • assets (dict or sequence of dicts) – Data containing any of these payloads (camera_id), (camera_id, time), (observation_id), (collection_id, image). E.g. data = [{‘camera_id’: ‘cam_01’, time: ‘2017-01-01T00:00:000Z’}]
Returns:

RecordCollection

copy(collection_id, new_name)[source]

Copy a collection and its contents to a new collection.

Parameters:
  • collection_id (str) – Collection ID.
  • new_name (str) – New collection name.
Returns:

New collection ID.

Return type:

str

create(name, description, tags=None)[source]

Create a new collection.

Parameters:
  • name (str) – Display name for the collection.
  • description (str) – Description for the collection.
  • tags (str or sequence of strs, optional) – Optional comma-delimited keyword tags to be added to the collection.
Returns:

New collection ID.

Return type:

str

destroy(collection_id)[source]

Delete an empty collection.

If the collection is not empty, delete will fail. Use the empty method to remove all imagery before calling this method.

Parameters:collection_id (str) – Collection to delete.
Returns:{ok: true}
Return type:dict
empty(collection_id)[source]

Bulk remove (up to 1000) images from a collection.

Parameters:collection_id (str) – Collection to empty.
Returns:{ok: true, total: 1000}
Return type:dict
images(collection_id, camera=None, old_flag=False)[source]

Get all image names in a given collection.

When using the optional camera input parameter only images from that camera will be returned.

Parameters:
  • collection_id (str) – Collection ID.
  • camera (str, optional) – Camera ID to be found.
  • old_flag (bool, optional) – Flag for finding old format image names. When True images that do not contain md5 hashes at the start of their name will be found.
Returns:

Image names.

Return type:

sequence of strs

index(**kwargs)[source]

Get collections matching the provided spatial, text, or metadata filters.

The maximum skip value is 4000. If this is reached, truncated results will be returned. You will need to refine your query to avoid this.

Parameters:**kwargs – Any keyword arguments found in the collections_index_documentation.
Returns:CollectionsFeatureCollection
remove_image(collection_id, names)[source]

Remove images from a collection.

Parameters:
  • collection_id (str) – Collection ID to remove images from.
  • names (str or sequence of strs) – List of image names to be removed.
Returns:

RecordCollection

show(collection_id, limit=200, marker=None)[source]

Get the attributes and image list for collections.

The results will also contain image names available in the collection. These are limited to a maximum of 200 per query.

Parameters:
  • collection_id (str) – Collection ID.
  • limit (int, optional) – Number of image names to be returned with each response. Defaults to 200. Max value of 200 is allowed.
  • marker (str, optional) – Pagination marker. If the marker is an exact match to an existing image, the next image after the marker will be the first image returned. Therefore, for normal linked list pagination, specify the last image name from the current response as the marker value in the next request. Partial file names may be specified, in which case the first matching result will be the first image returned.
Returns:

CollectionsFeature

show_image(collection_id, image_names, out_dir=None, return_image_data=False)[source]

Get images from a collection.

Parameters:
  • collection_id (str) – Collection ID to add images into.
  • image_names (str or sequence of strs) – Image names.
  • out_dir (optional, str) – Directory to write images to. Defaults to None.
  • return_image_data (optional, bool) – If True images will be returned as numpy.ndarrays. Defaults to False.
Returns:

ImageCollection

update(collections_id, name=None, description=None, tags=None)[source]

Update a collection.

Parameters:
  • collections_id (str) – Collection ID.
  • name (str, optional) – Name to be changed to.
  • description (str, optional) – Description to be changed to.
  • tags (str or sequence of strs, optional) – Optional comma-delimited keyword tags to be changed to.
class helios.collections_api.CollectionsFeature(feature)[source]

Individual Collection JSON result.

bucket

str – ‘bucket’ value for the result.

created_at

str – ‘city’ value for the result.

description

str – ‘created_at’ value for the result.

id

str – ‘_id’ value for the result.

images

sequence of strs – ‘images’ value for the result.

json

dict – Raw JSON result.

name

str – ‘name’ value for the result.

tags

sequence of strs – ‘tags’ value for the result.

updated_at

str – ‘updated_at’ value for the result.

user_id

str – ‘user_id’ value for the result.

class helios.collections_api.CollectionsFeatureCollection(content, records)[source]

Iterable for features obtained via the Collections API.

All features within CollectionsFeatureCollection are instances of CollectionsFeature

bucket

‘bucket’ values for every result.

created_at

‘city’ values for every result.

description

‘created_at’ values for every result.

failed

Records for queries that failed.

id

‘_id’ values for every result.

json

Raw ‘json’ for every feature.

name

‘name’ values for every result.

succeeded

Records for queries that succeeded.

tags

‘tags’ values for every result.

updated_at

‘updated_at’ values for every result.

user_id

‘user_id’ values for every result.

Observations

Helios Observations API.

Methods are meant to represent the core functionality in the developer documentation. Some may have additional functionality for convenience.

class helios.observations_api.Observations(session=None)[source]

The Observations API provides ground-truth data generated by the Helios analytics.

index(**kwargs)[source]

Get observations matching the provided spatial, text, or metadata filters.

The maximum skip value is 4000. If this is reached, truncated results will be returned. You will need to refine your query to avoid this.

Usage example:

import helios
obs = helios.Observations()
state = 'Maryland'
bbox = [-169.352,1.137,-1.690,64.008]
sensors = 'sensors[visibility][min]=0&sensors[visibility][max]=1'
results = obs.index(state=state,
                    bbox=bbox,
                    sensors=sensors)

Usage example for transitions:

import helios
obs = helios.Observations()
# transition from dry/wet to partial/fully-covered snow roads
sensors = 'sensors[road_weather][data][min]=6&sensors[road_weather][prev][max]=3'
results = obs.index(sensors=sensors_query)
Parameters:**kwargs – Any keyword arguments found in the observations_index_documentation.
Returns:ObservationsFeatureCollection
preview(observation_ids, out_dir=None, return_image_data=False)[source]

Get preview images from observations.

Parameters:
  • observation_ids (str or sequence of strs) – list of observation IDs.
  • out_dir (optional, str) – Directory to write images to. Defaults to None.
  • return_image_data (optional, bool) – If True images will be returned as numpy.ndarrays. Defaults to False.
Returns:

ImageCollection

show(observation_ids)[source]

Get attributes for observations.

Parameters:observation_ids (str or sequence of strs) – Helios observation ID(s).
Returns:ObservationsFeatureCollection
class helios.observations_api.ObservationsFeature(feature)[source]

Individual Observation GeoJSON feature.

city

str – ‘city’ value for the feature.

country

str – ‘country’ value for the feature.

description

str – ‘description’ value for the feature.

id

str – ‘id’ value for the feature.

json

dict – Raw JSON feature.

prev_id

str – ‘prev_id’ value for the feature.

region

str – ‘region’ value for the feature.

sensors

dict – ‘sensors’ value for the feature.

state

str – ‘state’ value for the feature.

time

str – ‘time’ value for the feature.

class helios.observations_api.ObservationsFeatureCollection(content, records)[source]

Iterable for GeoJSON features obtained via the Observations API.

All features within ShowResults are instances of ObservationsFeature

city

‘city’ values for every feature.

country

‘country’ values for every feature.

description

‘description’ values for every feature.

failed

Records for queries that failed.

id

‘id’ values for every feature.

json

Raw ‘json’ for every feature.

prev_id

‘prev_id’ values for every feature.

region

‘region’ values for every feature.

sensors

‘sensors’ values for every feature.

sensors_to_dataframes(output_dir=None, prefix=None)[source]

Combine sensor blocks and other useful feature information for observations into Pandas DataFrame objects.

DataFrames will contain the time, value, previous value, observation ID, and previous observation ID from each feature.

Optionally, DataFrames can be written to CSV files. These will follow the format of {prefix}_{sensor_name}.csv.

Parameters:
  • output_dir (str, optional) – Output directory to write files to. If None, then no files will be written. Defaults to None.
  • prefix (str, optional) – Prefix to append to filenames. If None, no prefix will be prepended. Defaults to None.
Returns:

Pandas DataFrame objects for each sensor.

Return type:

dict

state

‘state’ values for every feature.

succeeded

Records for queries that succeeded.

time

‘time’ values for every feature.

Session

Manager for the authorization token required to access the Helios API.

class helios.core.session.Session(env=None)[source]

Manages API tokens for authentication.

Authentication credentials can be specified using the env input parameter, environment variables, or a credentials.json file in your ~/.helios directory. See the official documentation for more authentication information.

Required keys:
  • helios_client_id: Client ID from API key pair.
  • helios_client_secret: Client Secret ID from API key pair.
Optional keys:
  • helios_api_url: Optional, URL for API endpoint.

A session can be established and reused for multiple core API instances.

import helios
sess = helios.Session()
alerts = helios.Alerts(session=sess)
cameras = helios.Cameras(session=sess)

If a session is not specified before hand, one will be initialized automatically. This is less efficient because each core API instance will try to initialize a session.

import helios
alerts = helios.Alerts()
cameras = helios.Cameras()
start_session()[source]

Begins Helios session.

This will establish and verify a token for the session. If a token file exists the token will be read and verified. If the token file doesn’t exist or the token has expired then a new token will be acquired.

verify_token()[source]

Verifies the token.

If the token is bad or if the expiration time is less than the threshold False will be returned.

Returns:True if current token is valid, False otherwise.
Return type:bool

Structure

Base data structures for the SDK.

class helios.core.structure.ContentCollection(content, raw_data=None)[source]

Base class for feature/data results, i.e. content.

This is a general purpose iterable for content data from the SDK. Specific functionality will be defined in child classes.

Content is a general term for return data from the various API calls implemented within the SDK. For example, index queries return GeoJSON feature collections. Therefore, content will be a list of all the returned features within the GeoJSON feature collection.

content

sequence – Content that will be the elements in the iterator.

raw_data

sequence – Raw data for debugging.

class helios.core.structure.ImageCollection(content, records)[source]

Iterable for the fetched image content. Each element will be an ndarray if return_image_data was True.

failed

Records for queries that failed.

image_data

Image data if return_image_data was True.

name

Names of all images.

output_file

Full paths to all written images.

succeeded

Records for queries that succeeded.

class helios.core.structure.ImageRecord(message=None, query=None, content=None, error=None, name=None, output_file=None)[source]

Record class for images.

Parameters:
  • message (tuple) – Original message. This will be a namedtuple containing all the inputs for an individual call within a batch job.
  • query (str) – API query.
  • content (numpy.ndarray) – Image as a Numpy ndarray.
  • error (exception) – Exception that occurred, if any.
  • name (str) – Name of image.
  • output_file (str) – Full path to image file that was written.
ok

Check if failure occurred.

Returns:False if error occurred, and True otherwise.
Return type:bool
class helios.core.structure.Record(message=None, query=None, content=None, error=None)[source]

Record class for general use.

Parameters:
  • message (tuple) – Original message. This will be a namedtuple containing all the inputs for an individual call within a batch job.
  • query (str) – API query.
  • content – Returned content. To be defined by method.
  • error (exception) – Exception that occurred, if any.
ok

Check if failure occurred.

Returns:False if error occurred, and True otherwise.
Return type:bool
class helios.core.structure.RecordCollection(content, records)[source]

Base class for batch jobs dealing with Records.

This class is a variation of the FeatureCollection class to work with Records. The content attribute will be extracted from each record. Usage is the same as a ContentCollection, but the _raw attribute will give access to the underlying Records.

content

sequence – Content that will be the elements in the iterator.

records

sequence of Records – Raw record data for debugging purposes.

failed

Records for queries that failed.

succeeded

Records for queries that succeeded.

Utilities

json_utils

Helper functions for JSON objects.

helios.utilities.json_utils.merge_json(data, keys)[source]

Merge JSON fields into a single list.

Keys can either be a single string or a list of strings signifying a chain of “keys” into the dictionary.

Parameters:
  • data (list) – Dictionary to merge data from.
  • keys (str or sequence of strs) – A chain of keys into the dictionary to get to the field that will be merged.
Returns:

Merged values.

Return type:

list

helios.utilities.json_utils.read_json_file(json_file, **kwargs)[source]

Read a json file.

Parameters:
  • json_file (str) – Full path to JSON file.
  • **kwargs – Any keyword argument from the json.load method.
Returns:

JSON formatted dictionary.

Return type:

dict

helios.utilities.json_utils.read_json_string(json_string, **kwargs)[source]

Convert JSON formatted string to JSON.

Parameters:
  • json_string (str) – JSON formatted string.
  • **kwargs – Any keyword argument from the json.loads method.
Returns:

JSON formatted dictionary.

Return type:

dict

helios.utilities.json_utils.write_json(json_dict, file_name, **kwargs)[source]

Write JSON dictionary to file.

Parameters:
  • json_dict (dict) – JSON formatted dictionary.
  • file_name (str) – Output file name.
  • **kwargs – Any keyword argument from the json.dump method.
Returns:

None

parsing_utils

Helper functions for paths and URLs.

helios.utilities.parsing_utils.parse_camera(data)[source]

Parse camera name from a URL or image name.

Parameters:data (str) – Image URL or name.
Returns:Camera name.
Return type:str
helios.utilities.parsing_utils.parse_image_name(url)[source]

Parse image name from a URL.

Parameters:url (str) – Image URL.
Returns:Image name.
Return type:str
helios.utilities.parsing_utils.parse_time(data)[source]

Parse time from a URL or image name.

Parameters:data (str) – Image URL or name.
Returns:The parsed time as a datetime object.
Return type:datetime.datetime
helios.utilities.parsing_utils.parse_url(url)[source]

Parse a URL into its components.

Parameters:url (str) – Image URL.
Returns:Parsed URL.
Return type:urllib.parse.ParseResult