Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: signal Rest API
version: 2022-12-21-Signal
servers:
- url: https://api.genability.com
security:
- sec0: []
tags:
- name: Rest
paths:
/rest/echo/{error_code}:
get:
summary: Echo Overview
description: Validate how you are calling the Arcadia APIs and debug request formatting, authentication, and input values.
operationId: echo
parameters:
- name: errorCode
in: path
schema:
type: string
enum:
- '200'
- '301'
- '400'
- '403'
- '404'
- '500'
required: true
deprecated: false
x-readme:
code-samples:
- language: text
code: GET /rest/echo/hello
- language: text
code: GET /rest/echo
name: Basic
- language: text
code: GET /rest/echo/authenticate
name: Authenticate
- language: text
code: GET /rest/echo/validate
name: Validate
samples-languages:
- text
tags:
- Rest
/rest/echo/hello:
get:
summary: Echo Hello
description: Return a Hello World response when the passed-in credentials are valid or an unauthorized response when they are invalid.
operationId: echo-api-hello
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Rest
/rest/echo/errors:
get:
summary: Simulate Errors
description: Simulate possible error messages to test how your application responds to API errors.
operationId: echo-api-errors
parameters:
- name: errorCode
in: query
schema:
type: string
enum:
- '200'
- '301'
- '400'
- '403'
- '404'
- '500'
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"success\",\n \"count\": 1,\n \"type\": null,\n \"results\": [\n \"success\"\n ]\n}"
schema:
type: object
properties:
status:
type: string
example: success
count:
type: integer
example: 1
default: 0
type: {}
results:
type: array
items:
type: string
example: success
'301':
description: '301'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"error\",\n \"count\": 2,\n \"type\": \"Error\",\n \"results\": [\n {\n \"code\": \"301\",\n \"message\": \"Moved Permanently\",\n \"objectName\": \"http\"\n },\n {\n \"code\": \"301\",\n \"message\": \"Moved Permanently\",\n \"objectName\": \"http\",\n \"propertyName\": \"someProperty\"\n }\n ]\n}"
schema:
type: object
properties:
status:
type: string
example: error
count:
type: integer
example: 2
default: 0
type:
type: string
example: Error
results:
type: array
items:
type: object
properties:
code:
type: string
example: '301'
message:
type: string
example: Moved Permanently
objectName:
type: string
example: http
'400':
description: '400'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"error\",\n \"count\": 2,\n \"type\": \"Error\",\n \"results\": [\n {\n \"code\": \"301\",\n \"message\": \"Moved Permanently\",\n \"objectName\": \"http\"\n },\n {\n \"code\": \"301\",\n \"message\": \"Moved Permanently\",\n \"objectName\": \"http\",\n \"propertyName\": \"someProperty\"\n }\n ]\n}"
schema:
type: object
properties:
status:
type: string
example: error
count:
type: integer
example: 2
default: 0
type:
type: string
example: Error
results:
type: array
items:
type: object
properties:
code:
type: string
example: '301'
message:
type: string
example: Moved Permanently
objectName:
type: string
example: http
'403':
description: '403'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"error\",\n \"count\": 2,\n \"type\": \"Error\",\n \"results\": [\n {\n \"code\": \"403\",\n \"message\": \"Not Authorized\",\n \"objectName\": \"http\"\n },\n {\n \"code\": \"403\",\n \"message\": \"Not Authorized\",\n \"objectName\": \"http\",\n \"propertyName\": \"someProperty\"\n }\n ]\n}"
schema:
type: object
properties:
status:
type: string
example: error
count:
type: integer
example: 2
default: 0
type:
type: string
example: Error
results:
type: array
items:
type: object
properties:
code:
type: string
example: '403'
message:
type: string
example: Not Authorized
objectName:
type: string
example: http
'404':
description: '404'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"error\",\n \"count\": 2,\n \"type\": \"Error\",\n \"results\": [\n {\n \"code\": \"404\",\n \"message\": \"Not Found\",\n \"objectName\": \"http\"\n },\n {\n \"code\": \"404\",\n \"message\": \"Not Found\",\n \"objectName\": \"http\",\n \"propertyName\": \"someProperty\"\n }\n ]\n}"
schema:
type: object
properties:
status:
type: string
example: error
count:
type: integer
example: 2
default: 0
type:
type: string
example: Error
results:
type: array
items:
type: object
properties:
code:
type: string
example: '404'
message:
type: string
example: Not Found
objectName:
type: string
example: http
'500':
description: '500'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"error\",\n \"count\": 1,\n \"type\": \"Error\",\n \"results\": [\n \"A server error has occurred. Sorry. It has been logged and we will work to fix it.\"\n ]\n}"
schema:
type: object
properties:
status:
type: string
example: error
count:
type: integer
example: 1
default: 0
type:
type: string
example: Error
results:
type: array
items:
type: string
example: A server error has occurred. Sorry. It has been logged and we will work to fix it.
deprecated: false
tags:
- Rest
/rest/echo/authenticate:
get:
summary: Validate Authentication
description: Quickly validate the appId and appKey you are using. A successful response indicates they are valid.
operationId: echo-api-authenticate
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Rest
/rest/echo/validate:
get:
summary: Validate Input Formats
description: Validate whether an input value is in a valid and recognized format, including dates, times, integers, and arrays.
operationId: echo-api-validate
parameters:
- name: dateTime
in: query
description: Validates the passed in string to the ISO 8601 format (e.g. the date and time you want to validate). See the example below for a valid format.
schema:
type: string
- name: integer
in: query
description: Validates the passed in integer to validate it is recognized as an integer.
schema:
type: integer
format: int32
- name: array
in: query
description: Validates the passed in array to validate it is in a recognized format.
schema:
type: array
items:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Rest
/rest/v1/ondemand/calculate:
post:
summary: Calculate Cost
description: Run one on-demand cost calculation for a tariff, date range, and calculation inputs.
operationId: calculate
requestBody:
content:
application/json:
schema:
type: object
required:
- masterTariffId
- fromDateTime
- toDateTime
- propertyInputs
properties:
masterTariffId:
type: integer
description: Unique Arcadia ID for the master tariff of this tariff version.
format: int64
fromDateTime:
type: string
description: Starting date and time for this calculation.
default: '2021-08-11T00:00:00-07:00'
format: date
toDateTime:
type: string
description: End date and time for this calculation.
default: '2022-08-11T00:00:00-07:00'
format: date
propertyInputs:
type: array
description: Specify the usage data and applicabilities for the calculation as an Array of PropertyData
items:
properties:
keyName:
type: string
description: The key name of the property associated with this input. The most common one will be consumption (which is the kWh for the period), and second most common is demand (kW), but can also be applicability properties like cityLimits or hasElectricVehicle
fromDateTime:
type: string
description: The start of the period where this property is applicable. (Default= fromDateTime for the calculation request)
format: date
toDateTime:
type: string
description: The end of the period where this property is applicable. (Default= toDateTime for the calculation request)
format: date
period:
type: string
description: 'The Time of Use type: OFF_PEAK, PARTIAL_PEAK, ON_PEAK or CRITICAL_PEAK. As input, can alternatively be specified as a Date Period'
dataValue:
type: string
description: The value to use for this property. Can be input as the native type, but when populated will be returned as a string. (Required on input when not using dataSeries. dataValue or dataSeries is required, but requests must not specify both.)
dataSeries:
type: array
description: Used for properties which have many values, such as consumption time series data. (Required on input when not using dataValue. dataValue or dataSeries is required, but requests must not specify both.)
default: []
items:
type: number
format: double
duration:
type: integer
description: Used with dataSeries to specify the time span corresponding to each value in the dataSeries. (Required on input when using dataSeries)
format: int32
unit:
type: string
description: 'Where applicable, this is the unit of the value. Most common are: "kWh" - for keys of consumption, "kW" - for keys of demand.'
dataFactor:
type: number
description: For applicable properties (like usage data) scales the inputs by the value provided
format: double
operator:
type: string
description: For profile data only. Specifies how profiles should be joined.
enum:
- +
- '-'
required:
- keyName
type: object
detailLevel:
type: string
description: Toggles the level of details for the calculation result.
default: ALL
enum:
- ALL
- TOTAL
- CHARGE_TYPE
- CHARGE_TYPE_AND_TOU
- RATE
groupBy:
type: string
description: This controls how the calculation details are grouped. Examples (Optional, Defaults to the natural grouping for the rates)
default: MONTH
enum:
- ALL
- YEAR
- MONTH
- DAY
- HOUR
- QTRHOUR
excludeChargeClass:
type: array
description: Specifies a charge class to exclude from the calculation results. Available options are TRANSMISSION, DISTRIBUTION, SUPPLY, TAX, CONTRACTED, USER_ADJUSTED, AFTER_TAX, and OTHER.
items:
type: string
zipCode:
type: string
description: See examples for the cases when you need location data. When populating this field you should also populate country too. (Optional and usually not needed)
country:
type: string
description: Use this when passing in a zipCode or postCode, and set it to the ISO Country Code of your zipCode since some countries use the same format (Use with zipCode)
address:
type: object
description: An alternative to using zipCode and country. (Optional and usually not needed)
properties:
addressString:
type: string
description: Full free text string representing address. This is the property that is usually passed in. Zip will suffice but the full address is better.
addressName:
type: string
description: A name associated with the address (e.g. Headquarters). Not usually set.
address1:
type: string
description: First part of the address. Usually populated by our address validation from the addressString passed in.
address2:
type: string
description: Second part of the address. Usually populated by our address validation from the addressString passed in.
city:
type: string
description: City of the address. Usually populated by our address validation from the addressString passed in.
state:
type: string
description: State of the address. Usually populated by our address validation from the addressString passed in.
zip:
type: string
description: Postcode or ZIP code of the address. Usually populated by our address validation from the addressString passed in.
country:
type: string
description: Usually the ISO Country Code of the address. Usually populated by our address validation from the addressString passed in.
lon:
type: number
description: Longitude of the address. We’ll populate this by geo-tagging the address.
format: double
lat:
type: number
description: Latitude of the address. We’ll populate this by geo-tagging the address.
format: double
tariffEffectiveOn:
type: string
description: This field enables doing a calculation with a single, specified version of a given tariff. For example, if the user specifies that they want to use the 2016-01-01 version of PG&E’s E-1 tariff, any calculation, regardless of it's time range, would use the rate data from that version and only that version of the tariff.
format: date
rateInputs:
type: array
description: The rate input values are used to override existing rates on the tariff during the calculation. This enables modeling and/or setting customer specific rates during a calculation.
items:
properties:
tariffRateId:
type: integer
description: Unique Genability ID (primary key) for each tariff rate
format: int64
tariffId:
type: integer
description: Associates the rate with a tariff (foreign key)
format: int64
riderTariffId:
type: integer
description: Tariff ID of the rider attached to this tariff version. null otherwise
format: int64
riderId:
type: integer
description: Master Tariff ID of the rider linked to this tariff rate.
format: int64
tariffSequenceNumber:
type: integer
description: Sequence of this rate in the tariff, for display purposes only (e.g. this is the order on the bill)
format: int32
tariffBookSequenceNumber:
type: integer
description: Sequence of this rate in the tariff source document, if it differs from tariffSequenceNumber
format: int32
rateGroupName:
type: string
description: Name of the group this rate belongs to
tariffBookRateGroupName:
type: string
description: Name of the group this rate belongs to in the tariff source document, if it differs from rateGroupName
rateName:
type: string
description: Name of this rate. Can be null (in which case use the group name)
tariffBookRateName:
type: string
description: Name of this rate in the tariff source document, if it differs from rateName
rateBands:
type: array
description: List of TariffRateBands
items:
properties:
rateAmount:
type: string
rateUnit:
type: string
enum:
- COST_PER_UNIT
- PERCENTAGE
type: object
fromDateTime:
type: string
description: If populated, this indicates the rates effective date is not the same as that of its tariff
format: date
toDateTime:
type: string
description: If populated, this indicates the rates end date is not the same as that of its tariff
format: date
territory:
type: string
description: Only populated when this rate applies to a different region than the whole tariff (e.g. California Baseline Regions). This how-to has more.
season:
type: string
description: The season this rate applies to. Only used for seasonal rates (null otherwise)
timeOfUse:
type: string
description: The time period this rate applies to. Only used for TOU rates (null otherwise)
chargeType:
type: string
description: 'Possible values: FIXED_PRICE - a fixed charge for the period CONSUMPTION_BASED - based on quantity used (e.g. kW/h) DEMAND_BASED - based on the peak demand (e.g. kW) QUANTITY - a rate per number of items (e.g. $5 per street light) FORMULA - a rate that has a specific or custom formula MINIMUM - a minimum amount that the LSE will charge you, overriding lower pre-tax charges MAXIMUM - a maximum amount that the LSE will charge you, overriding higher pre-tax charges TAX - a percentage tax rate which is applied to the sum of all of the other charges on a bill'
chargeClass:
type: string
description: 'A comma separated string that indicates what class(es) of charges this rate is for. Values include: SUPPLY - Energy related charges. TRANSMISSION - Transmission level delivery charges. DISTRIBUTION - Distribution level (last mile) delivery charges of moving electricity into your home or business. TAX - Tax surcharges which appear in the utility tariff document. CONTRACTED - Charges which get replaced or overridden when you pass the retail (contracted) energy supply rate in the calculation. USER_ADJUSTED - Additional or custom rates you can add to a public or private tariff. An example would be a local tax rate which Genability does not model but you would want included. AFTER_TAX - Charges which apply post utility and other taxes. A good example would be the California Climate credit which is applied to the bill after the taxes are applied to the bill subtotal. OTHER - Charges which cannot be classified in any of the above buckets. This is very rare. NON_BYPASSABLE - Charges which cannot be offset by credits (usually Net Metering)'
chargePeriod:
type: string
description: 'Indicates what period this charge is calculated for. This is usually the same as the billing period (and is usually monthly) but can be other intervals. Possible values are: MONTHLY - each calendar month DAILY - calculated for each day QUARTERLY - every 3 months ANNUALLY - every year'
transactionType:
type: string
description: Indicates whether this rate is BUY (charge when importing from the grid, no credit when exporting), SELL (credit when exporting to the grid, no charge when importing), or NET (charge when importing, credit when exporting) with imports and exports resolved according the the chargePeriod. BUY_IMPORT (charge only when importing) and SELL_EXPORT (credit only when exporting) indicate that imports and exports are resolved in real-time (instantaneous netting).
quantityKey:
type: string
description: 'When not null, the property that defines the type of quantity this rate applies to. (e.g. billingMeter : property which defines the number of billing meters the rate will apply to)'
applicabilityKey:
type: string
description: 'When not null, the property that defines the eligibility criteria for this rate. (e.g. connectionType : property which defines how the service is connected to the grid)'
variableLimitKey:
type: string
description: 'When populated this defines the variable which determines the upper limit(s) of this rate. (e.g. demandMultiplierTierswithkWhTiers2416: property which uses the demand value to drive the consumption limits)'
variableRateKey:
type: string
description: 'When not null, this is the name of the property that defines the variable rate. In this case the rate field is null, or can (rarely) be used as an input to the determination of the variable rate. (e.g massachusettsResidentialRetailPrevailingRates : property which provides the regional prevailing residential supply rate for Massachusetts )'
variableFactorKey:
type: string
description: 'When not null, this is the name of the property that defines the variable factor to apply to this rate. (e.g billingPeriodProrationFactor: property which defines a prorated number of billing days)'
type: object
minimums:
type: boolean
description: This field enables enforcing minimum charges on this calculation.
default: true
billingPeriod:
type: boolean
description: A true or false flag. If the dates of the calculation represent an actual billing cycle, then you should set this to true. This will give you precise values for items like fixed charges. When it’s not set, or set to false, these charges will be prorated across the number of days in the calculation.
default: false
applyUtilityTax:
type: boolean
description: When true, the calculation attempts to apply a utility tax to the provided location. (Optional, Default = true when zipCode and country, or address provided, false otherwise)
examples:
Calculation With Arcadia's Typical Electricity Dataset:
value:
masterTariffId: 512
fromDateTime: '2021-08-11T00:00:00-07:00'
toDateTime: '2022-08-11T00:00:00-07:00'
detailLevel: ALL
groupBy: MONTH
minimums: true
billingPeriod: false
propertyInputs:
- keyName: baselineType
dataValue: typicalElectricity
- keyName: buildingId
dataValue: RESIDENTIAL
summary: Calculation With Arcadia's Typical Electricity Dataset
Calculating Last Month's Electricity Bill:
value:
fromDateTime: '2016-07-13T00:00:00-07:00'
toDateTime: '2016-08-11T00:00:00-07:00'
masterTariffId: 522
groupBy: MONTH
detailLevel: RATE
billingPeriod: true
propertyInputs:
- keyName: consumption
fromDateTime: '2016-07-13T00:00:00-07:00'
duration: 3600000
dataSeries:
- 1.58
- 1.58
- 1.58
- 1.58
- 1.59
- 1.6
- 1.61
- 1.62
- 1.63
- 1.63
- 1.64
- 1.64
- 1.66
- 1.68
- 1.7
- 1.73
- 1.75
- 1.76
- 1.78
- 1.8
- 1.8
- 1.81
- 1.81
- 1.81
- 1.84
- 1.88
- 1.91
- 1.95
- 1.97
- 1.98
- 2
- 2.01
- 2.02
- 2.03
- 2.04
- 2.05
- 2.06
- 2.07
- 2.08
- 2.09
# --- truncated at 32 KB (179 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/genability/refs/heads/main/openapi/genability-rest-api-openapi.yml