Outages¶

Table of Contents

Resource description
List Outages
Create an Outage
Retrieve an Outage
Update an Outage
Delete an Outage

Resource description ¶

All endpoints adhere to the JSON API specification.

Attributes ¶

Name	Description	Required?	Type	Notes
address	Location of the Outage	True	string
circuitType	Type of circuit at Outage	False	string
descriptiveCharacteristics	Characteristics of the Outage	False	string	Accepted values are: - Distribution Overhead - Distribution Underground - Generation - Substation - Transmission - Customer Equipment
duration	Duration of the outage in minutes	False	float	Calculated read-only value
endDatetime	Resolution date and time of the Outage	False	string	ISO 8601 formatted ex. `2014-02-04T16:20:00Z`. See A Note about Timezones.
isPartialRestoration	Outage is one of multiple restoration steps	False	bool	Default: `false`
isReportable	Outage contributes to reports	False	bool	Default: `false`
loadInterrupted	Load interrupted at Outage	False	float
phasesImpacted	Phases impacted at Outage	False	string	Accepted values are: - 1 (A) - 2 (B) - 3 (C) - 1&2 (A & B) - 2&3 (B & C) - 3&1 (A & C) - All Phases
reportedBy	Outage discovery notes	False	string
startDatetime	Beginning date and time of the Outage	True	string	ISO 8601 formatted ex. `2014-02-04T16:20:00Z`. See A Note about Timezones.
totalCustomers	Total customers served by the Utility	True	integer
totalCustomersImpacted	Number of customers impacted by this Outage	True	integer
totalWorkHoursForRestoration	Number of hours to resolve Outage	False	float
voltage	Voltage lost at Outage	False	string

Relationships ¶

Name	Description	Required?	Type
cause	Cause of this Outage	True	Foreign key
circuit	Circuit that was impacted by the Outage	False	Foreign key
customersImpacted	Customers impacted by the Outage	False	Many-to-many
event	Event this Outage belongs to	True	Foreign key
substation	Substation that was impacted by the Outage	False	Foreign key
user	User who created this Outage	False	Foreign key

A Note about Timezones ¶

eRT API is currently timezone naive. eRT API ignores timezone data associated with dates. eRT API’s current timezone handling means a few things:

The API ignores the timezone data that you send. Please send dates localized to the Utility’s timezone. For example, if an Eastern Utility has an outage at 9 am, send the outage’s startDatetime as YYYY-MM-DDT09:00:00Z or YYYY-MM-DDT09:00-04:00. Note that the timezone, UTC or -04:00, doesn’t matter to eRT API.
The API reports all dates as UTC. Please ignore the timezone eRT API returns. Know that the date and time you enter into the API are the date and time the API returns. For example, say you create an outage with startDatetime as YYYY-MM-DDT09:00-04:00. When you read that outage from the API, your response will contain a startDatetime of YYYY-MM-DDT09:00:00Z. Notice how the timezone changed, but the time did not.

Partial Restorations ¶

Outages can be restored in phases.

Step/Switch Restoration ¶

Here is a graph showing customer minutes of interruption for the step/switch restoration scenario:

This event starts at noon and consists of three separate outages. The first outage (blue) shows the 800 customers that were impacted by the feeder opening. The second outage (yellow) reflects the customers that were still out after the crew opened the downstream recloser. The third outage (green) reflects the 50 remaining customers that were without power until 1:30 when the recloser was finally closed.

To record this scenario we would create four resources through the API:

One Event - see Create an Event

Three Outages that belong to the newly created Event - see Create an Outage

The first of the three outages must have the following attributes. Our goal is to create a 30 minute Outage impacting 800 customers where isPartialRestoration is false. Notice that the actual startDatetime and endDatetime can be adjusted to any time as long as a 30 minute duration is specified. These attributes are in addition to other attributes that are required, but not relevant to this example:

{
    "data": {
        "attributes": {
            "startDatetime": "2018-10-13T00:00:00Z",
            "endDatetime": "2018-10-13T00:30:00Z",
            "totalCustomersImpacted": 800,
            "isPartialRestoration": false,
            ...
        },
        ...
    }
}

The second of the three outages must have the following attributes. We want to create a 30 minute Outage impacting 200 customers where isPartialRestoration is true. These attributes are in addition to other attributes that are required, but not relevant to this example:

{
    "data": {
        "attributes": {
            "startDatetime": "2018-10-13T00:30:00Z",
            "endDatetime": "2018-10-13T01:00:00Z",
            "totalCustomersImpacted": 200,
            "isPartialRestoration": true,
            ...
        },
        ...
    }
}

The third of the three outages must have the following attributes. We want to create a 30 minute Outage impacting 50 customers where isPartialRestoration is true. These attributes are in addition to other attributes that are required, but not relevant to this example:

{
    "data": {
        "attributes": {
            "startDatetime": "2018-10-13T01:00:00Z",
            "endDatetime": "2018-10-13T01:30:00Z",
            "totalCustomersImpacted": 50,
            "isPartialRestoration": true,
            ...
        },
        ...
    }
}

After creating these resources through the API we end up with the following records in eRT:

Notice that the table in the bottom right shows 800 “Customer Interruptions”. If these outages were not marked as partial restorations then there would be 1,050 (800 + 200 + 50) customer interruptions.

List Outages ¶

A user must have at least “member” authorization to list Outages for their Utility.

GET https://reliability.api.publicpower.org/v1/outages/¶

Example request:

GET /v1/outages/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken

Request Headers

Authorization – Required OAuth token to authenticate. See Authentication docs.
Content-Type – Content-Type: application/vnd.api+json - JSON API IANA media type

Query Parameters

page (int) – Page Number of results to request.
page_size (int) – Number of results to return per-page.
filter[cause] (int) – Limit results to comma-separated list of Cause IDs.
filter[cause_type] (string) – Limit results to “scheduled” or “unscheduled” causes.
filter[circuit] (int) – Limit results to comma-separated list of Circuit IDs.
filter[event] (int) – Limit results to comma-separated list of Event IDs.
filter[event__utility] (int) – Limit results to comma-separated list of Utility IDs.
filter[outage_duration__max] (int) – Limit outages by a maximum duration specified in minutes.
filter[outage_duration__min] (int) – Limit outages by a minimum duration specified in minutes.
filter[outage_end__max] (datetime) – Limit outages to an ISO 8601 formatted maximum end date.
filter[outage_start__min] (datetime) – Limit outages to an ISO 8601 formatted start date.
filter[search] (string) – Limit results by a search string. The string is checked against the following Outage fields: “address”, “cause”, “circuit”, “end date”, “start date”, and “substation”.
filter[substation] (int) – Limit results to comma-separated list of Substation IDs.
include (string) – Comma-separated list of relationship data to include with the response. Available relationships are “cause”, “circuit”, and “substation”.
sort (string) – Sort a response by the given attribute. Available attributes are “address”, “duration”, “start_datetime”, and “total_customers_impacted”. To specify a descending sort, prefix the attribute with a “-”, for example, “-duration”.

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "first": "https://reliability.api.publicpower.dev/v1/outages/?page=1",
    "last": "https://reliability.api.publicpower.dev/v1/outages/?page=145550",
    "next": "https://reliability.api.publicpower.dev/v1/outages/?page=2",
    "prev": null
  },
    "data": [
      {
        "type": "Outage",
        "id": "1",
        "attributes": {
          "address": "2400 Broadway Avenue",
          "totalCustomersImpacted": 1,
          "startDatetime": "2014-02-04T14:45:00Z",
          "endDatetime": "2014-02-04T16:20:00Z",
          "duration": 95,
          "isPartialRestoration": false,
          "isReportable": true,
          "descriptiveCharacteristics": "",
          "voltage": "",
          "circuitType": "",
          "phasesImpacted": "",
          "loadInterrupted": 0,
          "totalCustomers": 30000,
          "reportedBy": "Customer call-in",
          "totalWorkHoursForRestoration": 0
        },
        "relationships": {
          "event": {
            "data": {
              "type": "Event",
              "id": "2"
            }
          },
          "user": {
            "data": {
              "type": "User",
              "id": "3"
            }
          },
          "circuit": {
            "data": {
              "type": "Circuit",
              "id": "4"
            }
          },
          "cause": {
            "data": {
              "type": "Cause",
              "id": "44"
            }
          },
          "equipmentDetails": {
            "meta": {
              "count": 1
            },
            "data": [
              {
                "type": "EquipmentDetail",
                "id": "1069554"
              }
            ]
          },
          "substation": {
            "data": {
              "type": "Substation",
              "id": "5"
            }
          },
          "customersImpacted": {
            "data": [],
            "meta": {
              "count": 0
            }
          }
        }
      }
    ],
    "meta": {
      "pagination": {
        "page": 1,
        "pages": 145550,
        "count": 145550
      }
    }
}

Status Codes

200 OK – Successful response
401 Unauthorized – You did not provide a valid Authorization: Bearer token.
403 Forbidden – Your user role is not authorized to access this endpoint.

Create an Outage ¶

A user must have at least “member” authorization to create Outages for their Utility.

POST https://reliability.api.publicpower.org/v1/outages/¶

Example request:

POST /v1/outages/ HTTP/1.1
Host: reliability.api.publicpower.org
Authorization: Bearer myaccesstoken
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "Outage",
    "id": "1",
    "attributes": {
      "address": "Test Address",
      "totalCustomersImpacted": 1,
      "startDatetime": "2014-02-04T14:45:00Z",
      "endDatetime": "2014-02-04T15:00:00Z",
      "isPartialRestoration": false,
      "isReportable": true,
      "descriptiveCharacteristics": "Distribution Overhead",
      "voltage": "6900",
      "circuitType": "Radial",
      "phasesImpacted": "1 (A)",
      "loadInterrupted": 100,
      "totalCustomers": 30000,
      "reportedBy": "Customer call-in",
      "totalWorkHoursForRestoration": 10
    },
    "relationships": {
      "event": {
        "data": {
          "type": "Event",
          "id": "83238"
        }
      },
      "user": {
        "data": {
          "type": "User",
          "id": "{{relationship_user_id}}"
        }
      },
      "circuit": {
        "data": {
          "type": "Circuit",
          "id": "236"
        }
      },
      "cause": {
        "data": {
          "type": "Cause",
          "id": "3"
        }
      },
      "substation": {
        "data": {
          "type": "Substation",
          "id": "63"
        }
      },
      "customersImpacted": {
        "data": []
      }
    }
  }
}

Request Headers

Authorization – Required OAuth token to authenticate. See Authentication docs.
Content-Type – Content-Type: application/vnd.api+json - JSON API IANA media type

Example response:

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "Outage",
    "id": "264935",
    "attributes": {
      "address": "Test Address",
      "totalCustomersImpacted": 1,
      "startDatetime": "2014-02-04T14:45:00Z",
      "endDatetime": "2014-02-04T15:00:00Z",
      "duration": 15,
      "isPartialRestoration": false,
      "isReportable": true,
      "descriptiveCharacteristics": "Distribution Overhead",
      "voltage": "6900",
      "circuitType": "Radial",
      "phasesImpacted": "1 (A)",
      "loadInterrupted": 100,
      "totalCustomers": 30000,
      "reportedBy": "Customer call-in",
      "totalWorkHoursForRestoration": 10
    },
    "relationships": {
      "user": {
        "data": {
          "type": "User",
          "id": "5"
        }
      },
      "event": {
        "data": {
          "type": "Event",
          "id": "83238"
        }
      },
      "cause": {
        "data": {
          "type": "Cause",
          "id": "3"
        }
      },
      "substation": {
        "data": {
          "type": "Substation",
          "id": "63"
        }
      },
      "circuit": {
        "data": {
          "type": "Circuit",
          "id": "236"
        }
      },
      "customersImpacted": {
        "meta": {
          "count": 0
        },
        "data": []
      }
    }
  }
}

Status Codes

201 Created – Outage created
400 Bad Request – The POSTed data was malformed.
401 Unauthorized – You did not provide a valid Authorization: Bearer token.
403 Forbidden – Your user role is not authorized to access this endpoint.

Retrieve an Outage ¶

A user must have at least “member” authorization to retrieve Outages for their Utility.

GET https://reliability.api.publicpower.org/v1/outages/(int: outage_id)/¶

Example request:

GET /v1/outages/264935/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken

Request Headers

Authorization – Required OAuth token to authenticate. See Authentication docs.
Content-Type – Content-Type: application/vnd.api+json - JSON API IANA media type

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "Outage",
    "id": "264935",
    "attributes": {
      "address": "Test Address",
      "totalCustomersImpacted": 1,
      "startDatetime": "2014-02-04T14:45:00Z",
      "endDatetime": "2014-02-04T15:00:00Z",
      "duration": 15,
      "isPartialRestoration": false,
      "isReportable": true,
      "descriptiveCharacteristics": "Distribution Overhead",
      "voltage": "6900",
      "circuitType": "Radial",
      "phasesImpacted": "1 (A)",
      "loadInterrupted": 100,
      "totalCustomers": 30000,
      "reportedBy": "Customer call-in",
      "totalWorkHoursForRestoration": 10
    },
    "relationships": {
      "user": {
        "data": {
          "type": "User",
          "id": "5"
        }
      },
      "event": {
        "data": {
          "type": "Event",
          "id": "83238"
        }
      },
      "cause": {
        "data": {
          "type": "Cause",
          "id": "3"
        }
      },
      "equipmentDetails": {
        "meta": {
          "count": 1
        },
        "data": [
          {
            "type": "EquipmentDetail",
            "id": "1069554"
          }
        ]
      },
      "substation": {
        "data": {
          "type": "Substation",
          "id": "63"
        }
      },
      "circuit": {
        "data": {
          "type": "Circuit",
          "id": "236"
        }
      },
      "customersImpacted": {
        "meta": {
          "count": 0
        },
        "data": []
      }
    }
  }
}

Status Codes

200 OK – Successful response
401 Unauthorized – You did not provide a valid Authorization: Bearer token.
403 Forbidden – Your user role is not authorized to access this endpoint.

Update an Outage ¶

A user must have at least “member” authorization to update Outages for their Utility.

PATCH https://reliability.api.publicpower.org/v1/outages/(int: outage_id)/¶

Example request:

Please note that you can PATCH any attribute or relationship listed in the resource details.

PATCH /v1/outages/264935/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken

{
  "data": {
    "attributes": {
      "address": "Updated location"
    },
    "type": "Outage",
    "id": "264935"
  }
}

Request Headers

Authorization – Required OAuth token to authenticate. See Authentication docs.
Content-Type – Content-Type: application/vnd.api+json - JSON API IANA media type

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "Outage",
    "id": "264935",
    "attributes": {
      "address": "Updated location",
      "totalCustomersImpacted": 1,
      "startDatetime": "2014-02-04T14:45:00Z",
      "endDatetime": "2014-02-04T15:00:00Z",
      "duration": 15,
      "isPartialRestoration": false,
      "isReportable": true,
      "descriptiveCharacteristics": "Distribution Overhead",
      "voltage": "6900",
      "circuitType": "Radial",
      "phasesImpacted": "1 (A)",
      "loadInterrupted": 100,
      "totalCustomers": 30000,
      "reportedBy": "Customer call-in",
      "totalWorkHoursForRestoration": 10
    },
    "relationships": {
      "user": {
        "data": {
          "type": "User",
          "id": "5"
        }
      },
      "event": {
        "data": {
          "type": "Event",
          "id": "83238"
        }
      },
      "cause": {
        "data": {
          "type": "Cause",
          "id": "3"
        }
      },
      "substation": {
        "data": {
          "type": "Substation",
          "id": "63"
        }
      },
      "circuit": {
        "data": {
          "type": "Circuit",
          "id": "236"
        }
      },
      "customersImpacted": {
        "meta": {
          "count": 0
        },
        "data": []
      }
    }
  }
}

Status Codes

200 OK – Outage updated
400 Bad Request – The PATCHed data was malformed.
401 Unauthorized – You did not provide a valid Authorization: Bearer token.
403 Forbidden – Your user role is not authorized to access this endpoint.

Delete an Outage ¶

A user must have at least “member” authorization to delete Outages for their Utility.

DELETE https://reliability.api.publicpower.org/v1/outages/(int: outage_id)/¶

Example request:

DELETE /v1/outages/264935/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken

Request Headers

Authorization – Required OAuth token to authenticate. See Authentication docs.
Content-Type – Content-Type: application/vnd.api+json - JSON API IANA media type

Example response:

HTTP/1.1 204 No Content
Content-Type: application/vnd.api+json

Status Codes

204 No Content – Outage deleted
400 Bad Request – You do not have access to delete this Outage.
401 Unauthorized – You did not provide a valid Authorization: Bearer token.
403 Forbidden – Your user role is not authorized to access this endpoint.