Singularity API

A detailed reference to the SingularityAPI wrapper class

class singularity.SingularityAPI(api_key)

The Singularity API is available through api.singularity.energy.

Details on the specific HTTP endpoints can be found in the API’s official documentation.

All API calls are done with once (no retry logic) and are sent with an X-Api-Key header and a User-Agent header.

calculate_generated_carbon_intensity(genfuelmix, region, source='EGRID_2019')

Calculate the intensity for a given genfuelmix.

The generated rate is calculated by multiplying the generated MW for each fuel type by its emission factor for the given source. You can find all sources listed from a call to the get_all_emission_factors function. Each object in the returned list will have an id which can be passed as the source parameter to this function.

Parameters:
  • genfuelmix – the data part of a generated_fuel_mix event
  • region – a region from the Regions enum
  • source – (default: EGRID_2019) a string representing the source data to use for the emission factors.
Returns:

the rate of carbon emissions for a genfuelmix in lbs/MWh
Raises:

an APIException if a bad response code is returned
calculate_marginal_carbon_intensity(fuelmix_percents, region, source='EGRID_2019')

Calculate the intensity for a given fuelmix percentage

Parameters:
  • fuelmix_percents – the data part of a marginal_fuel_mix event
  • region – a region from the Regions enum
  • source – (default: EGRID_2019) a string representing the source data to use for the emission factors
Returns:

the rate of carbon emissions for a fuelmix in lbs/MWh
Raises:

an APIException if a bad response code is returned
carbon_flow_by_region(datestring, regions=['ISONE', 'NYISO', 'PJM', 'IESO'])

Get the region_flow and carbon_intensity for the listed regions.

Parameters:
  • datestring – the ISO8601 string to use to find all the events
  • regions – (default: [‘ISONE’, ‘NYISO’, ‘PJM’, ‘IESO’]) a list of strings as the regions to search for
Returns:

a dict of region codes -> carbon_intensity, region_flow & generated_fuel_mix events for the timestamp
find_all_region_events(dedup_keys)

Find all events with the given dedup keys.

Parameters:dedup_keys – the list of dedup keys to check for existence
Returns:a list of events found by the provided keys
Raises:APIException if any events are not found
find_region_event(dedup_key)

Find an event by its dedup key.

Any region event will have a dedup_key as a top level field:

from datetime import datetime as dt, timedelta as td
from singularity import SingularityAPI, Regions

singularity = SingularityAPI('API_KEY')
nowstring = dt.utcnow().isoformat() + 'Z'
before = (dt.utcnow() - td(minutes=10)).isoformat() + 'Z'
events, pagination = singularity.search_region_events(
    Regions.ISONE,
    'generated_fuel_mix',
    before,
    nowstring
)
# get the dedup_key from the event
key = events[0]['dedup_key']
Parameters:dedup_key – the deduplication key for the event
Returns:a single region event or None if not found and we’re told not to raise an exception
Raises:APIException if there is a bad response code, e.g. 404
get_all_emission_factors()

Fetch all the emission factors available in the emissions API.

Returns list:a list of all supported emission factor sources and their values
latest_region_events(region_or_postal_code, event_type='carbon_intensity', emission_factor=None)

Get the latest region events for a region or postal code.

Parameters:
  • region_or_postal_code – the region or postal code to query. Either a region from the Regions enum or a string of a postal code
  • event_type – (default: carbon_intensity) the forecast event type to query for currently only carbon_intensity and generated_fuel_mix are supported
  • emission_factor – (default: EGRID_u2018) he emission factor used to calculate carbon intensity possible values: EGRID_u2018, EGRID_2018, EGRID_u2019, EGRID_2019
Returns:

a dict of the latest event and forecasts for the event
Raises:

an APIException if a bad response code is returned
search_region_events(region, event_type, start, end, filter_=None, page=None, per_page=None)

Search for region events over a period of time.

Currently, the supported regions are:
  • ISONE
  • NYISO
  • PJM
  • IESO
  • CAISO
  • MISO
  • SPP
  • BPA

Regions are updated often so check back soon if you want to use one that isn’t listed.

The region events that are currently supported can be found in the notes section of the documentation.

Usage:

from singularity import SingularityAPI, Regions
s = SingularityAPI('API_KEY')
region_string = 'PJM'
region = Regions(region_string)  # or you can use Regions.PJM
events, pagination = s.search_region_events(region, 'carbon_intensity', '2020-01-20T00:00:00Z', '2020-01-21T00:00:00Z')
Parameters:
  • region – a region from the Regions enum
  • event_type – an event type to search for
  • start – an iso8601 datetime string with a timezone
  • end – an iso8601 datetime string with a timezone
  • filter – a string in the format key:value to filter the events for. a filter either looks in meta or data objects. Filters must be in the format of data.some_key:some_value
  • page – (optional) a number to indicate which page of results to return
  • per_page – (optional) the number of events to return per page. default is 300, maximum is 1,000
Returns:

an array of region events, and a dict with pagination information
Raises:

APIException if there is a bad response code
search_region_events_for_postal_code(postal_code, event_type, start, end, filter_=None, page=None, per_page=None)

Search for region events by a postal code instead of a region.

Currently only ISONE, NYISO, and PJM have mappings from postal code <> ISO region. Any postal codes from any other region, for example, California, will not be found.

Parameters:
  • postal_code – a string of a postal code to use for the search, e.g. 02139
  • event_type – a string of the event type to search for
  • start – an iso8601 datetime string with a timezone
  • end – an iso8601 datetime string with a timezone
  • filter – (optional) a string in the format key:value to filter the events for
  • page – (optional) a number to indicate which page of results to return
  • per_page – (optional) the number of events to return per page. default is 300, maximum is 1,000
Returns:

an array of region events, and a dict with pagination information
Raises:

APIException if there is a bad response code