> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wattshift.com/llms.txt
> Use this file to discover all available pages before exploring further.

# list utilities



## OpenAPI

````yaml /api-reference/openapi.json post /v1/utility/get
openapi: 3.0.0
info:
  title: WattShift API
  description: An API for the WattShift Service (https://wattshift.com/partners)
  version: '1.0'
  contact: {}
servers: []
security: []
tags: []
paths:
  /v1/utility/get:
    post:
      tags:
        - utility
      summary: list utilities
      operationId: getUtility
      parameters:
        - name: x-ws-api-key
          in: header
          description: WattShift API Key
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UtilityRequestDTO'
            example:
              zipcode: '94107'
              detailLevel: minimal
      responses:
        '400':
          description: Validation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelopeDto'
              example:
                request_id: req_123
                error_code: VALIDATION_FAILED
                message: Request validation failed.
                field_errors:
                  - field: zipcode
                    message: zipcode is invalid
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorEnvelopeDto'
              example:
                request_id: req_123
                error_code: AUTH_MISSING_API_KEY
                message: Missing x-ws-api-key header.
                recovery_action: >-
                  Provide the x-ws-api-key header. If this contradicts the
                  public docs or OpenAPI contract, submit structured feedback
                  through /v1/feedback.
        default:
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UtilityResponseExternalDto'
              example:
                - utilityId: '14328'
                  utilityName: Pacific Gas & Electric
                  iconUrl: https://example.com/utilities/pge.png
                  ratePlans:
                    - id: 6915de25881cbc6041e4c7f1
                      rateID: tou-d-pr-1
                      udId: tou-d-pr-1
                      ratePlanName: TOU-D
                      supportedType: optimizable
      security:
        - x-ws-api-key: []
        - x-ws-api-key: []
components:
  schemas:
    UtilityRequestDTO:
      type: object
      properties:
        pageSize:
          oneOf:
            - type: number
            - type: string
        pageNumber:
          oneOf:
            - type: number
            - type: string
        zipcode:
          description: zipcode for utility
          type: string
          pattern: ^(?:0{0,4}[0-9]{1,5}|[0-9]{3})(?:[-\s][0-9]{4})?$
        lat:
          description: latitude for utility rates
          type: string
        long:
          description: longitude for utility rates
          type: string
        radius:
          description: radius within which utility rates are requested
          oneOf:
            - type: number
            - type: string
          nullable: true
          default: null
        utilityId:
          description: source id of the utility
          type: string
        effectiveOnDate:
          description: timestamp, seconds since 1970-01-01T00:00:00, UTC
          oneOf:
            - type: number
            - type: string
        isSolarPrioritizedOrder:
          type: boolean
        detailLevel:
          type: string
          enum:
            - full
            - minimal
          x-enumNames:
            - FULL
            - MINIMAL
    ApiErrorEnvelopeDto:
      type: object
      properties:
        request_id:
          type: string
          example: req_123
        error_code:
          type: string
          enum:
            - AUTH_MISSING_API_KEY
            - AUTH_INVALID_API_KEY
            - AUTH_EXPIRED_CREDENTIAL
            - AUTH_REVOKED_CREDENTIAL
            - AUTH_INSUFFICIENT_SCOPE
            - VALIDATION_FAILED
            - RATE_LIMITED
            - NOT_FOUND
            - FORBIDDEN
            - PRODUCTION_ACCESS_DENIED
            - INTERNAL_ERROR
          example: VALIDATION_FAILED
        message:
          type: string
          example: Request validation failed.
        recovery_action:
          type: string
          example: >-
            Provide the x-ws-api-key header. If this contradicts the public
            docs, submit feedback through /v1/feedback.
        field_errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiFieldErrorDto'
        retry_after_seconds:
          type: number
          example: 3600
      required:
        - request_id
        - error_code
        - message
    UtilityResponseExternalDto:
      type: object
      properties:
        utilityId:
          type: string
        utilityName:
          type: string
        iconUrl:
          type: string
          format: uri
        ratePlans:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              rateID:
                description: Semantic rate identifier for the normalized tariff
                type: string
              udId:
                type: string
              ratePlanName:
                type: string
              supportedType:
                type: string
                enum:
                  - optimizable
                  - unoptimizable
                  - unsupported
                  - unknown
                x-enumNames:
                  - optimizable
                  - unoptimizable
                  - unsupported
                  - unknown
              solarBillingProgram:
                type: string
                enum:
                  - none
                  - nem1
                  - nem2
                  - nem3
                  - nbt
                  - muni_export
              exportCompensationRefs:
                type: array
                items:
                  type: object
                  properties:
                    dataset:
                      type: string
                      enum:
                        - retail_net_metering
                        - ca_nbt_export_compensation
                    resolver:
                      type: string
                      enum:
                        - wattshift-api/export-compensation/v1
                    mode:
                      type: string
                      enum:
                        - retail_import_parity
                        - avoided_cost_hourly
                    status:
                      type: string
                      enum:
                        - ready
                        - partial
                        - missing
                        - unverified
                        - policy_only
                        - manual_review
                        - not_required
                    profileId:
                      type: string
                    profileVersion:
                      type: string
                    profileIds:
                      type: array
                      items:
                        type: string
                    profileVersions:
                      type: array
                      items:
                        type: string
                    baseUtility:
                      type: string
                      enum:
                        - PGE
                        - SCE
                        - SDGE
                    vintage:
                      type: string
                    customerClass:
                      type: string
                      enum:
                        - residential
                    sourceCoverage:
                      type: string
                    warnings:
                      type: array
                      items:
                        type: string
                  required:
                    - dataset
                    - resolver
                    - mode
                    - status
            required:
              - id
              - rateID
              - udId
              - ratePlanName
      required:
        - utilityId
        - utilityName
        - iconUrl
        - ratePlans
    ApiFieldErrorDto:
      type: object
      properties:
        field:
          type: string
          example: zipcode
        message:
          type: string
          example: zipcode is invalid
      required:
        - message
  securitySchemes:
    x-ws-api-key:
      type: apiKey
      in: header
      name: x-ws-api-key
      description: WattShift API key

````