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 and client_secret)
  • Registered redirect URIs for your application

If you’re missing any prerequisites, please contact support@nomos.energy.

​
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:

  1. Redirecting users to our authorization endpoint
  2. Handling the callback with the authorization code
  3. Exchanging the code for access tokens

See our Authorization Code guide for detailed implementation steps.

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:

curl -X GET "https://api.nomos.energy/subscriptions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

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:

curl -X GET "https://api.nomos.energy/subscriptions/{subscription}/prices?start=2024-01-31&end=2024-01-31" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

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:

  1. Monitor token expiration (60 minutes)
  2. Use the refresh token to obtain new access tokens
  3. Update stored tokens
  4. 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.