Introduction
This documentation provides all the information needed to work with the GivEnergy APIs
GivEnergy's public API is free for both personal & commercial use. Commercial use of the free API is rate restricted. A paid Commercial option is also available with custom access rates and additional features. To find out more our enhanced commercial offering, please visit this web page.
Base URL
https://api.givenergy.cloud/v1
Authenticating requests
To authenticate requests, include an Authorization
header with the value "Bearer {YOUR_API_KEY}"
All authenticated endpoints are marked with a requires authentication badge in the documentation below. This is also explained in the Badges section of this document
You can manage your API tokens by visiting the API Tokens page
Headers
Always ensure to have the following headers set with every request. If these headers are not included the response may not return valid data
Accept: application/json
Content-Type: application/json
Badges
Badge | Description |
scopes: api:inverter:read, api:inverter:control | The API token used needs all of these scopes to be able to use this API endpoint |
account type: account (only, +) | Your account must be at exactly this type (only) or at least this type (+) to use this API endpoint |
requires authentication | You must provide a valid API token to use this API endpoint |
rate limited: limit,minutes | This endpoint has a custom rate limit of limit requests every minutes minute(s). See Rate Limiting for more information |
paginated | This endpoint returns additional pagination metadata. See Pagination for more information |
dynamically validated | This endpoint's parameters are dynamically validated. See Dynamic Validation for more information |
approved users only | This endpoint is only accessible by authorised users |
Request Parameters
Most requests require 1 or more parameters to be passed into the request to search for specific data or to refine the data that is received
This section of the documentation describes to how to enter these parameters, how they are validated and what might happen
Parameter Types
Most endpoints found in this document provide details about which URL parameters
, Query Parameters
and Body Parameters
may be passed into the request
URL Parameters
are passed directly into the URL, and are indicated by a variable name inside curly brackets. For example:
inverter/{inverter}/data-points/{date}
where an inverter serial number must replace {inverter} and an ISO8601-date must replace {date}
inverter/XXXXXXXXXX/data-points/2022-01-06
Query Parameters
are appended to the end of the URL, following a question mark (?
) and a list of ampersand (&
) delimited key=value
pairs,
where key
is the name of the parameter and value
is its value. For example:
https://api.givenergy.cloud/v1/inverter/XXXXXXXXXX/data-points/2022-01-06?page=1&pageSize=20
includes parameter page
with a value of 1
Body Parameters
are passed into the request body. Examples may be seen for each request in the 'Example request' section
Validation
Documented Validation
Most endpoints provide simple validation rules in the URL parameters
, Query Parameters
or Body Parameters
For example
URL Parameters
a-url-parameter
string optional
Denotes that the URL parameter must be a string, and that it can be optional. A list of data types can be found in the Data Types section of this document
Dynamic Validation
Some endpoints require and validate parameters differently depending on the content of other parameters.
Some endpoints may also return validation input required for a different endpoint, for example:
calling the Get Setting Presets
endpoint will return a parameters
property which is a list of parameters
that must be entered in the body of the Modify Preset
endpoint in order to properly make the request
These endpoints will be marked with a dynamically validated badge
Due to the way that these endpoints are validated and handled, their dynamic content may change at any time. Well-defined endpoint parameters and response data will never change in this way
The parameters will be a json object, where each key is the property and its corresponding value adheres to the following format:
Property | Description |
---|---|
description | The description of the parameter |
validation | An array of validation rules for this parameter |
An example of this can be seen in the code section
{
"data": [
{
"id": 0,
"name": "Eco",
"description": "This mode will dynamically charge and discharge your batteries to minimise your import from the grid",
"parameters": {
"enabled": {
"description": "Enable or disable the preset",
"validation": [
"required",
"boolean"
]
}
}
},
...
]
}
The array of validation rules will either be one the types described in Data Types or one of the following:
Name | Description |
---|---|
optional | The parameter is not required |
required | The parameter is required |
min:value | The value must be at least value |
max:value | The value must be no larger than value |
numeric | The value must be numeric (integer or decimal) |
alpha:length | The value must be a string of alphanumeric characters with length length |
between:min,max | The value must be between min and max |
date_format:format,format2,... | The value must be a string that matches one of the PHP date formats |
bitwise:bits | Value must be an empty string (for no values) or a comma-separated list of values from 1 to bits |
in:value1,value2,... | The value must be exactly one of the allowed values |
object | The value must be a valid JSON object |
property:property:rule1,rule2,... | The value of property on the value must pass all of the validation rules |
hex:length | The value must be a string of hexadecimal characters with length length |
Validation Errors
If any invalid url, query or body parameters are passed into the request and a 422 status code is returned, data will be returned with the following format:
Property | Description |
---|---|
message | A description of the validation error. Typically "The given data was invalid." |
errors | An object of key => value errors, where key is the validation property that has errors, and value is an array of failed validation messages |
{
"message": "The given data was invalid.",
"errors": {
"value": [
"The value field is required."
]
}
}
Response Codes
The GivEnergy API uses conventional HTTP response codes to indicate the success or failure of an API request. The table below contains a summary of the typical response codes:
Code | Description |
---|---|
200 | The response was successful |
201 | The response was successful and a resource was created |
400 | Valid data was given but the request has failed |
401 | No valid API Token was given |
403 | Your account is not authorised to visit this endpoint or view this resource |
404 | The request endpoint or resource could not be found |
422 | The payload has missing required parameters or invalid data was given |
429 | Rate limit quota exceeded |
500 | The request failed due to an internal server error |
502 | The request failed due to an internal server error |
503 | The API is offline for maintenance |
504 | The request took too long to process |
Response Format
Responses will always return a JSON object as long as the correct headers are set
Any successful response (status 2XX) will have its relevant data returned in the data
property on the JSON object
See the 'Example Response' section for each endpoint to see how the response might look
Paginated responses will include additional data. See Pagination for more information
Response data will be different if invalid request data is provided. See Validation for more information
Remote Control Codes
When performing read or write commands to a device, a response value will be returned
When sending a command to a single device, the response value, a message and a boolean indicating if the response was successful will also be returned
When sending a command to multiple devices at once, only the response value will be returned. The response value may be either the value sent to the device, a different value (indicating that the device modified its value, but not to the one received) or one of the below error codes:
Code | Description | Potentially Successful? |
---|---|---|
-1 | The device did not respond before the request timed out | Yes |
-2 | The device is offline | No |
-3 | The device does not exist or your account does not have access to the device | No |
-4 | There were one or more validation errors. Additional information may be available | No |
-5 | There was a server error | Yes |
-6 | There was no response from the server | Yes |
Data Types
Type | Description | Examples |
---|---|---|
ISO8601-type | Type is either date or datetime See this link for more information | date 2022-01-01 datetime 2022-01-01T12:34:56Z |
datetime | A generic datetime, formatted YYYY-MM-DD hh:mm:ss. This data type is typically used when fetching data from endpoints that operate based on the system or user's local time | 2022-01-01 06:30:00 |
type,delimited | A string of comma-separated values where type is the type of each value | 1,2,3 yes,no,maybe |
string | A simple string | Hello! |
integer | A whole number | 1 100 -5000 |
decimal,precision | A decimal number with precision number of digits after the decimal point | decimal,1 1.5 decimal,6 0.000001 decimal,0 5 |
type[] | An array of values with type type | integer[] [1, 2, 3] string[] ["yes", "no", "maybe"] |
object | A valid JSON object | { "some": "json", "data": { "that": { "can": "be nested" }, "and": [ "include", "arrays", "of", "data" ] } } |
boolean | A simple boolean. A string of "true" or "false" is invalid | 1 0 true false |
Pagination
Paginated responses are typically returned when the data being requested is part of a collection, for example retrieving a list of user accounts or hardware associated with a particular user
Paginated results always include links
and meta
properties which contain the following information
Links
The following data is returned on the links
object with the response data
Property | Description |
---|---|
first | The link to the first page of paginated results |
last | The link to the last page of paginated results |
prev | The link to the previous page of paginated results |
next | The link to the next page of paginated results |
Meta
The following data is returned on the meta
object with the response data
Property | Description |
---|---|
current_page | The currently visited page's page number |
from | The number of the first record in this page, in comparison to all records |
last_page | The number of the last page in the collection |
path | The current uri, without any additional pagination query parameters |
per_page | The number of records returned with this response |
to | The number of the last record in this page, in comparison to all records |
total | The total number of records |
{
"data": [
...
],
"links": {
"first": "https://api.givenergy.cloud/v1/inverter/XXXXXXXXXX/events?page=1",
"last": "https://api.givenergy.cloud/v1/inverter/XXXXXXXXXX/events?page=3",
"prev": null,
"next": "https://api.givenergy.cloud/v1/inverter/XXXXXXXXXX/events?page=2",
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 3,
"path": "https://api.givenergy.cloud/v1/inverter/XXXXXXXXXX/events",
"per_page": 15,
"to": 15,
"total": 35
}
}
Rate Limiting
This API is rate limited, meaning that requests will not be processed if the user exceeds a certain number of requests in a given window. The window starts when the first request is made that counts towards the rate limit and ends after the specified number of minutes has elapsed
Every request that returns a response from the API counts towards the rate limit regardless of the response code received
The default global rate limit is 300 requests per minute shared across all endpoints
If the rate limit is exceeded, a response with code 429 will be returned
Every response will include the following headers to assist with managing rate limiting:
Header | Description |
---|---|
X-RateLimit-Limit | The maximum number of requests that the user is permitted to make per minute |
X-RateLimit-Remaining | The number of requests remaining in the current rate limit window |
Certain endpoints may have a rate custom rate limit defined which is specific to that endpoint
Requests to endpoints with custom rate limits do not count towards the global rate limit
Account
Get Your Account Information
requires authentication account type: any scope: api:account:read
Retrieves your account information
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/account" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/account"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/account'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/account',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": {
"id": 2,
"name": "frank28.203",
"first_name": "Anna",
"surname": "Adams",
"role": "OWNER",
"email": "kelly44@allen.co.uk",
"address": "Flat 60\nKyle Lights",
"postcode": "SP1 1NE",
"country": "UNITED_KINGDOM",
"telephone_number": "0738 286 7656",
"timezone": "GMT",
"standard_timezone": "Europe/London"
}
}
Received response:
Request failed with error:
Get Account Information by ID
requires authentication account type: engineer+ scope: api:account:read
Retrieves the information of a specific account by its ID
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/account/1234" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/account/1234"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/account/1234'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/account/1234',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": {
"id": 3,
"name": "patel.joshua.941",
"first_name": "Amy",
"surname": "Owen",
"role": "EXTERNAL",
"email": "wright.dylan@clark.net",
"address": "84 John Lake",
"postcode": "AB22 8ZW",
"country": "UNITED_KINGDOM",
"telephone_number": "+44(0)0083 429653",
"timezone": "GMT",
"standard_timezone": "Europe/London"
}
}
Received response:
Request failed with error:
Get Account Dongles by ID
requires authentication account type: engineer+ scopes: api:inverter:list, api:account:read
Retrieves a list of dongles for an account by its ID
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/account/qkunze/devices?page=1" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/account/qkunze/devices"
);
const params = {
"page": "1",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/account/qkunze/devices'
params = {
'page': '1',
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/account/qkunze/devices',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'page' => '1',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
{
"serial_number": "49niih5fqc",
"firmware_version": null,
"type": "GPRS",
"commission_date": "1997-07-21T09:43:01Z",
"inverter": {
"serial": "FC4716A325",
"status": "NORMAL",
"last_online": "2024-04-01T22:13:11Z",
"last_updated": "2007-10-27T01:50:39Z",
"commission_date": "1990-12-29T23:49:01Z",
"info": {
"battery_type": "LITHIUM",
"battery": {
"nominal_capacity": 0,
"nominal_voltage": 0,
"depth_of_discharge": 0.8
},
"model": "Commercial EMS",
"max_charge_rate": 0
},
"warranty": {
"type": "Standard Legacy",
"expiry_date": "1995-12-29T23:49:01Z"
},
"firmware_version": {
"ARM": null,
"DSP": null
},
"connections": {
"batteries": []
},
"flags": []
}
},
{
"serial_number": "28sobz4oqi",
"firmware_version": null,
"type": "GPRS",
"commission_date": "1996-01-17T23:27:53Z",
"inverter": {
"serial": "ED8493J072",
"status": "LOST",
"last_online": "2001-06-13T16:13:36Z",
"last_updated": "1995-10-07T10:09:08Z",
"commission_date": "1982-01-13T04:36:37Z",
"info": {
"battery_type": "LITHIUM",
"battery": {
"nominal_capacity": 0,
"nominal_voltage": 0,
"depth_of_discharge": 1
},
"model": "Gateway",
"max_charge_rate": 0
},
"warranty": {
"type": "Standard Legacy",
"expiry_date": "1987-01-13T04:36:37Z"
},
"firmware_version": {
"ARM": 420,
"DSP": 426
},
"connections": {
"datalog": {
"serial_number": "28sobz4oqi",
"firmware_version": null,
"type": "GPRS",
"commission_date": "1996-01-17T23:27:53Z"
},
"batteries": []
},
"flags": []
}
}
]
}
Received response:
Request failed with error:
Get Account Information by Username
requires authentication account type: engineer+ scope: api:account:read
Retrieves the information of a specific account by its username
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/account/search/qkunze" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/account/search/qkunze"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/account/search/qkunze'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/account/search/qkunze',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": {
"id": 18,
"name": "lmartin.14",
"first_name": "Jack",
"surname": "Palmer",
"role": "VIEWER",
"email": "noah.phillips@rogers.biz",
"address": "Flat 31\nKing Lake",
"postcode": "AB11 5QE",
"country": "UNITED_KINGDOM",
"telephone_number": "(0064) 295 7686",
"timezone": "GMT",
"standard_timezone": "Europe/London"
}
}
Received response:
Request failed with error:
Get Your Account Children Information
requires authentication account type: engineer+ scope: api:account:list
Retrieves a list of accounts that your account has access to
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/account-children?page=1" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/account-children"
);
const params = {
"page": "1",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/account-children'
params = {
'page': '1',
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/account-children',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'page' => '1',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
{
"id": 19,
"name": "wright.dylan.123",
"first_name": "Paul",
"surname": "Edwards",
"role": "SUB_CONTRACTOR",
"email": "stephanie07@gmail.com",
"address": "84 Alexandra Square",
"postcode": "WS11 1ZY",
"country": "UNITED_KINGDOM",
"telephone_number": "04527298086",
"timezone": "GMT",
"standard_timezone": "Europe/London"
},
{
"id": 20,
"name": "michael37.776",
"first_name": "Archie",
"surname": "Jones",
"role": "SUB_CONTRACTOR",
"email": "jmorgan@gmail.com",
"address": "39 Grace Ferry",
"postcode": "LE4 4JR",
"country": "UNITED_KINGDOM",
"telephone_number": "0047 3552779",
"timezone": "GMT -1",
"standard_timezone": "Atlantic/Azores"
}
]
}
Received response:
Request failed with error:
Get Account Children Information by ID
requires authentication account type: company+ scopes: api:account:read, api:account:list
Retrieves a list of accounts that the specified account has access to
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/account-children/1234?page=1" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/account-children/1234"
);
const params = {
"page": "1",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/account-children/1234'
params = {
'page': '1',
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/account-children/1234',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'page' => '1',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
{
"id": 21,
"name": "rose.phoebe.616",
"first_name": "Jessica",
"surname": "King",
"role": "VIEWER",
"email": "jackson.amy@owen.com",
"address": "80 Collins Land",
"postcode": "MK9 2AD",
"country": "UNITED_KINGDOM",
"telephone_number": "+44(0)316836121",
"timezone": "GMT",
"standard_timezone": "Europe/London"
},
{
"id": 22,
"name": "molly.watson.814",
"first_name": "Isabelle",
"surname": "Williams",
"role": "OWNER",
"email": "wilkinson.zach@smith.info",
"address": "33 Sean Valley",
"postcode": "TW15 3EQ",
"country": "UNITED_KINGDOM",
"telephone_number": "0975301722",
"timezone": "GMT +6",
"standard_timezone": "Asia/Qostanay"
}
]
}
Received response:
Request failed with error:
Communication Device
Inverter Flags
When a communication device has an inverter
present, the inverter
will have a flags
property.
This is a list of strings that represent the flags that apply to that inverter.
If a flag is not present in the array, it does not apply to that inverter.
{
"serial_number": "COMMDEVICE",
...
"inverter": {
...
"flags": [
"full-power-discharge-in-eco-mode",
...
]
}
}
All currently available flags can be found in the below table:
Flag | Description |
---|---|
full-power-discharge-in-eco-mode |
When present, the inverter will discharge the battery at full power during a scheduled DC discharge irrespective of the value of the Eco mode setting. If this flag is missing, Eco mode must be disabled for the battery to discharge at full power during a scheduled DC discharge |
Get Your Communication Devices
requires authentication account type: any scope: api:inverter:list
View a collection of communication devices you have access to
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/communication-device?page=1" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/communication-device"
);
const params = {
"page": "1",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/communication-device'
params = {
'page': '1',
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/communication-device',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'page' => '1',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
{
"serial_number": "WF2345G123",
"type": "WIFI",
"commission_date": "2021-01-01T00:00:00Z",
"inverter": {
"serial": "CE2345G123",
"status": "WAITING",
"last_online": "2023-01-01T00:00:00Z",
"last_updated": "2023-01-01T00:00:00Z",
"commission_date": "2021-01-01T00:00:00Z",
"info": {
"battery_type": "LITHIUM",
"battery": {
"nominal_capacity": 110,
"nominal_voltage": 51.2
},
"model": "GIV-AC-3.0",
"max_charge_rate": 2560
},
"warranty": {
"type": "Standard",
"expiry_date": "2033-01-01T00:00:00Z"
},
"firmware_version": {
"ARM": 420,
"DSP": 426
},
"connections": {
"batteries": [
{
"module_number": 1,
"serial": "BB2345G123",
"firmware_version": "1035",
"capacity": {
"full": 110,
"design": 110
},
"cell_count": 16,
"has_usb": true,
"nominal_voltage": 51.2
}
],
"meters": [
{
"address": 1,
"serial_number": 212345678,
"manufacturer_code": "0000",
"type_code": 1500,
"hardware_version": 1000,
"software_version": 1000,
"baud_rate": 9600
}
]
},
"flags": []
}
}
]
}
Received response:
Request failed with error:
Get Communication Device Information by Serial Number
requires authentication account type: any scope: api:inverter:read
Get a communication device's information by serial number
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/communication-device/consequatur" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/communication-device/consequatur"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/communication-device/consequatur'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/communication-device/consequatur',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": {
"serial_number": "WF2345G123",
"type": "WIFI",
"commission_date": "2021-01-01T00:00:00Z",
"inverter": {
"serial": "CE2345G123",
"status": "WAITING",
"last_online": "2023-01-01T00:00:00Z",
"last_updated": "2023-01-01T00:00:00Z",
"commission_date": "2021-01-01T00:00:00Z",
"info": {
"battery_type": "LITHIUM",
"battery": {
"nominal_capacity": 110,
"nominal_voltage": 51.2
},
"model": "GIV-AC-3.0",
"max_charge_rate": 2560
},
"warranty": {
"type": "Standard",
"expiry_date": "2033-01-01T00:00:00Z"
},
"firmware_version": {
"ARM": 420,
"DSP": 426
},
"connections": {
"batteries": [
{
"module_number": 1,
"serial": "BB2345G123",
"firmware_version": "1035",
"capacity": {
"full": 110,
"design": 110
},
"cell_count": 16,
"has_usb": true,
"nominal_voltage": 51.2
}
],
"meters": [
{
"address": 1,
"serial_number": 212345678,
"manufacturer_code": "0000",
"type_code": 1500,
"hardware_version": 1000,
"software_version": 1000,
"baud_rate": 9600
}
]
},
"flags": []
}
}
}
Received response:
Request failed with error:
EMS Data
Get Latest EMS System Data
requires authentication account type: any scope: api:inverter:read
Retrieves the latest system data from the EMS
EMS Status
The status of the EMS is returned with every EMS datapoint and indicates the operating status of the EMS. The status is an integer that can be one of the following values:
Status | Description |
---|---|
0 | WAITING |
1 | NORMAL |
2 | WARNING |
3 | ERROR |
4 | UPDATING |
5 | BYPASS |
EMS Inverters
An array of inverters is returned with every EMS data point and contains the serial number, status, etc. of each connected inverter.
Inverter Statuses
The status of the given inverter is reported with every inverter and indicates the operating status of the inverter. The status is an integer that can be one of the following values:
Status | Description |
---|---|
0 | DISABLED |
1 | WAITING |
2 | ONLINE |
3 | WARNING |
4 | ERROR |
5 | FLASH |
7 | OFFLINE |
EMS Meters
An array of meters is returned with every EMS data point and contains the type, status, etc. of each meter.
Meter Statuses
The status reported with every meter and indicates the operating status of the meter. The status is an integer that can be one of the following values:
Status | Description |
---|---|
0 | DISABLED |
1 | ONLINE |
2 | OFFLINE |
Meter Types
The type is reported with every meter and indicates the operating type of meter. The type is an integer that can be one of the following values:
Type | Description |
---|---|
0 | GRID |
1 | GENERATION |
2 | LOAD |
3 | OTHER |
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/ems/consequatur/system-data/latest" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/ems/consequatur/system-data/latest"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/ems/consequatur/system-data/latest'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/ems/consequatur/system-data/latest',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": {
"battery_power": 9214,
"battery_wh_remaining": 58276,
"calculated_load_power": 15168,
"car_power": -27828,
"error_code": 40330,
"grid_power": 16772,
"measured_load_power": 19053,
"status": 3,
"time": null,
"total_generation": 8035,
"warning_code": 48384,
"inverters": [
{
"active_power": -8597,
"number": 1,
"serial_number": "il6029p206",
"soc": 88,
"status": 4,
"temperature": 3.2
},
{
"active_power": -2221,
"number": 2,
"serial_number": "nl3168l361",
"soc": 79,
"status": 4,
"temperature": 10.3
},
{
"active_power": 24191,
"number": 3,
"serial_number": "uy0262d251",
"soc": 43,
"status": 2,
"temperature": 28.4
},
{
"active_power": null,
"number": 4,
"serial_number": null,
"soc": null,
"status": 0,
"temperature": null
}
],
"meters": [
{
"active_power": null,
"number": 1,
"status": 0,
"type": 0
},
{
"active_power": null,
"number": 2,
"status": 2,
"type": 1
},
{
"active_power": null,
"number": 3,
"status": 0,
"type": 3
},
{
"active_power": null,
"number": 4,
"status": 2,
"type": 2
},
{
"active_power": null,
"number": 5,
"status": 0,
"type": 0
},
{
"active_power": null,
"number": 6,
"status": 0,
"type": 0
},
{
"active_power": null,
"number": 7,
"status": 0,
"type": 0
},
{
"active_power": null,
"number": 8,
"status": 0,
"type": 0
}
]
}
}
Received response:
Request failed with error:
EV Charger
GivEnergy EV chargers follow version 1.6 of the Open Charge Point Protocol (OCPP 1.6).
Where applicable, EV Charger data returned by the API regarding will be transformed in such a way that it adheres to the OCPP 1.6 standard.
EV Charger Status
The below table is a complete list of all possible statuses that an OCPP 1.6 charger may report at any given time. Each charger may only report one status at once. Non- GivEnergy EV chargers will have their status (if applicable) normalised to an OCPP 1.6 status.
Status | Description |
---|---|
Available | The EV charger is not plugged in to a vehicle |
Preparing | The EV charger is plugged into a vehicle and is ready to start a charge |
Charging | The EV charger is charging the connected EV |
SuspendedEVSE | The charging session has been stopped by the EV charger |
SuspendedEV | The charging session has been stopped by the EV |
Finishing | The charging session has finished, but the EV charger isn't ready to start a new charging session |
Reserved | The EV charger has been reserved for a future charging session |
Unavailable | The EV charger cannot start new charging sessions |
Faulted | The EV charger is reporting an error |
Info
Get Your EV Chargers
requires authentication account type: customer only scope: api:ev-charger:list
Return a list of EV chargers registered to your account
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/ev-charger?page=1" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/ev-charger"
);
const params = {
"page": "1",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/ev-charger'
params = {
'page': '1',
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/ev-charger',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'page' => '1',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
{
"uuid": "ae6050fe-dfb0-497f-b59f-4b90d56766ef",
"serial_number": "02622517580214",
"type": "GivEnergy",
"alias": "Garage",
"online": false,
"went_offline_at": null,
"status": "Charging"
},
{
"uuid": "306c6ee0-633b-4a09-82f7-6199152adee0",
"serial_number": "96893553879883",
"type": "GivEnergy",
"alias": "EV Charger 1",
"online": false,
"went_offline_at": null,
"status": "Unavailable"
}
]
}
Received response:
Request failed with error:
Get EV Charger by UUID
requires authentication account type: any scope: api:ev-charger:read
Return information about a single EV charger by its UUID
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": {
"uuid": "8bf66e82-4f1d-4ee9-9cc4-75da52bf15e7",
"serial_number": "70458130637647",
"type": "GivEnergy",
"alias": "Garage",
"online": false,
"went_offline_at": null,
"status": "Preparing"
}
}
Received response:
Request failed with error:
Meter Data
Data Points
A 'data point' is a collection of sensor readings taken at a point in time from an EV charger's meter.
GivEnergy EV chargers typically capture one data point per meter per minute.
Meters
Each EV charger has 1 or more meters.
A 'meter' is a physical location where data is monitored.
GivEnergy EV chargers use the following meter IDs:
ID | Name | Information |
---|---|---|
0 | EV Charger | These readings are taken by the EV charger internally |
1 | Grid Meter | These readings are taken by the EM115 meter monitoring the grid, if there is one installed |
2 | PV 1 Meter | These readings are taken by the EM115 meter monitoring PV generation source 1, if there is one installed |
3 | PV 2 Meter | These readings are taken by the EM115 meter monitoring PV generation source 2, if there is one installed |
Each data point has at least 1 measurand.
Measurands
A 'measurand' is a reading taken from a certain sensor on the given meter. For example, measurand 13 (Power.Active.Import) is the amount of power that is currently being used by the EV charger to charge the vehicle.
The below table can be used to map the value returned from the API to something more meaningful;
Value | Name | Description |
---|---|---|
0 | Current.Export | Instantaneous current flow from EV |
1 | Current.Import | Instantaneous current flow to EV |
2 | Current.Offered | Maximum current offered to EV |
3 | Energy.Active.Export.Register | Energy exported by EV (Wh or kWh) |
4 | Energy.Active.Import.Register | Energy imported by EV (Wh or kWh) |
5 | Energy.Reactive.Export.Register | Reactive energy exported by EV (varh or kvarh) |
6 | Energy.Reactive.Import.Register | Reactive energy imported by EV (varh or kvarh) |
7 | Energy.Active.Export.Interval | Energy exported by EV (Wh or kWh) |
8 | Energy.Active.Import.Interval | Energy imported by EV (Wh or kWh) |
9 | Energy.Reactive.Export.Interval | Reactive energy exported by EV. (varh or kvarh) |
10 | Energy.Reactive.Import.Interval | Reactive energy imported by EV. (varh or kvarh) |
11 | Frequency | Instantaneous reading of powerline frequency |
12 | Power.Active.Export | Instantaneous active power exported by EV. (W or kW) |
13 | Power.Active.Import | Instantaneous active power imported by EV. (W or kW) |
14 | Power.Factor | Instantaneous power factor of total energy flow |
15 | Power.Offered | Maximum power offered to EV |
16 | Power.Reactive.Export | Instantaneous reactive power exported by EV. (var or kvar) |
17 | Power.Reactive.Import | Instantaneous reactive power imported by EV. (var or kvar) |
18 | RPM | Fan speed in RPM |
19 | SoC | State of charge of charging vehicle in percentage |
20 | Temperature | Temperature reading inside Charge Point. |
21 | Voltage | Instantaneous AC RMS supply voltage |
Each measurand may be accompanied by a unit of measure.
Units of measure
Each measurand has a maximum of 1 unit. The measurand does not necessarily have a unit of measure if the unit can be implied or is not needed, for example RPM.
The below table can be used to map the value returned from the API to something more meaningful:
Value | Unit |
---|---|
0 | Wh |
1 | kWh |
2 | varh |
3 | kvarh |
4 | W |
5 | kW |
6 | VA |
7 | kVA |
8 | var |
9 | kvar |
10 | A |
11 | V |
12 | Celsius |
13 | Fahrenheit |
14 | K |
15 | Percent |
Get Data Points
requires authentication account type: any scope: api:ev-charger:data
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/meter-data?start_time=2023-06-01T00%3A00%3A00Z&end_time=2023-06-02T00%3A00%3A00Z&measurands[]=1&meter_ids[]=1&page=1" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/meter-data"
);
const params = {
"start_time": "2023-06-01T00:00:00Z",
"end_time": "2023-06-02T00:00:00Z",
"measurands[0]": "1",
"meter_ids[0]": "1",
"page": "1",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/meter-data'
params = {
'start_time': '2023-06-01T00:00:00Z',
'end_time': '2023-06-02T00:00:00Z',
'measurands[0]': '1',
'meter_ids[0]': '1',
'page': '1',
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/meter-data',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'start_time' => '2023-06-01T00:00:00Z',
'end_time' => '2023-06-02T00:00:00Z',
'measurands[0]' => '1',
'meter_ids[0]' => '1',
'page' => '1',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
{
"meter_id": 0,
"timestamp": "2023-06-01 08:00:00",
"measurements": [
{
"measurand": 13,
"value": 1145,
"unit": 4
},
{
"measurand": 11,
"value": 50.2,
"unit": null
},
{
"measurand": 21,
"value": 230.5,
"unit": 11
}
]
}
]
}
Received response:
Request failed with error:
Commands
Commands
Below is a list of commands that may be sent to a charger. Some chargers may not support some commands based on hardware, firmware, software or other limitations. You can determine which commands may be sent to a specific charger by calling the Get EV Charger Commands endpoint
Each command is formatted in the following way:
command-id
(This replaces command_id
in the request parameters)
A brief description of the command goes here
Request Data
This is a list of parameters that must be sent with this command
Command Data
This is the data that is stored against each command and is returned by the API. An example of this data can be found in the code example to the right of the page for each command.
A response value of null
typically means that this command will never return data.
Command Data
{
"type": "a description of this parameter can be found here"
}
start-charge
Instructs the charger to start charging
Request Data
This command requires no data
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
[]
stop-charge
Instructs the charger to stop charging
Request Data
This command requires no data
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
[]
adjust-charge-power-limit
Sets the maximum charge power
Request Data
limit
number
Must be between 6 and 32.
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
{
"min": "The minimum value that may be set",
"max": "The maximum value that may be set",
"value": "The value that is currently set",
"unit": "The power limit unit. Can be either A or W"
}
set-plug-and-go
Determines if the charger should be in 'plug-and-go' mode, which is where the charger starts a charge as soon as a vehicle is connected, as long as the charger is communicating with the server
Request Data
enabled
boolean
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
true
set-session-energy-limit
Configures the server to instruct the charger to stop charging if the charging session puts this much energy into the vehicle
Request Data
limit
number
optional
Must be between 0.1 and 250.
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
{
"min": 0.1,
"max": 1000,
"value": 54.5,
"unit": "kWh"
}
set-schedule
Create a new schedule. The newly created schedule is not yet active on the charger
Request Data
schedule_id
string
optional
name
string
Must not be greater than 30 characters.
periods
string[]
periods[].start_time
string
Must be a valid date in the format H:i
.
periods[].end_time
string
Must be a valid date in the format H:i
.
periods[].limit
number
Must be between 6 and 32.
periods[].days
integer[]
Must be at least 0. Must not be greater than 6.
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
{
"schedules": [
{
"id": "The ID of the schedule",
"name": "The name of the schedule",
"is_active": "Whether this schedule is active on the charger",
"periods": [
{
"days": "An array of days of the week that this schedule period runs. From 0 (Monday) to 6 (Sunday)",
"start_time": "The start time of this interval formatted H:i",
"end_time": "The end time of this interval formatted H:i",
"limit": "The power limit of this period in Amps"
}
]
}
]
}
unlock-connector
Instructs the charger to unlock the plug from the vehicle. The vehicle may override this command
Request Data
This command requires no data
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
[]
delete-charging-profile
Delete one or all schedules from the charger
Request Data
schedule_id
string
optional
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
[]
change-mode
Changes the charger's current operating mode
EV Charger Modes
GivEnergy EV chargers have a set number of operational modes. The charger must have one and only one mode selected at all times
Mode information can be found in the table below:
ID | Name | Description |
---|---|---|
SuperEco | Eco+ | The vehicle will charge from excess solar only at a minimum of 6A (1.4kW) |
Eco | Eco | The vehicle will charge at a minimum of 6A (1.4kW) from a combination of excess solar and grid power. If excess solar exceeds 6A (1.4kW), this will be diverted into the EV |
Boost | Boost | The vehicle will charge from a combination of solar and grid up to the “Max Current” limit |
ModbusSlave | Inverter Control | The vehicle will charge based upon instructions that it has been given by the GivEnergy Inverter |
Any active schedule set on the charger will override the current mode. That is, if a schedule is set to start at 4PM, the charger will adhere to the current mode until 4PM then the schedule will start
Request Data
mode
string
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
{
"active": "The currently active mode ID",
"available": "An array of IDs of modes that are available for this charger"
}
restart-charger
Sends a command to restart the charger immediately
Request Data
hard_reset
boolean
optional
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
[]
change-randomised-delay-duration
Sets the randomised delay function on the charger.
Due to government regulations, every EV charger that is capable of starting a charge based on some schedule must start the charge at some random number of seconds after the schedule was set to start. This is to alleviate strain on the grid caused by many chargers starting at once
More information can be found on the gov.uk website
Request Data
duration
number
Must be at least 600. Must not be greater than 1800.
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
null
add-id-tags
Register one or more ID tags to the charger
Request Data
id_tags
string[]
Must have at least 1 items.
id_tags[].id
string
Must not be greater than 20 characters. Must be at least 1 character.
id_tags[].alias
string
optional
id_tags[].expiry_date
string
optional
Must be a valid date.
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
{
"id_tags": [
{
"id": "The ID of the ID tag",
"alias": "The alias of the ID tag. Can be null",
"expiry_date": "The date that the ID tag will no longer work for this charger. Can be null",
"created_at": "The date that the ID tag was registered to this charger"
}
],
"maximum_id_tags": "The maximum number of ID tags that may be registered to this charger"
}
delete-id-tags
Delete one or of the charger's registered ID tags
Request Data
id_tags
string[]
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
null
rename-id-tag
Rename one of the charger's ID tags
Request Data
tag_id
string
Must not be greater than 20 characters. Must be at least 1 character.
alias
string
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
null
installation-mode
Deprecated
Update the charger's installation mode
Installation Modes
Notice
Installation modes are now handled in an enhanced way through the utilisation of the configuration-mode command. It is advised to refrain from using the installation-mode command, as it may lead to unintended side effects. Further information on configuration modes can be found in the dedicated section.
Each charger must specify an installation mode in order to change its operating mode. Typically the installation mode is specified during setup using the GivEnergy app, however it may also be changed via the portal or API. The installation mode may be changed at any time.
The installation mode describes which type of additional hardware the charger is connected to aid in operation or provide better functionality.
Each installation mode supports 1 or more operating modes.
GivEnergy EV chargers use the following installation modes:
ID | Name | Description | Available Modes |
---|---|---|---|
standalone | Standalone | The charger works as a standalone unit with no additional monitoring devices | Boost |
ct_meter | CT + Meter | The charger is connected to at least 1x EM115 meter with CT clamp. One of these meters must monitor grid import and export | Boost Eco EcoPlus |
inverter_control | Inverter Control | The charger is connected to a GivEnergy inverter | ModbusSlave |
Request Data
installation_mode
string
Must be one of standalone
, ct_meter
, or inverter_control
.
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
"standalone"
setup-version
A description has not been provided for this command
Request Data
setup_version
integer
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
A description has not been provided for this command's data
set-active-schedule
Set the charger's active schedule. If no schedule ID is provided the currently active schedule will be deactivated
Request Data
schedule_id
string
optional
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
{
"schedule_id": "The ID of the currently active schedule, if there is one"
}
set-max-import-capacity
Set the maximum import capacity of the charger's main supply in amps
Request Data
value
integer
optional
Must be between 40 and 100.
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
A description has not been provided for this command's data
enable-front-panel-led
Turn the charger's front panel LED on or off
Request Data
value
boolean
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
A description has not been provided for this command's data
configure-inverter-control
Configure the behaviour of the charger and inverter when in inverter control mode
Inverter Control
If a GivEnergy inverter is installed at the same location as a GivEnergy EV charger, the charger can be configured to work in tandem with the inverter to realise new features.
Right now, this behaviour is managed by the GivEnergy Cloud and requires that both the inverter and EV charger have a persistent internet connection. In the future we plan on having this behaviour managed by the inverter itself, which will allow the inverter and EV charger to work together even if the internet connection is lost and provides the added benefit of quick response times.
Benefits of using inverter control include:
- Excess solar generation can be shared between the EV charger and the battery, with the amount of power sent to each device being configurable
- The inverter can be configured to stop discharging the battery when the EV charger is charging
To enable inverter control, you need to do the following:
- Set the configuration mode (
configuration-mode
) toD
(Inverter control cloud) - Change the mode (
change-mode
) toModbusSlave
Configuration Options
inverter_battery_export_split
This option controls how much of the excess solar generation is sent to the battery and how much is sent to the EV charger.
The default value for this option is 0.5 (50%).
Since the EV charger requires a minimum of 6A of export to charge, any export under 6A will be used to charge the battery.
Any export over 6A will be smartly split between the battery and the EV charger, attempting to meet your configured split percentage where possible.
If the total export power is greater than 6A, the charger will always charge at minimum 6A.
Please see the below table for some examples:
Export Power (A) | Value | Battery % | EV % | Battery Charge (A) | EV Charger Charge (A) |
---|---|---|---|---|---|
6 | 0.5 | 50 | 50 | 0 | 6 |
12 | 0.5 | 50 | 50 | 6 | 6 |
9 | 0.5 | 50 | 50 | 3 | 6 |
12 | 0.75 | 75 | 25 | 6 | 6 |
5 | 0.1 | 10 | 90 | 5 | 0 |
32 | 0.9 | 90 | 10 | 26 | 6 |
32 | 0.8 | 80 | 20 | 25.6 | 6.4 |
32 | 0.1 | 10 | 90 | 3.2 | 28.8 |
max_battery_discharge_power_to_evc
This option controls the maximum power (in watts) that the GivEnergy battery may discharge to be used by the EV charger when solar is not generating.
The default value for this option is 0.
The battery will still discharge to cover other local demand where available.
mode
This option controls the operational mode of the EV charger.
The default value for this option is SuperEco
.
Set a value of SuperEco
to instruct the charger to only charge from excess solar at a minimum of 6A.
Set a value of Eco
to instruct the charger to charge at a minimum of 6A,
importing from the grid if there is 6A of excess solar available.
Set a value of Boost
to prevent the battery from discharging beyond
the max_battery_discharge_power_to_evc
plus home demand value when the car is charging. Charges will need to be started manually
by either using an RFID tag or the start-charge
command.
Request Data
inverter_battery_export_split
string
optional
Must be at least 0 characters. Must not be greater than 1 character.
max_battery_discharge_power_to_evc
integer
optional
Must be at least 0.
mode
string
optional
Must be one of Eco
, SuperEco
, or Boost
.
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
{
"inverter_battery_export_split": 0,
"max_battery_discharge_power_to_evc": 0,
"mode": "SuperEco"
}
perform-factory-reset
Performs a factory reset on the charger
Request Data
This command requires no data
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
[]
configuration-mode
Change the configuration mode of the charger
Configuration Modes
Each charger must specify a configuration mode in order to change its operating mode. Typically the configuration mode is specified during setup using the GivEnergy app, however it may also be changed via the portal or API. The configuration mode may be changed at any time.
The configuration mode describes which (if any) additional hardware is installed alongside the EV charger to aid in operation or provide better functionality.
Each configuration mode supports 1 or more operating modes.
GivEnergy EV chargers use the following configuration modes:
ID | Name | Description | Available Modes |
---|---|---|---|
A | Standalone | EVC installed with internet connectivity & mains supply only | Boost |
B | Standalone With PV | EVC installed with internet connectivity & mains supply only, with third party solar inverter and no meters | Boost |
C | CT Meter | EVC installed with internet connectivity, mains supply, wired comms cable & compatible meter | Boost, Eco, SuperEco |
D | Inverter Control Cloud | EVC installed with internet connectivity, mains supply & compatible GivEnergy PV inverter associated with the same GivEnergy cloud account | ModbusSlave |
E | Inverter Control Local (coming soon) | EVC installed with internet connectivity, mains supply & compatible GivEnergy PV inverter wired into charger comms port | ModbusSlave |
Request Data
configuration_mode
string
Must be one of A
, B
, C
, D
, or E
.
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
Command Data
{
"value": "The value of current configuration mode of the charger"
}
enable-local-control
Enable or disable local Modbus control on the charger
Request Data
value
boolean
Command Data
A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document
A description has not been provided for this command's data
Send Command Response
When sending a command to the charger, the response will typically be formatted as per the code example found below:
Where code
is one of the following:
Value | Code | Description |
---|---|---|
0 | SUCCESS | The command was sent successfully |
-1 | TIMEOUT | The charger did not respond to the command in time |
-2 | CHARGER_OFFLINE | The charger did not receive the request because it was offline |
-3 | INVALID_DATA | The charger did not receive the request because the data was invalid |
-4 | FAILURE | The charger actioned the request but did not respond as expected |
-5 | ERROR | There was a error with either the server or charger at some point between sending the request and receiving the response |
success
is a boolean that indicates whether or not the request was successful.
{
"code": 0,
"success": true,
"message": "Accepted"
}
Error Response
If the response code received is ERROR
(-5), additional data will be sent with the response.
The content of the data will be different depending on if it was the server or the charger that experienced the error.
Charger Error
The charger has indicated that it encountered a problem with either its hardware or firmware and could not process the request as expected.
error.code
will be present in the response data and will be one of the following values:
Code | Description |
---|---|
NotImplemented | The charger could not recognise this type of request |
NotSupported | The charger could not handle this type of request |
InternalError | The charger experienced an internal error whilst processing the request |
ProtocolError | The charger could not handle the request because the request data was incomplete |
SecurityError | The charger could not handle the request because of an internal security issue |
FormationViolation | The charger could not handle the request because the request data was not structured correctly |
PropertyConstraintViolation | The charger could not handle the request because one or more fields on the data contained an invalid value |
OccurenceConstraintViolation | The charger could not handle the request because one or more fields on the data contained a value which violates occurrence constraints |
TypeConstraintViolation | The charger could not handle the request because one or more fields on the data contained a value which was the wrong type |
GenericError | An error occurred which is not covered by the other error codes |
These error codes are specified in the OCPP1.6 protocol.
The response may also include data
which is extra data returned by the EV Charger that may be useful to diagnose the cause of the error and prevent it from happening again.
{
"code": -5,
"success": false,
"message": "CallError",
"error": {
"code": "NotImplemented",
"type": "Error",
"message": "This charger does not implement this request"
},
"data": {
"extra": "extra information would be here"
}
}
Server Error
The server has encountered a problem when sending the request or processing the response. These errors will be picked up by our internal monitoring but should be reported if possible
{
"code": -5,
"success": false,
"message": "Error",
"error": {
"type": "Error",
"message": "There was an error on the server"
}
}
Get Supported Commands
requires authentication account type: any scope: api:ev-charger:control
Fetch a list of all commands that are supported for the given EV charger
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
"start-charge",
"stop-charge",
"set-plug-and-go",
"set-session-energy-limit",
"set-schedule",
"change-mode"
]
}
Received response:
Request failed with error:
Get Command Data
requires authentication account type: any scope: api:ev-charger:control
Fetch the current data for the given command and EV Charger
The below response example is for the change-mode
command
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands/setup-version" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands/setup-version"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands/setup-version'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands/setup-version',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": {
"active": "EcoPlus",
"available": [
"Eco",
"EcoPlus",
"Boost"
]
}
}
Received response:
Request failed with error:
Send Command
requires authentication
account type: any
scope: api:ev-charger:control
dynamically validated
Send a command to an EV Charger
Example request:
curl --request POST \
"https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands/setup-version" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands/setup-version"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "POST",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands/setup-version'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands/setup-version',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": {
"code": 0,
"success": true,
"message": "Accepted"
}
}
Received response:
Request failed with error:
Charging Sessions
A 'charging session' or 'transaction' is a single charge of a vehicle. A session starts when the vehicle starts to charge, whether it has been done locally using an ID tag, remotely using the portal, app, or API or automatically by using plug and go or inverter control.
Each charging session contains the following information:
Key | Description | Type | Optional? |
---|---|---|---|
started_by | The ID tag used to start the charge | string | No |
meter_start | The kWh reading of the import meter when this session started | float | No |
started_at | The date and time that the session started | datetime | No |
stopped_by | The ID tag used to stop the charge. | string | Yes |
meter_stop | The kWh reading of the import meter when this session stopped | float | Yes |
stopped_at | The date and time that the session stopped | datetime | Yes |
stop_reason | The reason that this session stopped. See Stop Reasons for more information | string | Yes |
Optional fields will be null if the session has not been stopped.
Stop Reasons
When a charging session is stopped, the stop_reason
field will be populated with one of the following values
to indicate why the session was stopped:
Reason | Description |
---|---|
EmergencyStop | The emergency stop button was pressed |
EVDisconnected | The charging cable was disconnected from the EV |
HardReset | A hard reset command was received |
Local | An RFID tag was used to stop the charging session |
Other | Other |
PowerLoss | The charger experienced a complete loss of power |
Reboot | A locally initiated reboot occurred |
Remote | The charging session was stopped remotely |
SoftReset | A soft reset command was received |
UnlockCommand | An unlock connector command was received |
DeAuthorized | The charging session was not authorised to start |
ID Tags
Starting a Session
When a session is started, the ID tag used to start the session is logged. The ID tag value is different depending on how the session was started:
If the session is started locally using a physical ID tag, this will be the ID tag number which can be found on the tag itself.
If the session is started by a user using the app, API or portal, the value will be their user ID.
If the session is started by plug and go, the value will be PLUG_AND_GO
.
If the session is started by inverter control, the value will be INVERTER_CONTROL
.
Ending a session
When a session is ended, the same rules as above apply. If the session is stopped locally by the charger or EV (for example if the EV is unplugged), the ID tag value will be the same as the one used to start the session.
Get Charging Sessions
requires authentication account type: any scope: api:ev-charger:data
Fetch a list of all charging sessions for the given EV charger
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/charging-sessions?page=1" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"start_time\": \"2019-02-02\",
\"end_time\": \"2105-11-05\"
}"
const url = new URL(
"https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/charging-sessions"
);
const params = {
"page": "1",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"start_time": "2019-02-02",
"end_time": "2105-11-05"
};
fetch(url, {
method: "GET",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/charging-sessions'
payload = {
"start_time": "2019-02-02",
"end_time": "2105-11-05"
}
params = {
'page': '1',
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers, json=payload, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/charging-sessions',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'page' => '1',
],
'json' => [
'start_time' => '2019-02-02',
'end_time' => '2105-11-05',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
{
"started_by": "9f42852",
"meter_start": 933.4,
"started_at": "2000-07-04T09:03:34Z",
"stopped_by": null,
"meter_stop": null,
"stopped_at": null,
"stop_reason": null
},
{
"started_by": "54bd6d5",
"meter_start": 1423.7,
"started_at": "1981-02-09T18:02:07Z",
"stopped_by": null,
"meter_stop": null,
"stopped_at": null,
"stop_reason": null
}
]
}
Received response:
Request failed with error:
Energy Flow Data
Get Energy Flow Data
requires authentication account type: any scope: api:inverter:data
Grouping IDs
Grouping ID | Name | Description |
---|---|---|
0 | Half Hourly | Groups the data into 30-minute intervals |
1 | Daily | Groups the data into 24-hour intervals |
2 | Monthly | Groups the data into monthly intervals |
3 | Yearly | Groups the data into yearly intervals |
4 | Total | Groups the data into a single interval, spanning from the start time to the end time |
Type IDs
Type ID | Name | Description |
---|---|---|
0 | PV to Home | The amount of energy generated by the solar panels to be used immediately for local consumption |
1 | PV to Battery | The amount of energy generated by the solar panels that has been used to charge the battery |
2 | PV to Grid | The amount of energy generated by the solar panels that has been exported to the grid |
3 | Grid to Home | The amount of energy imported from the grid that has been used immediately for local consumption |
4 | Grid to Battery | The amount of energy imported from the grid that has been used to charge the battery |
5 | Battery to Home | The amount of energy discharged by the battery that has been used for local consumption |
6 | Battery to Grid | The amount of energy discharged by the battery that has been exported to the grid |
Fetches the energy flow data for a given inverter between 2 times
Example request:
curl --request POST \
"https://api.givenergy.cloud/v1/inverter/CE1234G567/energy-flows" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"start_time\": \"2022-01-01\",
\"end_time\": \"2022-01-01\",
\"grouping\": 0,
\"types\": [
0,
1,
2,
5
]
}"
const url = new URL(
"https://api.givenergy.cloud/v1/inverter/CE1234G567/energy-flows"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"start_time": "2022-01-01",
"end_time": "2022-01-01",
"grouping": 0,
"types": [
0,
1,
2,
5
]
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/energy-flows'
payload = {
"start_time": "2022-01-01",
"end_time": "2022-01-01",
"grouping": 0,
"types": [
0,
1,
2,
5
]
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
'https://api.givenergy.cloud/v1/inverter/CE1234G567/energy-flows',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'start_time' => '2022-01-01',
'end_time' => '2022-01-01',
'grouping' => 0,
'types' => [
0,
1,
2,
5,
],
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
"start_time": "2022-01-01 00:00",
"end_time": "2022-01-01 00:30",
"data": [
"0": 4.5,
"1": 8.3,
"2": 1.2,
"5": 7.3
],
...
]
}
Received response:
Request failed with error:
Response
Response Fields
data
object[]
The response data
data[].start_time
datetime
The start time of that energy flow record
data[].end_time
datetime
The end time of that energy flow record
data[].data
object
An object where the property is the type and the value is the amount of energy for that period in Kilowatt-Hours (kWh).
For example, { "0": 1, "4": 2 }
means type 0 (PV to Home) has a value of 1 and type 4 (Grid to Battery) has a value of 2. The value has a maximum precision of 2 decimal places
Inverter Control
Presets
Get Setting Presets
requires authentication account type: any scope: api:inverter:control
Retrieves a list of available setting presets for a given inverter
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/inverter/CE1234G567/presets" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/inverter/CE1234G567/presets"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/presets'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/inverter/CE1234G567/presets',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
{
"id": 0,
"name": "Eco",
"description": "This mode will dynamically charge and discharge your batteries to minimise your import from the grid",
"parameters": {
"enabled": {
"description": "Enable or disable the preset",
"validation": [
"required",
"boolean"
]
}
}
},
...
]
}
Received response:
Request failed with error:
Modify Preset
requires authentication
account type: any
scope: api:inverter:control
dynamically validated
Modify one or more inverter settings using a given preset
Example request:
curl --request POST \
"https://api.givenergy.cloud/v1/inverter/CE1234G567/presets/consequatur" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/inverter/CE1234G567/presets/consequatur"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "POST",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/presets/consequatur'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
'https://api.givenergy.cloud/v1/inverter/CE1234G567/presets/consequatur',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": {
"success": true,
"message": "Read Successfully"
}
}
Received response:
Request failed with error:
Single
Get Settings List
requires authentication account type: any scope: api:inverter:control
Returns a set of inverter settings available to your account
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/inverter/CE1234G567/settings" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/inverter/CE1234G567/settings"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/settings'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/inverter/CE1234G567/settings',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
{
"id": 266,
"name": "DC Discharge 3 End Time",
"validation": "Value format should be HH:mm. Use correct time range for hour and minutes",
"validation_rules": [
"date_format:H:i"
]
}
]
}
Received response:
Request failed with error:
Read Setting
requires authentication account type: any scope: api:inverter:control
Read a specific setting on the inverter
Example request:
curl --request POST \
"https://api.givenergy.cloud/v1/inverter/CE1234G567/settings/17/read" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"context\": \"consequatur\"
}"
const url = new URL(
"https://api.givenergy.cloud/v1/inverter/CE1234G567/settings/17/read"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"context": "consequatur"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/settings/17/read'
payload = {
"context": "consequatur"
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
'https://api.givenergy.cloud/v1/inverter/CE1234G567/settings/17/read',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'context' => 'consequatur',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": {
"value": 326.13
}
}
Received response:
Request failed with error:
Modify Setting
requires authentication account type: any scope: api:inverter:control
Write a value to the setting on the inverter
Example request:
curl --request POST \
"https://api.givenergy.cloud/v1/inverter/CE1234G567/settings/17/write" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"value\": \"consequatur\",
\"context\": \"consequatur\"
}"
const url = new URL(
"https://api.givenergy.cloud/v1/inverter/CE1234G567/settings/17/write"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"value": "consequatur",
"context": "consequatur"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/settings/17/write'
payload = {
"value": "consequatur",
"context": "consequatur"
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
'https://api.givenergy.cloud/v1/inverter/CE1234G567/settings/17/write',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'value' => 'consequatur',
'context' => 'consequatur',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": {
"value": 3261.3,
"success": true,
"message": "Read Successfully"
}
}
Received response:
Request failed with error:
Multiple
Modify Setting (Multiple)
requires authentication account type: any scope: api:inverter:control
Write a value to a setting on multiple inverters
Example request:
curl --request POST \
"https://api.givenergy.cloud/v1/multi-control/write" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"inverter_serials\": [
\"SERIAL_1\",
\"SERIAL_2\"
],
\"setting_id\": 17,
\"value\": \"1\"
}"
const url = new URL(
"https://api.givenergy.cloud/v1/multi-control/write"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"inverter_serials": [
"SERIAL_1",
"SERIAL_2"
],
"setting_id": 17,
"value": "1"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/multi-control/write'
payload = {
"inverter_serials": [
"SERIAL_1",
"SERIAL_2"
],
"setting_id": 17,
"value": "1"
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
'https://api.givenergy.cloud/v1/multi-control/write',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'inverter_serials' => [
'SERIAL_1',
'SERIAL_2',
],
'setting_id' => 17,
'value' => '1',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"SERIAL_1": {
"response": 1,
},
"SERIAL_2": {
"response": -2,
}
}
Received response:
Request failed with error:
Read Setting (Multiple)
requires authentication account type: any scope: api:inverter:control
Read a specific setting on multiple inverters
Example request:
curl --request POST \
"https://api.givenergy.cloud/v1/multi-control/read" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"inverter_serials\": [
\"SERIAL_1\",
\"SERIAL_2\"
],
\"setting_id\": 17
}"
const url = new URL(
"https://api.givenergy.cloud/v1/multi-control/read"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"inverter_serials": [
"SERIAL_1",
"SERIAL_2"
],
"setting_id": 17
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/multi-control/read'
payload = {
"inverter_serials": [
"SERIAL_1",
"SERIAL_2"
],
"setting_id": 17
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
'https://api.givenergy.cloud/v1/multi-control/read',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'inverter_serials' => [
'SERIAL_1',
'SERIAL_2',
],
'setting_id' => 17,
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"SERIAL_1": {
"response": 1,
},
"SERIAL_2": {
"response": -2,
}
}
Received response:
Request failed with error:
Inverter Data
Inverter Statuses
The status of the given inverter is reported with every data point and indicates the operating status of the inverter. The status is a string that can be one of the following values:
Status | Description |
---|---|
NORMAL | The inverter is operating normally and is processing an amount power |
WAITING | The inverter is operating normally and is not processing any power |
LOST | The inverter is offline |
UNKNOWN | The inverter has recently connected to the GivEnergy platform and has not yet updated its status |
ERROR | The inverter is reporting one or more faults. Its performance will be impacted |
WARNING | The inverter is reporting one or more warnings. Its performance may not be impacted |
UPDATING | The inverter is currently updating its firmware |
BYPASS | The inverter is currently in bypass mode |
Request Inverter Data
requires authentication
account type: any
scope: api:inverter:read
approved users only
Sends a command to the inverter to force it to persist a data point
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/inverter/CE1234G567/request-data" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/inverter/CE1234G567/request-data"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/request-data'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/inverter/CE1234G567/request-data',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (success):
{
"success": true
}
Example response (failure):
{
"success": false
}
Received response:
Request failed with error:
Get Latest System Data
requires authentication account type: any scope: api:inverter:read
Retrieves the latest system data from the inverter
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/inverter/CE1234G567/system-data/latest" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/inverter/CE1234G567/system-data/latest"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/system-data/latest'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/inverter/CE1234G567/system-data/latest',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": {
"time": "2006-10-31T23:16:07Z",
"status": "Normal",
"solar": {
"power": 1526,
"arrays": [
{
"array": 1,
"voltage": 369.8,
"current": 918.5,
"power": 881
},
{
"array": 2,
"voltage": 413.1,
"current": 654.2,
"power": 563
}
]
},
"grid": {
"voltage": 2155.3,
"current": -4688.5,
"power": -3270,
"frequency": 259.5
},
"battery": {
"percent": 83,
"power": -2484,
"temperature": 85
},
"inverter": {
"temperature": 80,
"power": 37241,
"output_voltage": 222.1,
"output_frequency": 49.28,
"eps_power": 224
},
"consumption": 38674
}
}
Received response:
Request failed with error:
Get Latest Meter Data
requires authentication account type: any scope: api:inverter:read
Retrieves the latest meter data from the inverter
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/inverter/CE1234G567/meter-data/latest" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/inverter/CE1234G567/meter-data/latest"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/meter-data/latest'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/inverter/CE1234G567/meter-data/latest',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": {
"time": "1992-08-15T14:35:09Z",
"today": {
"solar": 5690.3,
"grid": {
"import": 9880.9,
"export": 4294.6
},
"battery": {
"charge": 91852.3,
"discharge": 65419.6
},
"consumption": 938.6,
"ac_charge": 30996.9
},
"total": {
"solar": 57462.4,
"grid": {
"import": 184.9,
"export": 5659
},
"battery": {
"charge": 8763.7,
"discharge": 8763.7
},
"consumption": 66779,
"ac_charge": 26925.1
},
"is_metered": true
}
}
Received response:
Request failed with error:
Get Events
requires authentication account type: any scope: api:inverter:data
Retrieves a list of faults that were triggered from the inverter and when they were cleared
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/inverter/CE1234G567/events?start=consequatur&end=consequatur&cleared=&page=1" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"cleared\": false,
\"start\": \"2019-02-03\",
\"end\": \"2105-11-05\"
}"
const url = new URL(
"https://api.givenergy.cloud/v1/inverter/CE1234G567/events"
);
const params = {
"start": "consequatur",
"end": "consequatur",
"cleared": "0",
"page": "1",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"cleared": false,
"start": "2019-02-03",
"end": "2105-11-05"
};
fetch(url, {
method: "GET",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/events'
payload = {
"cleared": false,
"start": "2019-02-03",
"end": "2105-11-05"
}
params = {
'start': 'consequatur',
'end': 'consequatur',
'cleared': '0',
'page': '1',
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers, json=payload, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/inverter/CE1234G567/events',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'start' => 'consequatur',
'end' => 'consequatur',
'cleared' => '0',
'page' => '1',
],
'json' => [
'cleared' => false,
'start' => '2019-02-03',
'end' => '2105-11-05',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
{
"event": "Parallel communication failure",
"start_time": "2004-01-27T07:53:39Z",
"end_time": null
},
{
"event": "Inverter Current Fault",
"start_time": "1996-04-23T02:23:48Z",
"end_time": null
}
]
}
Received response:
Request failed with error:
Get Data Points
requires authentication account type: any scope: api:inverter:data
Inverter Data Point Schema
Data Point
Field | Description | Unit | Type |
---|---|---|---|
time | Timestamp data point was reported | - | ISO8601-datetime |
status | Status of the inverter | - | string |
power | See power data section below | - | - |
today | See today/total data section below | - | - |
total | See today/total data section below | - | - |
is_metered | Whether the data point includes readings from the grid meter | - | boolean |
Power Data
Field | Description | Unit | Type |
---|---|---|---|
solar | See solar power section below | - | - |
grid | See grid power section below | - | - |
battery | See battery data section below | - | - |
consumption | See consumption data section below | - | - |
inverter | See inverter data section below | - | - |
Solar Power
Field | Description | Unit | Type |
---|---|---|---|
power | Total solar power generated | W | integer |
arrays | List of solar arrays providing power, see solar arrays section below | - | SolarArray[] |
Solar Arrays
Field | Description | Unit | Type |
---|---|---|---|
array | Array number | - | integer |
voltage | Solar array voltage | V | decimal,1 |
current | Solar array current | A | decimal,1 |
power | Power being generated by the solar array | W | integer |
Grid Power
Field | Description | Unit | Type |
---|---|---|---|
voltage | Grid voltage | V | decimal,1 |
current | Grid current | A | decimal,1 |
power | Power supplied from(-)/to(+) the grid | W | integer |
frequency | Grid frequency | Hz | decimal,2 |
Battery Data
Field | Description | Unit | Type |
---|---|---|---|
percent | Battery percentage | % | integer |
power | Power charging(-)/discharging(+) from the battery | W | integer |
temperature | Battery temperature | °C | decimal,1 |
Consumption Data
Field | Description | Unit | Type |
---|---|---|---|
power | Power consumed by the site | W | integer |
Inverter Data
Field | Description | Unit | Type |
---|---|---|---|
temperature | Inverter temperature | °C | decimal,1 |
power | Power output/input from the inverter | W | integer |
output_voltage | Inverter voltage | V | decimal,1 |
output_frequency | Inverter frequency | Hz | decimal,2 |
eps_power | EPS power (emergency power supply) | W | integer |
Today/Total Data
Field | Description | Unit | Type |
---|---|---|---|
solar | PV generation energy today/total | kWh | decimal,1 |
grid | See grid section below | - | - |
battery | See battery section | - | - |
consumption | Power consumption today/total | kWh | decimal,1 |
ac_charge | AC charge energy today/total | kWh | decimal,1 |
Grid
Field | Description | Unit | Type |
---|---|---|---|
import | Grid import energy today/total | kWh | decimal,1 |
export | Grid export energy today/total | kWh | decimal,1 |
Battery
Field | Description | Unit | Type |
---|---|---|---|
charge | Battery charge today/total | kWh | decimal,1 |
discharge | Battery discharge today/total | kWh | decimal,1 |
Displays the entire data packet set from the chosen date
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/inverter/CE1234G567/data-points/consequatur?page=1" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/inverter/CE1234G567/data-points/consequatur"
);
const params = {
"page": "1",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/data-points/consequatur'
params = {
'page': '1',
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/inverter/CE1234G567/data-points/consequatur',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'page' => '1',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
{
"time": "1997-02-19T03:53:16Z",
"status": "LOST",
"power": {
"solar": {
"power": 4703,
"arrays": [
{
"array": 1,
"voltage": 198.6,
"current": 3.3,
"power": 491
},
{
"array": 2,
"voltage": 170.8,
"current": 10,
"power": 2806
}
]
},
"grid": {
"voltage": 128.3,
"current": 98.1,
"power": 19821,
"frequency": 49.25
},
"battery": {
"percent": 79,
"power": -2289,
"temperature": 12
},
"consumption": {
"power": 22636
},
"inverter": {
"temperature": 50,
"power": -9476,
"output_voltage": 144.7,
"output_frequency": 49.69,
"eps_power": 24672
}
},
"today": {
"solar": 4373.9,
"grid": {
"import": 3168.4,
"export": 5384.4
},
"battery": {
"charge": 8691.3,
"discharge": 4350.4
},
"consumption": 5673.7,
"ac_charge": 8021.5
},
"total": {
"solar": 4353.3,
"grid": {
"import": 4625.8,
"export": 7045.8
},
"battery": {
"charge": 1034.1,
"discharge": 1034.1
},
"consumption": 7757.1,
"ac_charge": 9568.8
},
"is_metered": true
},
{
"time": "2013-10-23T04:13:45Z",
"status": "UNKNOWN",
"power": {
"solar": {
"power": 3748,
"arrays": [
{
"array": 1,
"voltage": 439.3,
"current": 0.5,
"power": 3339
},
{
"array": 2,
"voltage": 26.9,
"current": 9.9,
"power": 3324
}
]
},
"grid": {
"voltage": 66.5,
"current": 77.6,
"power": 20120,
"frequency": 49.75
},
"battery": {
"percent": 60,
"power": 799,
"temperature": 50.1
},
"consumption": {
"power": 47610
},
"inverter": {
"temperature": 29.3,
"power": -7702,
"output_voltage": 167.6,
"output_frequency": 49.01,
"eps_power": 21174
}
},
"today": {
"solar": 452,
"grid": {
"import": 9389.9,
"export": 1836.2
},
"battery": {
"charge": 6270.8,
"discharge": 5510.6
},
"consumption": 9864.4,
"ac_charge": 4178.8
},
"total": {
"solar": 4574.4,
"grid": {
"import": 6372.2,
"export": 3627.8
},
"battery": {
"charge": 15.7,
"discharge": 15.7
},
"consumption": 3788.9,
"ac_charge": 300.3
},
"is_metered": true
}
]
}
Received response:
Request failed with error:
Notifications
Notification Platform
Each notification must be sent to one or more platforms. Currently, the following platforms are supported:
Platform | Description |
---|---|
persist |
Persists a notification to the user's notifications center in the portal and mobile app |
push |
Sends a push notification to all devices that the user is logged in to on the mobile app |
Send Notification
requires authentication account type: any scope: api:notification:send rate limited: 10,60
Sends a notification to your account on the specified platforms
A failure indicates that the notification could not be sent to one or more of the specified platforms
To help prevent misuse of this endpoint, the values of body
and title
must meet the following requirements:
- They must not include any email addresses
- They must not include any telephone numbers
- They must not include any URLs (with or without
http(s)://
prefix)
As this endpoint is used and user behaviour patterns are analyzed, the validation rules may change over time without warning to keep users safe. If modifications to this endpoint's validation rules are made, this endpoint's documentation will be updated and details of the change will be included in the changelog found at the bottom of this document
To help users identify the origin of notifications sent via this endpoint, a message will be included at the end of the notification body that either states the name of the third-party application that sent the notification or the name of the token used, whichever is applicable
Users and third-party applications found to be abusing this endpoint will have their API access revoked
Example request:
curl --request POST \
"https://api.givenergy.cloud/v1/notification/send" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"platforms\": [
\"persist\"
],
\"title\": \"Something amazing has happened!\",
\"body\": \"Here is some information about the amazing thing that has happened\",
\"icon\": \"mdi-account-outline\"
}"
const url = new URL(
"https://api.givenergy.cloud/v1/notification/send"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"platforms": [
"persist"
],
"title": "Something amazing has happened!",
"body": "Here is some information about the amazing thing that has happened",
"icon": "mdi-account-outline"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/notification/send'
payload = {
"platforms": [
"persist"
],
"title": "Something amazing has happened!",
"body": "Here is some information about the amazing thing that has happened",
"icon": "mdi-account-outline"
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
'https://api.givenergy.cloud/v1/notification/send',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'platforms' => [
'persist',
],
'title' => 'Something amazing has happened!',
'body' => 'Here is some information about the amazing thing that has happened',
'icon' => 'mdi-account-outline',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (success):
{
"success": true
}
Example response (failure):
{
"success": false
}
Received response:
Request failed with error:
Site
Get Your Sites
requires authentication account type: any scope: api:site:list
Retrieves a list of your sites
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/site?page=1" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/site"
);
const params = {
"page": "1",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/site'
params = {
'page': '1',
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/site',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'page' => '1',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
{
"id": 7,
"name": "Jeremy Hill",
"account": "yreynolds.814",
"date_created": "1988-02-17",
"country": "FAROE_IS",
"timezone": "GMT",
"tz_timezone": "Europe/Astrakhan",
"latitude": 79.284177,
"longitude": 1.10994,
"type": "SINGLE_PHASE",
"products": []
},
{
"id": 8,
"name": "Heather Thompson",
"account": "anderson.ian.503",
"date_created": "2018-07-16",
"country": "TOKELAU",
"timezone": "GMT",
"tz_timezone": "Atlantic/South_Georgia",
"latitude": -52.674876,
"longitude": -141.434346,
"type": "SINGLE_HYBIRD",
"products": []
}
]
}
Received response:
Request failed with error:
Get Single Site by ID
requires authentication account type: any scope: api:site:read
Gather a single site's information
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/site/17" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/site/17"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/site/17'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/site/17',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": {
"id": 9,
"name": "Jeremy Hill",
"account": "arthur94.60",
"date_created": "1988-02-17",
"country": "FAROE_IS",
"timezone": "GMT",
"tz_timezone": "Europe/Astrakhan",
"latitude": 79.284177,
"longitude": 1.10994,
"type": "SINGLE_PHASE",
"products": []
}
}
Received response:
Request failed with error:
Site Status
Site Status
The site's status indicates if the site is occupied and if they have opted in to any available schemes.
If the site status is null
, it is assumed that this site is not part of any scheme.
Status | Description |
---|---|
vacant | Vacant |
opted_in | Opted In |
opted_out | Opted Out |
Get Site Status
requires authentication
account type: any
scope: api:site:read
approved users only
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/site/17/status" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/site/17/status"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/site/17/status'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/site/17/status',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"status": "vacant"
}
Received response:
Request failed with error:
Update Site Status
requires authentication
account type: any
scope: api:site:update
approved users only
Update the status of a site. Provide a status of null
to delete the status.
Modifying the site status will automatically perform any modifications to any hardware on that site as required.
Example request:
curl --request POST \
"https://api.givenergy.cloud/v1/site/17/status" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
const url = new URL(
"https://api.givenergy.cloud/v1/site/17/status"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "POST",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/site/17/status'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
'https://api.givenergy.cloud/v1/site/17/status',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"success": true
}
Received response:
Request failed with error:
Smart Device
Device
Get Your Smart Devices
requires authentication account type: any scope: api:smart-device:list
List the smart devices registered to your account
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/smart-device?page=1" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/smart-device"
);
const params = {
"page": "1",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/smart-device'
params = {
'page': '1',
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/smart-device',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'page' => '1',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
{
"uuid": "48a8d332-c5e8-40d4-82e8-f82f645ba669",
"alias": "veniam",
"other_data": {
"graph_color": "#f0c27c",
"hardware_id": "P",
"local_key": "J"
}
},
{
"uuid": "a642da10-7e0f-4bdb-8d52-9954ddb3415e",
"alias": "ea",
"other_data": {
"graph_color": "#6e7655",
"hardware_id": "p",
"local_key": "!"
}
}
]
}
Received response:
Request failed with error:
Create Smart Device
requires authentication account type: any scope: api:smart-device:create
Register a new smart device to your account
Example request:
curl --request POST \
"https://api.givenergy.cloud/v1/smart-device" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"serial_number\": \"consequatur\",
\"alias\": \"consequatur\",
\"product_name\": \"consequatur\",
\"manufacturer\": \"consequatur\",
\"other_data\": []
}"
const url = new URL(
"https://api.givenergy.cloud/v1/smart-device"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"serial_number": "consequatur",
"alias": "consequatur",
"product_name": "consequatur",
"manufacturer": "consequatur",
"other_data": []
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/smart-device'
payload = {
"serial_number": "consequatur",
"alias": "consequatur",
"product_name": "consequatur",
"manufacturer": "consequatur",
"other_data": []
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
'https://api.givenergy.cloud/v1/smart-device',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'serial_number' => 'consequatur',
'alias' => 'consequatur',
'product_name' => 'consequatur',
'manufacturer' => 'consequatur',
'other_data' => [],
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
{
"uuid": "5f774acf-c1f8-4397-8ab8-11f0f7591f95",
"alias": "iste",
"other_data": {
"graph_color": "#22c331",
"hardware_id": "e",
"local_key": "/"
}
},
{
"uuid": "a8a72437-e91e-40b9-9962-7eba1094630c",
"alias": "ut",
"other_data": {
"graph_color": "#913ee5",
"hardware_id": "#",
"local_key": "l"
}
}
]
}
Received response:
Request failed with error:
Get Smart Device by ID
requires authentication account type: any scope: api:smart-device:read
Get a smart device's information
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea'
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
{
"uuid": "dc9fa757-190c-4916-a5f9-a34ffd1e7c1d",
"alias": "veniam",
"other_data": {
"graph_color": "#f0c27c",
"hardware_id": "P",
"local_key": "J"
}
},
{
"uuid": "49aa4fdd-b9ec-4244-957a-890653cbe6fa",
"alias": "sit",
"other_data": {
"graph_color": "#ea2f1a",
"hardware_id": "Z",
"local_key": "<"
}
}
]
}
Received response:
Request failed with error:
Data
Get Smart Device Data Points by ID
requires authentication account type: any scope: api:smart-device:data
Get a list of a smart device's data points
Example request:
curl --request GET \
--get "https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea/data?page=1" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea/data"
);
const params = {
"page": "1",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea/data'
params = {
'page': '1',
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
'https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea/data',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'query' => [
'page' => '1',
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
{
"time": "1987-03-13T13:05:30Z",
"power": 509
},
{
"time": "2020-02-06T18:59:47Z",
"power": 884
}
]
}
Received response:
Request failed with error:
Create Smart Device Data Point
requires authentication account type: any scope: api:smart-device:data
Store a data point against a smart device
Example request:
curl --request POST \
"https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea/data" \
--header "Authorization: Bearer {YOUR_API_KEY}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"time\": \"consequatur\",
\"power\": 17
}"
const url = new URL(
"https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea/data"
);
const headers = {
"Authorization": "Bearer {YOUR_API_KEY}",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"time": "consequatur",
"power": 17
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json
url = 'https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea/data'
payload = {
"time": "consequatur",
"power": 17
}
headers = {
'Authorization': 'Bearer {YOUR_API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.request('POST', url, headers=headers, json=payload)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
'https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea/data',
[
'headers' => [
'Authorization' => 'Bearer {YOUR_API_KEY}',
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'time' => 'consequatur',
'power' => 17,
],
]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response (200):
{
"data": [
{
"time": "1980-03-23T05:34:16Z",
"power": 622
},
{
"time": "1971-06-09T14:15:47Z",
"power": 567
}
]
}
Received response:
Request failed with error:
Changelog
v1.27.0 (2024-09-30)
- Endpoints
- Get Data Points
- Added inverter data point response details
- Get Data Points
v1.26.0 (2024-09-10)
- Endpoints
- Site
- Added Get Site Status Endpoint
- Added Update Site Status Endpoint
- Site
v1.25.0 (2024-05-29)
-
Endpoints
-
Inverter Data
- Updated the endpoint to be accessible by approved non-commercial accounts as well
-
Meta
- Updated approved users only Badge description
-
v1.24.0 (2024-05-01)
-
Endpoints
- Inverter Data
- Added a new endpoint to request the data point. This endpoint is only be available for authorised commercial partners
- Inverter Data
-
Meta
- Added approved users only Badge
v1.23.0 (2024-04-25)
- Endpoints
- Communication Devices Endpoints
- HV battery data is now returned under
inverter.connections.batteries
- Added
nominal_voltage
toinverter.connections.batteries
- HV battery data is now returned under
- Communication Devices Endpoints
v1.22.0 (2024-03-25)
- Endpoints
- Plant Information
- Added
standard_timezone
to response data. This value follows the ISO-8601 international standard
- Added
- Plant Information
v1.21.0 (2024-03-05)
- Endpoints
- Account Information
- Added
standard_timezone
to response data. This value follows the ISO-8601 international standard
- Added
- Account Information
v1.20.0 (2024-02-28)
- Endpoints
- Added a new endpoint for Plant EMS system data.
- Returns status, battery power, grid power; along with inverter and meter data
- Added a new endpoint for Plant EMS system data.
v1.19.0 (2024/01/03)
- Endpoints
- Get Your Communication Devices & Get Communication Device Information by Serial Number
- Added
meters
toinverter.connections
. This is an array of objects containing information about the meters connected to the inverter
- Added
- Get Your Communication Devices & Get Communication Device Information by Serial Number
v1.18.0 (2023-12-06)
- Endpoints
- Get Your Communication Devices & Get Communication Device Information by Serial Number
- Added
module_number
toinverter.connections.batteries
. This number represents the battery's physical position in relation to other packs where the master pack has amodule_number
of 1. Each battery must have a unique value formodule_number
and the value must be between 1 and the number of batteries in the system - Fixed a problem where batteries that had been replaced were still being shown in
inverter.connections.batteries
- Added
- Get Your Communication Devices & Get Communication Device Information by Serial Number
v1.17.0 (2023-11-23)
- Endpoints
- Get Your Communication Devices & Get Communication Device Information by Serial Number
- Added
inverter.flags
to response data
- Added
- Notifications
- Added Send Notification endpoint
- Get Your Communication Devices & Get Communication Device Information by Serial Number
- Meta
- Documentation
- Added Inverter Flags information section to Communication Device endpoint group
- Added Rate Limiting section
- Changed the description of response code 429 to 'Rate limit quota exceeded' from 'Too many requests'
- Documentation
- Authentication
- Added
api:notification
andapi:notification:send
token scopes
- Added
v1.16.0 (2023-11-15)
- Endpoints
- Inverter Get Data Points & Get Latest System Data
- Added
status
to response data. An explanation of each status may be found at the top of the Inverter Data section
- Added
- Inverter Get Data Points & Get Latest System Data
v1.15.0 (2023-11-10)
- Endpoints
- Inverter Single Read & Modify Setting
- Added an optional
context
body parameter. When provided, this context will be seen in the 'via' column of the remote control history as 'API - Inverter Settings - {context}'
- Added an optional
- Inverter Single Read & Modify Setting
v1.14.0 (2023-11-06)
- Endpoints
- Account Information
- Added
postcode
to response data
- Added
- Inverter Data Points & Inverter Realtime Energy Data
- Added
today.ac_charge
which represents the amount of energy from the grid used to charge the battery since midnight - Added
total.ac_charge
which represents the amount of energy from the grid used to charge the battery since the inverter was installed - Added
is_metered
which represents whether the data point's energy values were read from the meters. Can rarely befalse
erroneously but can never betrue
erroneously
- Added
- Account Information
v1.13.0 (2023-10-11)
- Endpoints
- EV Charger
- Added Get Charging Sessions endpoint
- EV Charger
v1.12.0 (2023-08-15)
- Authentication
- API token generation
- Improved API token generation in the following ways:
- Multiple API tokens may now be generated for the same account
- API tokens may now be named
- API tokens may now have custom expiry times set
- API tokens may now have scopes applied
- API tokens generated before this update are named 'local_api_token', expire 1 year after they were created and will already have all scopes applied
- Improved API token generation in the following ways:
- Fixed an issue where some endpoints with the 'account type' badge were not preventing accounts without that type from accessing them
- API token generation
- Meta
- Documentation
- 'requires * permission' badges changed to 'scope/s: *' in line with the changes to API tokens
- References to 'API Key' have been replaced with 'API Token' throughout
- Improved wording of 'account type' badge and added account type for every endpoint
- Documentation
v1.11.0 (2023-06-09)
- Endpoints
- EV Charger
- Added Get Your EV Chargers endpoint
- Added Get Your EV Charger by UUID endpoint
- Added Get Data Points endpoint
- Added Get Supported Commands endpoint
- Added Get Command Data endpoint
- Added Send Command endpoint
- All With Inverter Data
- Added
battery.nominal_capacity
,battery.nominal_voltage
andmax_charge_rate
toinfo
- Added
- Get Settings List
- Added missing
validation
property in the example response - Added
validation_rules
to the response data which includes computer-parseable validation rules
- Added missing
- EV Charger
- Meta
- Improved request URL parameter name generation logic
- Improved request example value generation logic. Serial numbers and usernames should no longer be 'consequatur'
v1.10.2 (2023-05-12)
- Endpoints
- Get Account Dongles by ID
- Fixed
inverter.connections.batteries
not being present in the response data
- Fixed
- Get Account Dongles by ID
- Meta
- Fixed
inverter.connections.batteries
not being present in the response examples for the following endpoints:- Get Account Dongles by ID
- Get Your Communication Devices
- Get Communication Device Information by Serial Number
- Fixed
v1.10.1 (2022-12-06)
- Meta
- Improved documentation generation techniques
- There was a surprising amount of backend work required to make these changes - if you spot anything wrong, please let us know!
- Added the ability to further group endpoints inside groups (subgroups)
- Included subgroups for several endpoints
- Changelog section is now shown in the side bar
- Renamed 'Remote Control' section to 'Remote Control Codes'
- Improved documentation generation techniques
v1.10.0 (2022-11-23)
- Endpoints
- Inverter Control Read/Write Multiple
- Added a maximum length of 1000 to the
inverter_serials
body parameter
- Added a maximum length of 1000 to the
- Smart Device
- Fixed example responses
- Inverter Control Read/Write Multiple
v1.9.3 (2022-09-26)
- Endpoints
- Get Communication Device by Serial Number
- Fixed an issue where the device's inverter and batteries were not being returned
- Get Communication Device by Serial Number
v1.9.2 (2022-07-11)
- Endpoints
- All With Inverter Data
- The response data
last_online
andlast_updated
properties now return the correct time
- The response data
- All With Inverter Data
v1.9.1 (2022-07-06)
- Endpoints
- Get Your Sites
- The response data
account
property now returns the correct value
- The response data
- Get Your Sites
v1.9.0 (2022-06-27)
- Endpoints
- Modify Preset
- The response data now includes the relevant error code if the command fails
- Modify Preset
v1.8.0 (2022-05-09)
- Endpoints
- Energy Flow Data
- Added Get Energy Flow Data endpoint
- Get Inverter Data
- Added additional validation for the
date
query parameter - Improved data point timezone resolution for certain historical data
- Added additional validation for the
- Energy Flow Data
- Meta
- Added
datetime
data type - Renamed
json
data type toobject
to avoid type ambiguity
- Added
v1.7.0 (2022-05-03)
- Endpoints
- Get Your Sites
- Added
site_id
to the response data for each site
- Added
- Site Data Endpoints
products
now correctly returns an array of objects instead of a single object
- Get Your Sites
v1.6.0 (2022-04-19)
-
Endpoints
- Inverter Control
- Added Modify Setting (Multiple) and Read Setting (Multiple) endpoints
- Account
- Added Get Account Dongles by ID endpoint
- Inverter Control
-
Meta
- Added Remote Control section
v1.5.2 (2022-04-04)
- Endpoints
- Some With Timestamps
- Fixed timestamps displaying as Zulu time but actually being local system time
- Some With Timestamps
v1.5.1 (2022-03-08)
- Endpoints
- All With Pagination
- Fixed
pageSize
URL parameter not being respected correctly
- Fixed
- All With Pagination
v1.5.0 (2022-03-08)
- Endpoints
- Get Data Points
- Added
inverter.temperature
,inverter.power
,inverter.output_voltage
,inverter.output_temperature
andinverter.eps_power
to the response data
- Added
- Get Data Points
v1.4.1 (2022-03-08)
- Endpoints
- Get Communication Device Information by Serial Number
- Fixed erroneous 404 response for some account types
- Get Communication Device Information by Serial Number
v1.4.0 (2022-03-04)
- Endpoints
- Get Latest System Data
- Fixed
battery.temperature
showing inverter temperature - Added
inverter.temperature
,inverter.power
,inverter.output_voltage
,inverter.output_frequency
,inverter.eps_power
to the response data
- Fixed
- Get Your Account Children & Get Account Children By ID
- Fixed documentation showing single object as response instead of array of objects
- Get Account Children Information by ID
- Specified that the
account
parameter is the account ID
- Specified that the
- All With Pagination
- Updated pagination
page
andpageSize
query parameters type tointeger
instead ofstring
- Updated pagination
- Get Your Communication Devices
- Added missing paginated badge
- Get Latest System Data
v1.3.1 (2022-03-03)
- Endpoints
- Get Data Points
- Removed erroneous
time
parameter - Clarified that the
date
parameter assumes the inverter's local time
- Removed erroneous
- Get Data Points
v1.3.0 (2022-03-02)
- Endpoints
- All With Date/Time Response Values
- Date/time response values are now ISO8601 formatted (or null, where applicable)
- All With Date/Time Response Values
v1.2.0 (2022-02-28)
- Endpoints
- Inverter Data
- All Data Endpoints
- Fixed rounding errors on decimal values
- Fixed some properties always returning null
- Get Latest System Data
- Removed
grid.import
/grid.export
, replaced withgrid.power
(these values were always returning null) - Removed
battery.charge
/battery.charge
, replaced withbattery.power
(these values were always returning null)
- Removed
- All Data Endpoints
- Inverter Control
- Fixed some users not being able to read/write settings
- Inverter Data
v1.1.0 (2022-02-24)
-
Endpoints
- Inverter Control
- Get Setting Presets
- Added
parameters
property to response data
- Added
- Read/Modify Setting
- Removed erroneous
id
URL Parameter
- Removed erroneous
- Get Setting Presets
- Inverter Control
-
Meta
- Added Request Parameters Section
- Moved Validation Errors from Response Format to Request Parameters
- Added dynamically validated Badge
v1.0.0 (2022-02-21)
Initial Release
-
Endpoints
- Added Account Endpoints
- Get Your Account Information
- Get Account Information by ID
- Get Account Information by Username
- Get Your Account Children Information
- Get Account Children Information by ID
- Added Communication Device Endpoints
- Get Your Communication Devices
- Get Communication Device Information by Serial Number
- Added Inverter Control Endpoints
- Get Setting Presets
- Modify Preset
- Get Settings List
- Read Setting
- Write Setting
- Added Inverter Data Endpoints
- Get Latest System Data
- Get Latest Meter Data
- Get Events
- Get Data Points
- Added Site Endpoints
- Get Your Sites
- Get Single Site by ID
- Added Smart Device Endpoints
- Get Your Smart Devices
- Create Smart Device
- Get Smart Device by ID
- Create Smart Device Data Point
- Get Smart Device Data Points by ID
- Added Account Endpoints
-
Meta
- Added Introduction Section
- Added Authentication Requests Section
- Added Headers Section
- Added Badges Section
- Added Response Codes Section
- Added Response Format Section
- Added Data Types Section