openapi: 3.0.3
info:
  title: Xcel Energy Green Button Connect My Data ApplicationInformation ElectricPowerQualitySummary API
  summary: OAuth 2.0 authorized customer energy usage data based on the NAESB ESPI standard.
  description: 'Xcel Energy Green Button Connect My Data API based on the ESPI (Energy Services Provider Interface) standard developed by NAESB. Enables authorized third-party applications to access customer electricity and natural gas usage data captured by Xcel Energy smart meters. Resources are exposed as Atom feeds and entries containing UsagePoint, MeterReading, IntervalBlock, ReadingType, ElectricPowerUsageSummary, ElectricPowerQualitySummary, LocalTimeParameters, and customer information. Customer authorization is granted via OAuth 2.0 and follows the Green Button Connect specification used by utilities across North America.

    '
  version: 1.1.0
  contact:
    name: Xcel Energy Developer Portal
    url: https://developer-apim.aws.xcelenergy.com/
  license:
    name: Proprietary
    url: https://www.xcelenergy.com/privacy_policy
  x-generated-from: documentation
  x-last-validated: '2026-05-03'
  x-standards:
  - NAESB ESPI 1.1
  - Green Button Connect My Data
servers:
- url: https://api.xcelenergy.com/DataCustodian/espi/1_1/resource
  description: Xcel Energy Data Custodian (Production)
- url: https://developer-apim.aws.xcelenergy.com/DataCustodian/espi/1_1/resource
  description: Xcel Energy Developer Sandbox
tags:
- name: ElectricPowerQualitySummary
  description: Aggregate power-quality measurements for a UsagePoint.
paths:
  /Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerQualitySummary:
    get:
      operationId: listElectricPowerQualitySummaries
      summary: List ElectricPowerQualitySummaries for a UsagePoint
      description: 'Returns an Atom feed of ElectricPowerQualitySummary entries describing power-quality measurements for the UsagePoint.

        '
      tags:
      - ElectricPowerQualitySummary
      security:
      - accessToken: []
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      - $ref: '#/components/parameters/UsagePointId'
      responses:
        '200':
          description: Atom feed of ElectricPowerQualitySummary entries.
          content:
            application/atom+xml:
              schema:
                $ref: '#/components/schemas/ElectricPowerQualitySummaryFeed'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /Subscription/{subscriptionId}/UsagePoint/{usagePointId}/ElectricPowerQualitySummary/{powerQualitySummaryId}:
    get:
      operationId: getElectricPowerQualitySummary
      summary: Retrieve a single ElectricPowerQualitySummary
      description: Returns the ElectricPowerQualitySummary entry identified by powerQualitySummaryId.
      tags:
      - ElectricPowerQualitySummary
      security:
      - accessToken: []
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      - $ref: '#/components/parameters/UsagePointId'
      - $ref: '#/components/parameters/PowerQualitySummaryId'
      responses:
        '200':
          description: Atom entry containing the ElectricPowerQualitySummary resource.
          content:
            application/atom+xml:
              schema:
                $ref: '#/components/schemas/ElectricPowerQualitySummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    UsagePointId:
      name: usagePointId
      in: path
      required: true
      description: Identifier of a UsagePoint within a Subscription.
      schema:
        type: string
        example: '1'
    PowerQualitySummaryId:
      name: powerQualitySummaryId
      in: path
      required: true
      description: Identifier of an ElectricPowerQualitySummary resource.
      schema:
        type: string
        example: '1'
    SubscriptionId:
      name: subscriptionId
      in: path
      required: true
      description: Identifier of a Subscription created from an Authorization.
      schema:
        type: string
        example: sub-5678
  responses:
    Unauthorized:
      description: Authentication failed or the access token is invalid or expired.
    NotFound:
      description: The requested resource was not found or is not authorized for this token.
  schemas:
    AtomEntry:
      type: object
      description: Atom entry envelope used to wrap ESPI resource payloads.
      properties:
        id:
          type: string
          description: Stable URI for the entry.
        title:
          type: string
          description: Human-readable title of the entry.
        published:
          type: string
          format: date-time
          description: Time the entry was first published.
        updated:
          type: string
          format: date-time
          description: Time the entry was last updated.
        link:
          type: array
          description: Atom link relations (self, up, related).
          items:
            type: object
            properties:
              rel:
                type: string
                example: self
              href:
                type: string
                example: UsagePoint/1
        content:
          type: object
          description: ESPI XML payload content.
    AtomFeed:
      type: object
      description: Atom feed envelope used to wrap collections of ESPI resource entries.
      properties:
        id:
          type: string
        title:
          type: string
        updated:
          type: string
          format: date-time
        link:
          type: array
          items:
            type: object
            properties:
              rel:
                type: string
              href:
                type: string
        entry:
          type: array
          items:
            $ref: '#/components/schemas/AtomEntry'
    ElectricPowerQualitySummary:
      allOf:
      - $ref: '#/components/schemas/AtomEntry'
      - type: object
        description: Power-quality summary measurements for a UsagePoint.
        properties:
          flickerPlt:
            type: integer
          flickerPst:
            type: integer
          harmonicVoltage:
            type: integer
          longInterruptions:
            type: integer
          mainsVoltage:
            type: integer
          measurementProtocol:
            type: integer
          powerFrequency:
            type: integer
          rapidVoltageChanges:
            type: integer
          shortInterruptions:
            type: integer
          summaryInterval:
            type: object
            properties:
              duration:
                type: integer
              start:
                type: integer
          supplyVoltageDips:
            type: integer
          supplyVoltageImbalance:
            type: integer
          supplyVoltageVariations:
            type: integer
          tempOvervoltage:
            type: integer
    ElectricPowerQualitySummaryFeed:
      allOf:
      - $ref: '#/components/schemas/AtomFeed'
  securitySchemes:
    accessToken:
      type: oauth2
      description: Customer-scoped access token issued via the OAuth 2.0 authorization-code grant.
      flows:
        authorizationCode:
          authorizationUrl: https://api.xcelenergy.com/DataCustodian/oauth/authorize
          tokenUrl: https://api.xcelenergy.com/DataCustodian/oauth/token
          refreshUrl: https://api.xcelenergy.com/DataCustodian/oauth/token
          scopes:
            FB=4_5_15;IntervalDuration=900;BlockDuration=monthly;HistoryLength=34128000: Standard ESPI scope string for 15-minute electric usage data with 13 months of history.
    clientAccessToken:
      type: oauth2
      description: Application-scoped client access token used for management endpoints (Authorization list, Bulk, ServiceStatus).
      flows:
        clientCredentials:
          tokenUrl: https://api.xcelenergy.com/DataCustodian/oauth/token
          scopes:
            DataCustodian_Admin_Access: Administrative scope used for application-level operations.
    registrationAccessToken:
      type: http
      scheme: bearer
      bearerFormat: Registration Access Token
      description: Token issued at application registration; used to read or update ApplicationInformation.