Skip to main content

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.

Welcome to WattShift! This guide will walk you through the fastest way to get your first Price Signal using our API.

​
Prerequisites

Before you begin, make sure you have your API Key. If you haven’t obtained one yet, follow the Get API Key guide.

​
Step 1: Onboard a Home

For this quickstart, we’ll use the API Based Onboarding method to programmatically create a home. This is the fastest way to test the flow.

​
1.1 Find a Utility and Rate Plan

First, let’s find a valid utility and rate plan for a test zip code (e.g., 95313). 
curl -X POST "https://api.wattshift.com/v1/utility/get" \
     -H "x-ws-api-key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{ "zipcode": "95313" }'
Copy the returned utilityId (for example, 14328 for PG&E) and choose one of the returned entries in ratePlans. Send that plan’s ratePlans[].id value as ratePlanId in the next step. The companion ratePlans[].rateID field is the semantic normalized tariff reference. 
{
  "utilityId": "14328",
  "utilityName": "Pacific Gas & Electric",
  "ratePlans": [
    {
      "id": "6915de3f881cbc6041e4c887",
      "rateID": "<semantic_rate_id>",
      "ratePlanName": "TOU-D"
    }
  ]
}

​
1.2 Create the Home

Now, create a home using the IDs you just found. 
curl -X POST "https://api.wattshift.com/v1/homes/create" \
     -H "x-ws-api-key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "My Test Home",
           "zipcode": "95313",
           "utilityId": "14328",
           "ratePlanId": "<selected ratePlans[].id>"
         }'
Response: 
{
  "id": "ws_home_123456789"
}
Save the response id. This is the home ID, shown as homeId in the examples below.

​
Step 2: Get Price Signal

Now that you have a home with a utility and rate plan, you can immediately generate a price signal! 
curl -X POST "https://api.wattshift.com/v1/homes/<homeId>/price_signal" \
     -H "x-ws-api-key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{}'
Response: You will receive a JSON object containing the price signal data for the current day, including 15-minute interval prices. 
{
  "prices": [
    {
      "start": "2023-10-27T00:00:00Z",
      "price": 0.24
    },
    ...
  ]
}

​
Congratulations!

You’ve successfully onboarded a home and retrieved your first price signal.

​
Next Steps

  • Explore Onboarding Options: Learn about our UI Based Onboarding for a user-friendly experience.
  • Calculate Impacts: Use the Impact Calculations endpoint to estimate bill savings.
  • Automate with Webhooks: Set up Webhooks to receive price signals automatically. ₹