TECO Energy Outages API

openapi: 3.0.3
info:
  title: Tampa Electric Account Accounts Outages API
  description: The Tampa Electric Account API provides programmatic access to customer account management capabilities including billing, energy usage history, payment processing, service requests, and energy efficiency programs. Used by residential and commercial customers and authorized third-party applications through the Tampa Electric developer portal.
  version: 1.0.0
  contact:
    url: https://developer.tecoenergy.com/
  license:
    name: Proprietary
    url: https://www.tecoenergy.com/
servers:
- url: https://api.tecoenergy.com/v1
  description: Tampa Electric API - Production
tags:
- name: Outages
paths:
  /outages:
    get:
      operationId: listOutages
      summary: List Active Outages
      description: Retrieve a list of current active outages within the Tampa Electric service territory.
      tags:
      - Outages
      parameters:
      - name: county
        in: query
        description: Filter outages by Florida county name.
        required: false
        schema:
          type: string
      - name: zipCode
        in: query
        description: Filter outages by ZIP code.
        required: false
        schema:
          type: string
      - name: status
        in: query
        description: Filter by outage status.
        required: false
        schema:
          type: string
          enum:
          - active
          - restored
          - assessing
      - name: page
        in: query
        description: Page number for pagination.
        required: false
        schema:
          type: integer
          default: 1
      - name: pageSize
        in: query
        description: Number of results per page.
        required: false
        schema:
          type: integer
          default: 25
          maximum: 100
      security:
      - bearerAuth: []
      responses:
        '200':
          description: A list of active outages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalOutages:
                    type: integer
                    description: Total number of active outages.
                  customersAffected:
                    type: integer
                    description: Total customers currently affected by outages.
                  outages:
                    type: array
                    items:
                      $ref: '#/components/schemas/Outage'
        '401':
          description: Unauthorized - invalid or missing token.
        '429':
          description: Too many requests.
  /outages/{outageId}:
    get:
      operationId: getOutage
      summary: Get Outage Details
      description: Retrieve detailed information about a specific outage by its ID.
      tags:
      - Outages
      parameters:
      - name: outageId
        in: path
        description: Unique identifier for the outage event.
        required: true
        schema:
          type: string
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Detailed outage information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Outage'
        '404':
          description: Outage not found.
  /outages/report:
    post:
      operationId: reportOutage
      summary: Report Power Outage
      description: Submit a power outage report for a specific service address.
      tags:
      - Outages
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutageReport'
      responses:
        '201':
          description: Outage report submitted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  confirmationNumber:
                    type: string
                    description: Confirmation number for the outage report.
                  message:
                    type: string
                    description: Status message.
                  estimatedRestorationTime:
                    type: string
                    format: date-time
                    description: Estimated time of power restoration.
        '400':
          description: Invalid request data.
        '401':
          description: Unauthorized.
  /outages/map:
    get:
      operationId: getOutageMap
      summary: Get Outage Map Data
      description: Retrieve geographic outage data suitable for rendering on a map.
      tags:
      - Outages
      parameters:
      - name: bounds
        in: query
        description: Geographic bounding box (minLat,minLng,maxLat,maxLng).
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Outage map data with geographic coordinates.
          content:
            application/json:
              schema:
                type: object
                properties:
                  outageAreas:
                    type: array
                    items:
                      type: object
                      properties:
                        latitude:
                          type: number
                          format: double
                        longitude:
                          type: number
                          format: double
                        radius:
                          type: number
                          description: Approximate radius of affected area in miles.
                        customersAffected:
                          type: integer
                        status:
                          type: string
components:
  schemas:
    OutageReport:
      type: object
      description: An outage report submitted by a customer.
      required:
      - serviceAddress
      - accountNumber
      properties:
        accountNumber:
          type: string
          description: Customer account number.
        serviceAddress:
          type: object
          description: Service address experiencing the outage.
          required:
          - streetAddress
          - zipCode
          properties:
            streetAddress:
              type: string
            city:
              type: string
            state:
              type: string
              default: FL
            zipCode:
              type: string
        contactPhone:
          type: string
          description: Customer contact phone number for follow-up.
        hazardObserved:
          type: boolean
          description: Whether a hazardous condition (downed line, sparking) was observed.
        hazardDescription:
          type: string
          description: Description of any observed hazard.
    Outage:
      type: object
      description: A power outage event in the Tampa Electric service territory.
      properties:
        outageId:
          type: string
          description: Unique identifier for the outage.
        status:
          type: string
          description: Current status of the outage.
          enum:
          - active
          - restored
          - assessing
        cause:
          type: string
          description: Reported or assessed cause of the outage.
          enum:
          - weather
          - equipment
          - animal
          - vegetation
          - vehicle
          - unknown
        customersAffected:
          type: integer
          description: Number of customers currently affected.
        affectedArea:
          type: object
          description: Geographic description of the outage area.
          properties:
            zipCodes:
              type: array
              items:
                type: string
            county:
              type: string
            city:
              type: string
        outageStartTime:
          type: string
          format: date-time
          description: When the outage was first reported or detected.
        estimatedRestorationTime:
          type: string
          format: date-time
          description: Estimated time of power restoration. Null if unknown.
        actualRestorationTime:
          type: string
          format: date-time
          description: Actual time of restoration. Null if still active.
        lastUpdated:
          type: string
          format: date-time
          description: Timestamp of the most recent status update.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT