Tampa Electric Outage API

openapi: 3.0.3
info:
  title: Tampa Electric Outage API
  description: >-
    The Tampa Electric Outage API provides programmatic access to power outage
    reporting, outage status tracking, and restoration information for the Tampa
    Electric service territory in west central Florida. Enables customers and
    partners to report outages, retrieve outage status, and access restoration
    estimated times for affected service addresses.
  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
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:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    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.
    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.