This guide assumes you’re building a third-party HEMS integration that
requires user consent. For server-to-server integrations, see our Client
Credentials guide instead.
Prerequisites
To complete this guide, you’ll need:- Valid OAuth 2.0 credentials (
client_id
andclient_secret
) - Registered redirect URIs for your application
Overview
In this guide, we’ll walk through integrating a Home Energy Management System (HEMS) with our API. By the end, your HEMS will be able to access real-time pricing data and optimize energy consumption accordingly.1
Implement OAuth 2.0 Flow (Optional)
If you’re building a third-party application that requires user consent, you’ll need to implement the Authorization Code flow. This involves:
- Redirecting users to our authorization endpoint
- Handling the callback with the authorization code
- Exchanging the code for access tokens
Store the refresh token securely - you’ll need it to maintain long-term access to the user’s data.
2
Select Subscription
Use the List Subscriptions endpoint to retrieve the customer’s subscriptions:
Most customers will only have one subscription. Store the subscription ID for subsequent API calls.
3
Fetch Price Information
Once authorized, your HEMS can retrieve real-time and forecasted electricity prices using the Price Time Series endpoint:
The available time resolutions (15min/60min) are determined by the subscription’s plan. Check your plan details to see which resolutions are available to you.
4
Implement Price-Based Optimization
With access to real-time and forecasted prices, your HEMS can optimize energy consumption by shifting energy-intensive operations to lower-price periods. This helps reduce energy costs for your customers while maintaining comfort and functionality.
The optimization strategy will depend on your specific HEMS capabilities and customer preferences.
5
Handle Token Refresh
Implement automatic token refresh to maintain uninterrupted access:
- Monitor token expiration (60 minutes)
- Use the refresh token to obtain new access tokens
- Update stored tokens
- Handle refresh token errors appropriately
Refresh token rotation is enabled by default - always store the new refresh token returned after each refresh operation.
Final Thoughts
Congratulations! You’ve learned how to integrate a HEMS with our API for price-based energy optimization. Your system can now make intelligent decisions based on real-time electricity prices.Need help? Have suggestions? We’d love to hear from you! Contact us at
support@nomos.energy to share your feedback or
get assistance with your integration.