API Overview

Overview

Welcome to the GreenGrid Energy API. This powerful set of endpoints enables you to seamlessly integrate smart energy data into your apps, dashboards, and systems. Whether you’re optimizing household efficiency or managing utility-scale insights, our API helps you make informed, sustainable choices in real time.

What you can do with the API

• Access real-time and historical energy consumption data
• Automate alerts for unusual usage patterns
• Sync with third-party smart home platforms
• Customize energy dashboards for homeowners and partners
• Retrieve performance metrics for solar, battery, and grid interactions

Who it’s for

This API is designed for:

• Developers building smart energy applications
• Utilities needing scalable, real-time grid data
• Device manufacturers integrating with GreenGrid hardware
• Energy consultants providing personalized efficiency advice

Getting started

To begin using the GreenGrid API:

1. Sign in to your developer account at developers.greengrid.io.
2. Create a new project and generate your API keys.
3. Review the authentication guide and rate limits.
4. Explore our interactive documentation and test endpoints directly in your browser.

Key features

RESTful structure

Standard HTTP methods (GET, POST, PUT, DELETE) make integration simple and predictable.

Scalable data access

Our endpoints support millions of requests daily, with secure, low-latency delivery.

Built-in filtering

Query parameters allow granular access to device-level data, time ranges, and user IDs.

Error transparency

All responses include clear error codes and remediation guidance to keep your system running smoothly.

Example endpoints

Support and feedback

If you run into issues or have feature suggestions, visit our Help Center or reach out through our developer forum. We’re here to help you build a greener, smarter energy future.

Next steps

Explore the Authentication Guide or jump straight into the API Reference.

Ready to power up your integration? Let’s get started.

Authentication Guide

To keep your data safe and access secure, all GreenGrid API requests must be authenticated. This guide walks you through how to get started.

Why Authentication Matters

Authentication ensures that only authorized users can access data and perform actions. It protects customer privacy and prevents misuse of energy insights.

API Key Basics

You need a GreenGrid API key to make authenticated requests.

Get Your API Key

1. Log in to your GreenGrid Developer Dashboard.
2. Go to API Keys.
3. Click Create New Key.
4. Copy and store your key securely. You won’t be able to view it again.

Tip: Treat your API key like a password. Don’t share it or commit it to public code.

Making Authenticated Requests

All authenticated requests must include your API key in the Authorization header.

Example Header

GET /v1/energy-insights HTTP/1.1
Host: api.greengrid.com
Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your actual key.

Token Expiry & Rotation

While API keys do not expire by default, we recommend rotating keys every 90 days for best security practices.

Rotate Your API Key

1. Log in to the Developer Dashboard.
2. Revoke the old key.
3. Generate a new key.
4. Update your systems immediately.

Error Handling

Here are common authentication errors and how to resolve them:

Keep It Secure

• Use HTTPS for every request.
• Store keys in server-side environment variables.
• Never expose keys in client-side code.

Need help? Contact Support or view the API Reference.

Changelog

Overview

The changelog keeps you informed about updates to the GreenGrid API, SDKs, and documentation. Each entry includes version details, release date, highlights, and technical changes.

v1.6.0 – 2025-06-01

Highlights:

• New webhook event: device.connected
• SDK updates for Python and JavaScript
• Energy insights endpoint now supports group_by=hour

Technical Changes:

• Added support for hourly aggregation in /energy-insights
• Improved error handling for invalid date formats
• Enhanced retry logic for webhook delivery failures

v1.5.2 – 2025-05-10

Highlights:

• Performance improvements for device listings
• Minor SDK bug fixes

Technical Changes:

• Reduced response time for /devices
• Fixed a caching issue in greengrid-sdk-js

v1.5.0 – 2025-04-15

Highlights:

• New endpoint: /alerts
• Notification delivery via email and webhook

Technical Changes:

• Introduced alert creation and management
• Added delivery method parameter (email, sms, webhook)

v1.4.0 – 2025-03-01

Highlights:

• Major API documentation refresh
• Authentication guide updated with rotation best practices

Technical Changes:

• Standardized error response structure across all endpoints
• Deprecated support for XML payloads (JSON only moving forward)

Looking for historical changes or archived versions? Contact Support for access to the full version history.

Data Models

Understanding the structure of data returned by the GreenGrid API helps you build faster and more reliable integrations. This guide outlines key objects, their attributes, and how they relate.

Common Objects

User

Represents a GreenGrid account holder.

{
  "user_id": "b43d-82ff",
  "email": "user@example.com",
  "created_at": "2024-09-12T17:03:00Z",
  "role": "homeowner"
}

• user_id: Unique identifier for the user
• email: User’s registered email address
• created_at: ISO timestamp of account creation
• role: User role (homeowner, utility, admin)

Device

Represents a smart device connected to GreenGrid.

{
  "device_id": "d901-22ac",
  "type": "smart_meter",
  "location": "Main Panel",
  "status": "active"
}

• device_id: Unique ID of the device
• type: Device type (e.g., smart_meter, thermostat)
• location: Physical installation point
• status: Current state (active, inactive, faulty)

EnergyInsight

Captures time-based energy usage.

{
  "user_id": "b43d-82ff",
  "date": "2025-05-31",
  "kwh_used": 13.2,
  "peak_hour": "18:00"
}

• date: The calendar date of measurement
• kwh_used: Total kilowatt-hours consumed
• peak_hour: Hour of highest usage

Relationships

• A user can have multiple devices.
• Each device reports insights daily.
• EnergyInsight data is tied to both user and device IDs.

Best Practices

• Use IDs rather than emails to reference users.
• Cache frequent lookups to reduce API calls.
• When storing data, normalize models to improve performance.

Want to explore live data? Use the API Reference or query insights using sample requests in Postman.

Endpoints Alerts And Notifications

Overview

These endpoints allow you to manage EnergyPulse alerts and configure how users are notified about significant energy usage events. Use them to enable real-time push notifications, SMS, or webhook triggers.

Base URL

https://api.greengrid.com/v1/alerts

Supported Methods

GET /alerts

Retrieve all alerts configured for a specific user.

Request

GET /v1/alerts?user_id=b43d-82ff
Authorization: Bearer YOUR_API_KEY

Sample Response

[
  {
    "alert_id": "alr-001",
    "type": "peak_usage",
    "threshold_kwh": 15,
    "delivery": "sms"
  }
]

POST /alerts

Create a new usage alert.

Request Body

{
  "user_id": "b43d-82ff",
  "type": "peak_usage",
  "threshold_kwh": 20,
  "delivery": "webhook"
}

Sample Response

{
  "alert_id": "alr-002",
  "status": "active"
}

PATCH /alerts/{alert_id}

Modify an existing alert’s parameters.

{
  "threshold_kwh": 18,
  "delivery": "email"
}

DELETE /alerts/{alert_id}

Delete a user alert.

{
  "message": "Alert removed successfully"
}

Webhook Configuration

For alerts delivered via webhook:

• Use POST endpoint: /v1/webhooks
• Provide a valid HTTPS callback URL
• GreenGrid retries failed calls with exponential backoff

Need to audit notification logs or test alert triggers? Visit the Notification History Page.

Endpoints for Energy Insights

Overview

The Energy Insights endpoints allow you to retrieve electricity usage data, compare consumption trends, and monitor peak usage times. These endpoints are ideal for dashboards, billing summaries, and sustainability reporting.

Base URL

https://api.greengrid.com/v1/energy-insights

Supported Methods

GET /energy-insights

Retrieves daily or monthly usage data for a user.

Request

GET /v1/energy-insights?start=2025-05-01&end=2025-05-31
Authorization: Bearer YOUR_API_KEY

Query Parameters

• start: Start date in YYYY-MM-DD format (required)
• end: End date in YYYY-MM-DD format (required)
• group_by: day (default) or month

Sample Response

{
  "user_id": "b43d-82ff",
  "data": [
    {
      "date": "2025-05-01",
      "kwh_used": 12.4,
      "peak_hour": "19:00"
    },
    {
      "date": "2025-05-02",
      "kwh_used": 10.7,
      "peak_hour": "20:00"
    }
  ]
}

POST /energy-insights

Used for advanced filtering or user-specific summaries.

Request Body

{
  "user_id": "b43d-82ff",
  "interval": "month",
  "metrics": ["kwh_used", "peak_hour"]
}

Sample Response

{
  "summary": {
    "total_kwh": 420.5,
    "avg_daily_kwh": 13.6,
    "peak_usage_time": "18:00"
  }
}

Use Cases

• Display usage graphs by day or month
• Detect peak demand periods
• Automate usage-based alerts

Need deeper visibility or want to segment by device? See Device Management Endpoints.

Endpoints User Management

Overview

User management endpoints let you create, update, delete, and retrieve users in your GreenGrid-integrated application. These endpoints are essential for identity mapping, role-based access, and onboarding automation.

Base URL

https://api.greengrid.com/v1/users

Supported Methods

GET /users/{user_id}

Retrieve profile information for a specific user.

Sample Request

GET /v1/users/b43d-82ff
Authorization: Bearer YOUR_API_KEY

Sample Response

{
  "user_id": "b43d-82ff",
  "email": "user@example.com",
  "role": "homeowner",
  "created_at": "2024-09-12T17:03:00Z"
}

POST /users

Create a new GreenGrid user.

Request Body

{
  "email": "newuser@example.com",
  "role": "homeowner"
}

Sample Response

{
  "user_id": "u122-93ca",
  "status": "created"
}

PATCH /users/{user_id}

Update user attributes like role or contact information.

{
  "role": "utility"
}

DELETE /users/{user_id}

Remove a user account and associated data.

{
  "message": "User deleted successfully"
}

Best Practices

• Validate email formats on creation.
• Use roles (homeowner, utility, admin) to define access scope.
• Use soft deletion for auditability in enterprise applications.

For access management or account recovery, see Authentication Guide.

Error codes and responses

GreenGrid API uses standard HTTP status codes to indicate the success or failure of your requests. This page will help you understand common error responses and how to fix them.

Response Format

All errors follow a consistent JSON structure:

{
  "error": "Description of the issue",
  "status": 4XX
}

Common HTTP Status Codes

Example: Invalid Token

Request

GET /v1/user-profile HTTP/1.1
Authorization: Bearer INVALID_TOKEN

Response

{
  "error": "Unauthorized",
  "status": 401
}

Debugging Tips

• Use tools like Postman to inspect headers and responses.
• Double-check token and payload formatting.
• Refer to the Authentication Guide for correct usage.
• If the problem persists, log the full request/response for analysis.

Need help with an error you’re seeing? Reach out to Support with your request ID and timestamp.

FAQ And Troubleshooting

Overview

This section addresses the most frequently asked questions about using the GreenGrid API and provides troubleshooting tips to help you solve common issues quickly.

Frequently Asked Questions

What happens if I lose my API key?

Log in to your Developer Dashboard, revoke the old key, and generate a new one. Remember to update your integrations with the new key immediately.

Can I use the API for commercial applications?

Yes. The API is designed for both personal and commercial projects. For high-volume or enterprise use, contact us for enhanced rate limits and support.

Is there a sandbox environment?

Yes. All developer accounts include access to a sandbox mode. Use the base URL https://sandbox-api.greengrid.com for testing without affecting live data.

What is the data retention policy?

Usage and device data are retained for a minimum of 12 months. You can request data exports or deletions in compliance with privacy regulations.

Troubleshooting Tips

401 Unauthorized

• Ensure your API key is included in the Authorization header.
• Double-check that the key hasn’t been revoked or expired.

403 Forbidden

• You may be trying to access a restricted endpoint.
• Check your role and permissions.

404 Not Found

• Confirm the endpoint path and resource ID are correct.
• Some endpoints require query parameters.

429 Too Many Requests

• You’ve hit your rate limit.
• Wait and retry using exponential backoff.

500 Internal Server Error

• The issue is on GreenGrid’s side.
• Retry after a short delay or contact support if it persists.

Get Help

Still stuck? Try the following:

• Visit the Help Center
• Ask a question in our Developer Community
• File a support ticket with your request ID and timestamp

For release-specific issues, refer to the Changelog to check for recent updates.

Getting started

Welcome to the GreenGrid API. This guide will help you set up your development environment, make your first request, and understand how to explore the API.

Who This Is For

Whether you’re building an energy dashboard, integrating smart devices, or optimizing usage patterns, this guide is for:

• Developers new to GreenGrid
• Tech teams at utilities and energy startups
• Engineers exploring clean energy integrations

Prerequisites

Before you begin, make sure you have:

• A GreenGrid developer account (Sign up here)
• An active API key
• Basic knowledge of HTTP and JSON
• A tool to make requests, like curl, Postman, or a REST client

Set Up Your Environment

We recommend testing requests in a secure, local development environment.

Example using curl (macOS, Linux)

curl -X GET https://api.greengrid.com/v1/energy-insights \
  -H "Authorization: Bearer YOUR_API_KEY"

Replace YOUR_API_KEY with your actual API key.

First API Call

Let’s retrieve energy usage data.

Endpoint

GET /v1/energy-insights

Sample Response

{
  "user_id": "b43d-82ff",
  "date_range": {
    "start": "2025-05-01",
    "end": "2025-05-31"
  },
  "kwh_used": 420.5,
  "peak_usage_time": "17:00"
}

Note: All responses are in UTC unless specified otherwise.

Explore the API

Once you’ve verified your first request, explore these next steps:

• Read the Authentication Guide
• Review available Endpoints
• Check Rate Limits

Troubleshooting Tips

• If you receive a 401 error, check that your API key is included and formatted correctly.
• If you get a timeout, verify your internet connection and endpoint URL.
• Always use HTTPS. HTTP requests will be rejected.

Still stuck? Visit the Help Center or reach out to our support team.

Rate limits and quotas

To ensure consistent performance for all users, GreenGrid enforces rate limits on API usage. This guide explains how rate limits work, what quotas apply, and how to avoid common issues.

Why Rate Limits Matter

Rate limiting prevents abuse, protects infrastructure, and ensures fair access across the platform. It also encourages efficient API design by discouraging excessive polling or redundant requests.

Standard Limits

GreenGrid applies different limits depending on the API tier associated with your account.

Note: These values are subject to change. Always refer to your Developer Dashboard for real-time usage.

How Throttling Works

If you exceed your rate limit:

• The request will return a 429 Too Many Requests status.
• A Retry-After header may be included to suggest when to try again.
• Continued abuse may lead to temporary suspension.

Sample 429 Response

{
  "error": "Rate limit exceeded",
  "status": 429,
  "retry_after": 30
}

Best Practices to Avoid Throttling

• Use caching for frequently accessed data.
• Batch requests when possible.
• Implement exponential backoff when retrying failed calls.
• Monitor your usage via the Developer Dashboard.

Monitoring Your Quota

You can track your API usage in real-time.

1. Log in to your Developer Dashboard.
2. Navigate to Usage & Quotas.
3. Set up alerts to warn when you’re nearing limits.

Need higher limits or planning a high-volume integration? Contact our sales team to learn about Enterprise plans.

SDKs And Libraries

Overview

GreenGrid offers SDKs and client libraries to help you integrate faster and reduce boilerplate code. These libraries wrap standard API calls and include built-in error handling, authentication helpers, and response parsing.

Available SDKs

Example: JavaScript

Setup

import { GreenGridClient } from 'greengrid-sdk-js';

const client = new GreenGridClient({ apiKey: 'YOUR_API_KEY' });

Fetch Insights

const insights = await client.getEnergyInsights({
  start: '2025-05-01',
  end: '2025-05-31'
});

console.log(insights);

Example: Python

Setup

from greengrid_sdk import GreenGridClient

client = GreenGridClient(api_key='YOUR_API_KEY')

Fetch Insights

data = client.get_energy_insights(start='2025-05-01', end='2025-05-31')
print(data)

Authentication

All SDKs use the same token-based system. Pass your API key securely during client initialization.

Tip: Never hard-code API keys in your source code. Use environment variables or a secrets manager.

Community and Contributions

We welcome contributions. Visit our GitHub organization for source code, issue tracking, and contribution guidelines.

Looking for integration guides? See our Getting Started section or explore Example Projects.

Versioning And Deprecation Policy

Overview

GreenGrid uses a clear and predictable versioning policy to help you manage API changes with confidence. This page explains how versions are released, how long they are supported, and what to expect during deprecation.

Version Format

We use semantic versioning: v{major}.{minor}.{patch}

• Major: Breaking changes (e.g., v2.0)
• Minor: Backward-compatible feature updates (e.g., v1.2)
• Patch: Backward-compatible bug fixes (e.g., v1.2.1)

The base API URL includes the major version only:

https://api.greengrid.com/v1/

Release Schedule

• Minor and patch updates: Released monthly as needed
• Major updates: Released no more than twice per year
• All new features target the latest major version

Deprecation Policy

When an API version is deprecated:

1. A minimum 6-month notice is provided.
2. Deprecated versions remain accessible during the grace period.
3. Breaking changes are communicated via:
   • Email alerts
   • Developer Dashboard notifications
   • Changelog updates

Migration Support

We provide migration guides and backwards compatibility flags for most transitions. SDKs and API clients are updated within 2 weeks of each major release.

Tip: Subscribe to our Developer Newsletter for early access to beta features.

Need help upgrading? Our support team can assist with migration planning or validation.

Webhooks And Event Subscriptions

Overview

Webhooks let your application receive real-time data from GreenGrid when specific events occur. This is useful for syncing usage data, triggering alerts, or logging activity as it happens.

Base URL

https://api.greengrid.com/v1/webhooks

Supported Methods

Available Events

POST /webhooks

Register a webhook to subscribe to one or more events.

Request Body

{
  "event": "usage.updated",
  "url": "https://yourapp.com/hooks/greengrid",
  "auth_token": "secure-token-abc123"
}

Sample Response

{
  "webhook_id": "whk-998ac",
  "status": "active"
}

GET /webhooks

Retrieve a list of active webhook subscriptions.

[
  {
    "webhook_id": "whk-998ac",
    "event": "usage.updated",
    "url": "https://yourapp.com/hooks/greengrid"
  }
]

DELETE /webhooks/{webhook_id}

Unsubscribe from a webhook.

{
  "message": "Webhook removed"
}

Retry Behavior

• GreenGrid retries failed deliveries up to 5 times using exponential backoff.
• If a webhook consistently fails, it will be paused.
• Ensure your endpoint responds with HTTP 2xx status within 5 seconds.

Need more control or analytics on delivery? Check Notification History.