Search and retrieve North American electricity tariffs, including rate structures, applicability properties, documents and the effective-dated history of a master tariff. The list endpoint exposes 33 documented query parameters for filtering by utility, territory, customer class, service type, tariff type and effective date.
{
"openapi": "3.1.0",
"info": {
"title": "signal",
"version": "2022-12-21-Signal"
},
"servers": [
{
"url": "https://api.genability.com"
}
],
"components": {
"securitySchemes": {
"sec0": {
"type": "http",
"scheme": "basic"
}
}
},
"security": [
{
"sec0": []
}
],
"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"
]
}
}
},
"/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
}
},
"/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
}
},
"/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
}
},
"/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
}
},
"/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\u2019ll populate this by geo-tagging the address.",
"format": "double"
},
"lat": {
"type": "number",
"description": "Latitude of the address. We\u2019ll 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\u2019s 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",
# --- truncated at 32 KB (236 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/genability/refs/heads/main/openapi/genability-signal-openapi.json