Skip to main content
POST
list utilities
Pass utilityId (EIA utility ID) when you already know the utility; use zipcode (or lat/long) to discover utilities for a location. The response utilityId is that same EIA ID. It is not a rate plan id — send ratePlans[].id as ratePlanId, ratePlans[].udId repeats that WattShift plan ID, and ratePlans[].rateID is the semantic tariff reference.

Lookup by utility EIA ID

When you already know the utility’s EIA ID (for example, 14328 for PG&E), request rate plans directly:

Authorizations

x-ws-api-key
string
header
required

WattShift API key

Headers

x-ws-api-key
string

WattShift API Key

Body

application/json
zipcode
string
required

zipcode for utility

Pattern: ^(?:0{0,4}[0-9]{1,5}|[0-9]{3})(?:[-\s][0-9]{4})?$
pageSize
pageNumber
lat
string

latitude for utility rates

long
string

longitude for utility rates

radius

radius within which utility rates are requested

utilityId
string

EIA utility ID (alternative to zipcode). Pass when you already know the utility; use zipcode or lat/long to discover utilities for a location. Not a rate plan id or rateID.

effectiveOnDate

timestamp, seconds since 1970-01-01T00:00:00, UTC

isSolarPrioritizedOrder
boolean
detailLevel
enum<string>
Available options:
full,
minimal

Response

Validation failure

request_id
string
required
Example:

"req_123"

error_code
enum<string>
required
Available options:
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
string
required
Example:

"Request validation failed."

recovery_action
string
Example:

"Provide the x-ws-api-key header. If this contradicts the public docs, submit feedback through /v1/feedback."

field_errors
object[]
retry_after_seconds
number
Example:

3600