Client API Reference

`tyba_client.client`

class Market(*values)

Indicator for which market to pull pricing data for

RT = 'realtime': Indicates pricing data for the Real Time (RT) Market is desired

DA = 'dayahead': Indicates pricing data for the Day Ahead (DA) Market is desired

class AncillaryService(*values)

Indicator for which service to pull pricing data for

REGULATION_UP = 'Regulation Up': Indicates pricing data for the Regulation Up service is desired

REGULATION_DOWN = 'Regulation Down': Indicates pricing data for the Regulation Down service is desired

RESERVES = 'Reserves': Indicates pricing data for the Reserves service is desired

ECRS = 'ECRS': Indicates pricing data for the ERCOT Contingency Reserve Service is desired

class Ancillary(services)

Interface for accessing Tyba’s historical ancillary price data

get_pricing_regions(*, iso, service, market)

Get the name and available year ranges for all ancillary service pricing regions that meet the ISO, service and market criteria.

Parameters:

iso (str) – ISO name. Possible values can be found by calling Services.get_all_isos()
service (AncillaryService) – specifies which ancillary service to pull prices for
market (Market) – specifies whether to pull day ahead or real time prices for the given service

Return type:

Response

Returns:

Response containing an array of JSON objects with schema AncillaryRegionData. For example:

[
    {
        'region': 'Pacific Northwest - SP15',
        'start_year': 2010,
        'end_year': 2025
    },
    {
        'region': 'WAPA',
        ...
    },
    ...
]

get_prices(*, iso, service, market, region, start_year, end_year)

Get price time series data for a single region/service combination

Parameters:

iso (str) – ISO name. Possible values can be found by calling Services.get_all_isos()
service (AncillaryService) – specifies which ancillary service to pull prices for
market (Market) – specifies whether to pull day ahead or real time prices for the given service
region (str) – specific region within the ISO to pull prices for. Possible values can be found by calling get_pricing_regions()
start_year (int) – the year prices should start
end_year (int) – the year prices should end

Return type:

Response

Returns:

Response containing a JSON object with schema PriceTimeSeries. For example:

{
    'prices': [
        61.7929,
        58.1359,
        61.4939,
        ....
    ],
    'datetimes': [
        '2022-01-01T00:00:00Z',
        '2022-01-01T01:00:00Z',
        '2022-01-01T02:00:00Z',
        ....
    ],
}

class LMP(services)

Interface for accessing Tyba’s historical energy price data

get_all_nodes(*, iso)

Get node names, IDs and other metadata for all nodes within the given ISO territory.

Parameters:

iso (str) – ISO name. Possible values can be found by calling Services.get_all_isos()

Return type:

Response

Returns:

Response containing an array of JSON objects with schema NodeData. For example:

[
    {'da_end_year': 2025,
     'rt_end_year': 2025,
     'rt_start_year': 2023,
     'name': 'CLAP_WWRSR1-APND',
     'id': '10017280350',
     'da_start_year': 2023,
     'zone': 'SDGE',
     'type': 'GENERATOR'},
    {'da_start_year': 2015,
     'rt_end_year': 2025,
     'zone': '',
     'name': 'ELCENTRO_2_N001:IVLY2',
     'type': 'SPTIE',
     'substation': '',
     'da_end_year': 2025,
     'id': '10003899356',
     'rt_start_year': 2015},
    ...
]

get_prices(*, node_ids, market, start_year, end_year)

Get price time series data for a list of node IDs

Parameters:

node_ids (list[str]) – list of IDs for which prices are desired - Maximum length is 8 IDS
market (Market) – specifies whether to pull day ahead or real time market prices
start_year (int) – the year prices should start
end_year (int) – the year prices should end

Return type:

Response

Returns:

Response containing a JSON object whose keys are node IDs and whose values are objects with schema PriceTimeSeries. For example:

{
    '10000802793': {
        'prices': [
            61.7929,
            58.1359,
            61.4939,
            ....
        ],
        'datetimes': [
            '2022-01-01T00:00:00',
            '2022-01-01T01:00:00',
            '2022-01-01T02:00:00',
            ....
        ],
        ...
    },
    '20000004677': {
        ...
    },
    ...
}

search_nodes(location=None, node_name_filter=None, iso_override=None)

Get a list of matching nodes based on search criteria. Multiple search criteria (e.g. location and node_name_filter) can be applied in a single request.

Parameters:

location (Optional[str]) –
location information. There are 3 possible forms:
- city/state, e.g. ‘dallas, tx’
- address, e.g. ‘12345 Anywhere Street, Anywhere, TX 12345’
- latitude and longitude, e.g. ‘29.760427, -95.369804’
node_name_filter (Optional[str]) – partial node name with which to perform a pattern-match, e.g. ‘HB_’
iso_override (Optional[str]) – ISO signifier, used to constrain search to a single ISO. When equal to None, all ISOs are searched based on other criteria. Possible values can be found by calling Services.get_all_isos()

Return type:

Response

Returns:

Response containing a JSON object. If matching nodes are found, a ‘nodes’ item will contain an array of objects with schema NodeSearchData. If no matching nodes are found, an error code will be returned. As an example, a successful search result might look like:

{
    "nodes": [
        {
            "node/name": "HB_BUSAVG",
            "node/id": "10000698380",
            "node/iso": "ERCOT",
            "node/lat": 30.850714,
            "node/lng": -97.877628,
            "node/distance-meters": 500.67458
        },
        {
            "node/name": ...,
            ...
        },
        ...
    ]
}

class Services(client)

Interface for accessing Tyba’s historical price data

ancillary: Ancillary: Interface for accessing Tyba’s historical ancillary price data

lmp: LMP: Interface for accessing Tyba’s historical energy price data

get_all_isos()

Get of list of all independent system operators and regional transmission operators (generally all referred to as ISOs) represented in Tyba’s historical price data

Return type:: Response
Returns:: Response containing JSON array of strings of the available ISO names

class Client(personal_access_token, host='https://dev.tybaenergy.com', request_args=None)

High level interface for interacting with Tyba’s API.

Parameters:: personal_access_token (str) – required for using the python client/API, contact Tyba to obtain

services: Services: Interface for accessing Tyba’s historical price data

forecast: Forecast: Interface for accessing Tyba’s historical price data

property ancillary: Ancillary: Shortcut to client.services.ancillary

property lmp: LMP: Shortcut to client.services.lmp

schedule(model)

Schedule a model simulation based on the given inputs

Parameters:

model (Union[StandaloneStorageModel, PVStorageModel, PVGenerationModel, DCExternalGenerationModel, ACExternalGenerationModel]) – a class instance of one of the model classes, e.g. StandaloneStorageModel. Contains all required inputs for running a simulation

Return type:

Response

Returns:

Response whose status code indicates whether the model was successfully scheduled. If successful, the response will contain a JSON object with an 'id' for the scheduled model run. This id can be used with the get_status() and wait_on_result() endpoints to retrieve status updates and model results. The presence of issues can be easily checked by calling the raise_for_status() method of the response object. For example:

resp = client.schedule(pv)
resp.raise-for_status()  # this will raise an error if the model was not successfully scheduled
id_ = resp.json()["id"]
res = client.wait_on_result(id_)

get_status(run_id)

Check the status and retrieve the results of a scheduled model simulation. If a simulation has not completed, this endpoint returns the simulation status/progress. If the simulation has completed, it returns the model results.

Parameters:: run_id (str) – ID of the scheduled model simulation
Returns:: Response containing a JSON object with schema ModelStatus

get_status_v1(run_id)

Deprecated, please use get_status(), which will support additional results schemas in the near future. Identical to get_status(), but returns results for completed simulations in the “V1” SLD-style schema

Parameters:: run_id (str) – ID of the scheduled model simulation
Returns:: Response containing a JSON object with schema ModelStatus (except with a different schema for result)

wait_on_result(run_id, wait_time=5, log_progress=False)

Poll for simulation status and, once complete, return the model results

Parameters:

run_id (str) – ID of the scheduled model simulation
wait_time (int) – time in seconds to wait between polling/updates
log_progress (bool) – indicate whether updates/progress should be logged/displayed. If True, will report both status and progress information

Return type:

dict

Returns:

results dictionary equivalent to ModelStatus.result returned by get_status(), with the exact schema depending on the model inputs

wait_on_result_v1(run_id, wait_time=5, log_progress=False)

Deprecated, please use :meth:`wait_on_result, which will support additional results schemas in the near future`. Identical to wait_on_result(), but returns results for completed simulations in the “V1” SLD-style schema

Parameters:

run_id (str) – ID of the scheduled model simulation
wait_time (int) – time in seconds to wait between polling/updates
log_progress (bool) – indicate whether updates/progress should be logged/displayed. If True, will report both status and progress information

Returns:

results dictionary with “V1” SLD-style schema

class NodeType(*values)

Indicator of which type of physical infrastructure is associated with a particular market node

GENERATOR = 'GENERATOR': Not sure

SPTIE = 'SPTIE': Not sure

LOAD = 'LOAD': Not sure

INTERTIE = 'INTERTIE': Not sure

AGGREGATE = 'AGGREGATE': Not sure

HUB = 'HUB': Not sure

NA = 'N/A': Not sure

class NodeData

Schema for node metadata

field name: str [Required]: Name of the node

field id: str [Required]: ID of the node

field zone: str [Required]: Zone where the node is located within the ISO territory

field type: NodeType [Required]: Identifier that indicates physical infrastructure associated with this node

field da_start_year: float [Required]: First year in the Day Ahead (DA) market price dataset for this node

field da_end_year: float [Required]: Final year in the Day Ahead (DA) market price dataset for this node

field rt_start_year: int [Required]: First year in the Real Time (RT) market price dataset for this node

field rt_end_year: int [Required]: Final year in the Real Time (RT) market price dataset for this node

field substation: Optional[str] = None: Indicator of the grid substation associated with this node (not always present)

class PriceTimeSeries

Schema for pricing data associated with a particular energy price node or ancillary pricing region

field datetimes: list[str] [Required]

Beginning-of-interval datetimes for the hourly pricing given in local time.

For energy prices, the datetimes are timezone-naive (no timezone identifier) but given in the local timezone (i.e. including Daylight Savings Time or DST). E.g. The start of the year 2022 in ERCOT is given as ‘2022-01-01T00:00:00’ as opposed to ‘2022-01-01T00:00:00-6:00’. Leap days are represented by a single hour, which should be dropped as a post-processing step.
For ancillary prices, the datetimes are in local standard time (i.e. not including DST) but appear to be in UTC (“Z” timezone identifier). E.g. The start of the year 2022 in ERCOT is given as ‘2022-01-01T00:00:00Z’ and not ‘2022-01-01T00:00:00-6:00’. Leap days are not included.

field prices: list[float] [Required]: Average hourly settlement prices for hours represented by datetimes.

class NodeSearchData

Schema for search-specific node metadata. The (name ‘xxxx’) to the right of the field names can be ignored

field node_name: str [Required] (alias 'node/name'): Name of the node

field node_id: str [Required] (alias 'node/id'): ID of the node

field node_iso: str [Required] (alias 'node/iso'): ISO that the node belongs to

field node_longitude: float [Required] (alias 'node/lng'): longitude of the point on the electrical grid associated with the node

field node_latitude: float [Required] (alias 'node/lat'): latitude of the point on the electrical grid associated with the node

field node_distance_meters: Optional[float] = None (alias 'node/distance-meters'): Distance from the node to the location parameter passed to search_nodes(). Not present if location is not given.

class AncillaryRegionData

Schema for ancillary region metadata

field region: str [Required]: Name of the region

field start_year: int [Required]: First year in price dataset for the region and specified service

field da_end_year: int [Required]: Final year in price dataset for the region and specified service

class ModelStatus

Schema for model status and results

field status: str [Required]: Status of the scheduled run. Possible values are explained in Tyba Model Run Status Codes

field progress: Optional[str] [Required]

Percentage value indicating the progress towards completing a model simulation. Only present if status is not 'complete'.

Note that in some cases the simulation may involve multiple optimization iterations, and the progress may appear to start over as each additional iteration is undertaken

field result: Union[GenerationModelResults, PVStorageModelResults, StandaloneStorageModelSimpleResults, StandaloneStorageModelWithDownstreamResults, None] [Required]: Model simulation results dictionary with schema defined depending on the model inputs, e.g. scheduling a PVGenerationModel will return a dictionary with schema GenerationModelResults. Only present if status is 'complete'

`tyba_client.forecast`

class Forecast(client)

most_recent(object_name, product, start_time, end_time, forecast_type=None, predictions_per_hour=None, prediction_lead_time_mins=None, horizon_mins=None)

Parameters:

object_name (str)
product (str)
start_time (datetime)
end_time (datetime)
forecast_type
predictions_per_hour
prediction_lead_time_mins
horizon_mins

Returns:

most_recent_probabilistic(object_name, product, start_time, end_time, quantiles, forecast_type=None, predictions_per_hour=None, prediction_lead_time_mins=None, horizon_mins=None)

Parameters:

object_name (str)
product (str)
start_time (datetime)
end_time (datetime)
quantiles (List[float])
forecast_type
predictions_per_hour
prediction_lead_time_mins
horizon_mins

Returns:

vintaged(object_name, product, start_time, end_time, days_ago, before_time, exact_vintage=False, forecast_type=None, predictions_per_hour=None, prediction_lead_time_mins=None, horizon_mins=None)

Parameters:

object_name (str)
product (str)
start_time (datetime)
end_time (datetime)
days_ago (int)
before_time (time)
exact_vintage (bool)
forecast_type
predictions_per_hour
prediction_lead_time_mins
horizon_mins

Returns:

vintaged_probabilistic(object_name, product, start_time, end_time, quantiles, days_ago, before_time, exact_vintage=False, forecast_type=None, predictions_per_hour=None, prediction_lead_time_mins=None, horizon_mins=None)

Parameters:

object_name (str)
product (str)
start_time (datetime)
end_time (datetime)
quantiles (List[float])
days_ago (int)
before_time (time)
exact_vintage (bool)
forecast_type
predictions_per_hour
prediction_lead_time_mins
horizon_mins

Returns:

by_vintage(object_name, product, vintage_start_time, vintage_end_time, forecast_type=None, predictions_per_hour=None, prediction_lead_time_mins=None, horizon_mins=None)

Parameters:

object_name (str)
product (str)
vintage_start_time (datetime)
vintage_end_time (datetime)
forecast_type
predictions_per_hour
prediction_lead_time_mins
horizon_mins

Returns:

by_vintage_probabilistic(object_name, product, quantiles, vintage_start_time, vintage_end_time, forecast_type=None, predictions_per_hour=None, prediction_lead_time_mins=None, horizon_mins=None)