Circuits

Resource description

All endpoints adhere to the JSON API specification.

Attributes

Name

Description

Required?

Type

Notes

name

Display name for the Circuit

True

string

totalCustomers

Number of customers served by this Circuit

False

int

milesOfLine

Miles of line controlled by this Circuit

False

decimal

percentResidential

Percentage of Meters at this Circuit that are classified as “residential”

False

string (representing decimal)

percentCommercial

Percentage of Meters at this Circuit that are classified as “commercial”

False

string (representing decimal)

percentIndustrial

Percentage of Meters at this Circuit that are classified as “industrial”

False

string (representing decimal)

lineLengthOverhead

Miles of line served by this Circuit above ground

False

string

lineLengthUnderground

Miles of line served by this Circuit below ground

False

string

Relationships

Name

Description

Required?

Type

substation

Substation this Circuit belongs to

True

Foreign key

List Circuits

A user must have at least “spectator” authorization to list Circuits for their Utility.

GET https://reliability.api.publicpower.org/v1/circuits/

Example request:

GET /v1/circuits/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken
Request Headers
Query Parameters

  • page (int) – Page Number of results to request.

  • page_size (int) – Number of results to return per-page.

  • filter[substation__utility] (int) – Only return results for a given Utility ID.

  • filter[substation] (int) – Only return results for a given Substation ID.

  • sort (string) – Sort the results by the given Circuit attribute. Available attribute: “name”

Example response:

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

{
  "links": {
    "first": "https://reliability.api.publicpower.dev/v1/circuits/?page=1&page_size=2",
    "last": "https://reliability.api.publicpower.dev/v1/circuits/?page=3543&page_size=2",
    "next": "https://reliability.api.publicpower.dev/v1/circuits/?page=2&page_size=2",
    "prev": null
  },
  "data": [
  {
    "type": "Circuit",
    "id": "13",
    "attributes": {
      "milesOfLine": 100,
      "name": "My Circuit",
      "lineLengthOverhead": "400",
      "lineLengthUnderground": "78",
      "percentCommercial": "39.00",
      "percentIndustrial": "10.45",
      "percentResidential": "50.55",
      "totalCustomers": 200
    },
    "relationships": {
      "substation": {
        "data": {
          "type": "Substation",
          "id": "7"
        }
      }
    }
  },
  {
    "type": "Circuit",
    "id": "14",
    "attributes": {
      "milesOfLine": null,
      "name": "My Circuit 2",
      "lineLengthOverhead": null,
      "lineLengthUnderground": null,
      "percentCommercial": null,
      "percentIndustrial": null,
      "percentResidential": null,
      "totalCustomers": 257
    },
    "relationships": {
      "substation": {
        "data": {
          "type": "Substation",
          "id": "7"
        }
      }
    }
  }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pages": 3543,
      "count": 7085
    }
  }
}
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 a Circuit

A user must have “leader” authorization to create Circuits for their Utility.

POST https://reliability.api.publicpower.org/v1/circuits/

Example request:

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

{
  "data": {
    "type": "Circuit",
    "attributes": {
      "name": "New Circuit",
      "totalCustomers": 400,
      "milesOfLine": 100
    },
    "relationships": {
      "substation": {
        "data": {
          "type": "Substation",
          "id": "123"
        }
      }
    }
  }
}
Request Headers

Example response:

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

{
  "data": {
    "type": "Circuit",
    "id": "7669",
    "attributes": {
      "name": "New Circuit",
      "milesOfLine": 100,
      "lineLengthOverhead": null,
      "lineLengthUnderground": null,
      "percentCommercial": null,
      "percentIndustrial": null,
      "percentResidential": null,
      "totalCustomers": 400
    },
    "relationships": {
      "substation": {
        "data": {
          "type": "Substation",
          "id": "123"
        }
      }
    }
  }
}
Status Codes

Retrieve a Circuit

A user must have at least “spectator” authorization to retrieve Circuits for their Utility.

GET https://reliability.api.publicpower.org/v1/circuits/(int: circuit_id)/

Example request:

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

Example response:

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

{
  "data": {
    "type": "Circuit",
    "id": "7669",
    "attributes": {
      "milesOfLine": 100,
      "name": "New Circuit",
      "lineLengthOverhead": null,
      "lineLengthUnderground": null,
      "percentCommercial": "39.00",
      "percentIndustrial": "10.45",
      "percentResidential": "50.55",
      "totalCustomers": 400
    },
    "relationships": {
      "substation": {
        "data": {
          "type": "Substation",
          "id": "123"
        }
      }
    }
  }
}
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 a Circuit

A user must have “leader” authorization to update Circuits for their Utility.

PATCH https://reliability.api.publicpower.org/v1/circuits/(int: circuit_id)/

Example request:

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

{
  "data": {
    "id": 7669,
    "type": "Circuit",
    "attributes": {
      "name": "Modified Circuit",
      "totalCustomers": 450,
      "milesOfLine": 120
    }
  }
}
Request Headers

Example response:

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

{
  "data": {
    "type": "Circuit",
    "id": "7669",
    "attributes": {
      "milesOfLine": 120,
      "name": "Modified Circuit",
      "lineLengthOverhead": null,
      "lineLengthUnderground": null,
      "percentCommercial": null,
      "percentIndustrial": null,
      "percentResidential": null,
      "totalCustomers": 450
    },
    "relationships": {
      "substation": {
        "data": {
          "type": "Substation",
          "id": "123"
        }
      }
    }
  }
}
Status Codes

  • 200 OK – Circuit updated

  • 401 Unauthorized – You did not provide a valid Authorization: Bearer token.

  • 403 Forbidden – Your user role is not authorized to access this endpoint.

Delete a Circuit

A user must have “leader” authorization to delete Circuits for their Utility.

DELETE https://reliability.api.publicpower.org/v1/circuits/(int: circuit_id)/

Example request:

DELETE /v1/circuits/7669/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken
Request Headers

Example response:

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