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

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:

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:

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:

{
    "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:

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:

Data Types

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

Meta

The following data is returned on the meta object with the response data

{
    "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:

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

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));

                                        
                    {
    "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"
    }
}
                 

Get Account Information by ID

requires authentication account type: engineer+ scope: api:account:read

Retrieves the information of a specific account by its ID

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));

                                        
                    {
    "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"
    }
}
                 

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

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));

                                        
                    {
    "data": [
        {
            "serial_number": "49niih5fqc",
            "firmware_version": null,
            "type": "GPRS",
            "commission_date": "1997-08-12T15:06:19Z",
            "inverter": {
                "serial": "FC4716A325",
                "status": "NORMAL",
                "last_online": "2024-05-15T16:27:56Z",
                "last_updated": "2007-11-26T13:58:32Z",
                "commission_date": "1991-01-15T22:14:31Z",
                "info": {
                    "battery_type": "LITHIUM",
                    "battery": {
                        "nominal_capacity": 165,
                        "nominal_voltage": 51.2,
                        "depth_of_discharge": 1
                    },
                    "model": "Plant EMS",
                    "max_charge_rate": 2600
                },
                "warranty": {
                    "type": "Standard Legacy",
                    "expiry_date": "1996-01-15T22:14:31Z"
                },
                "firmware_version": {
                    "ARM": null,
                    "DSP": null
                },
                "connections": {
                    "batteries": []
                },
                "flags": [
                    "full-power-discharge-in-eco-mode"
                ]
            }
        },
        {
            "serial_number": "28sobz4oqi",
            "firmware_version": null,
            "type": "GPRS",
            "commission_date": "1996-02-07T23:40:44Z",
            "inverter": {
                "serial": "ED8493J072",
                "status": "LOST",
                "last_online": "2001-07-09T01:03:08Z",
                "last_updated": "1995-10-28T04:55:51Z",
                "commission_date": "1982-01-22T21:34:04Z",
                "info": {
                    "battery_type": "LITHIUM",
                    "battery": {
                        "nominal_capacity": 52,
                        "nominal_voltage": 307.2,
                        "depth_of_discharge": 0.85
                    },
                    "model": "All-In-One",
                    "max_charge_rate": 6000
                },
                "warranty": {
                    "type": "Standard Legacy",
                    "expiry_date": "1987-01-22T21:34:04Z"
                },
                "firmware_version": {
                    "ARM": 420,
                    "DSP": 426
                },
                "connections": {
                    "batteries": []
                },
                "flags": []
            }
        }
    ]
}
                 

Get Account Information by Username

requires authentication account type: engineer+ scope: api:account:read

Retrieves the information of a specific account by its username

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));

                                        
                    {
    "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"
    }
}
                 

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

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));

                                        
                    {
    "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"
        }
    ]
}
                 

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

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));

                                        
                    {
    "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"
        }
    ]
}
                 

Get List Of Accounts Associated With Your SSO Identity

requires authentication account type: any scopes: api:account:list, api:sso:list

Retrieves all accounts that have been associated with your SSO identity

curl --request GET \
    --get "https://api.givenergy.cloud/v1/sso/me/accounts" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://api.givenergy.cloud/v1/sso/me/accounts"
);

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/sso/me/accounts'
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/sso/me/accounts',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

                                        
                    {
    "data": [
        {
            "id": 23,
            "name": "anna00.369",
            "first_name": "Alexandra",
            "surname": "Shaw",
            "role": "SUPER_ENGINEER",
            "email": "jack60@lewis.net",
            "address": "57 James Spring",
            "postcode": "NG5 1JR",
            "country": "UNITED_KINGDOM",
            "telephone_number": "08691 273874",
            "timezone": "GMT",
            "standard_timezone": "Europe/London"
        },
        {
            "id": 24,
            "name": "arthur94.60",
            "first_name": "Grace",
            "surname": "Fox",
            "role": "VIEWER",
            "email": "tim32@gmail.com",
            "address": "9 Hall Knolls",
            "postcode": "L38 9EB",
            "country": "UNITED_KINGDOM",
            "telephone_number": "(0262) 6260924",
            "timezone": "GMT +9",
            "standard_timezone": "Asia/Yakutsk"
        }
    ]
}
                 

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:

Get Your Communication Devices

requires authentication account type: any scope: api:inverter:list

View a collection of communication devices you have access to

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));

                                        
                    {
    "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": []
            }
        }
    ]
}
                 

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

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));

                                        
                    {
    "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": []
        }
    }
}
                 

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:

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:

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:

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:

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));

                                        
                    {
    "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
            }
        ]
    }
}
                 

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.

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

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));

                                        
                    {
    "data": [
        {
            "uuid": "49e01bb1-7c58-49e7-8db9-4772d00b53b9",
            "serial_number": "02622517580214",
            "type": "GivEnergy",
            "alias": "Garage",
            "online": false,
            "went_offline_at": null,
            "status": "Charging"
        },
        {
            "uuid": "bbbb44b8-d1a8-4b42-bf4e-e897954b5749",
            "serial_number": "96893553879883",
            "type": "GivEnergy",
            "alias": "EV Charger 1",
            "online": false,
            "went_offline_at": null,
            "status": "Unavailable"
        }
    ]
}
                 

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

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));

                                        
                    {
    "data": {
        "uuid": "c7c63c19-75df-412f-8bda-61afa46a10d4",
        "serial_number": "70458130637647",
        "type": "GivEnergy",
        "alias": "Garage",
        "online": false,
        "went_offline_at": null,
        "status": "Preparing"
    }
}
                 

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:

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;

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:

Get Data Points

requires authentication account type: any scope: api:ev-charger:data

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));

                                        
                    {
    "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
                }
            ]
        }
    ]
}
                 

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:

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:

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) to D (Inverter control cloud)
• Change the mode (change-mode) to ModbusSlave

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:

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:

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:

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:

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

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));

                                        
                    {
    "data": [
        "start-charge",
        "stop-charge",
        "set-plug-and-go",
        "set-session-energy-limit",
        "set-schedule",
        "change-mode"
    ]
}
                 

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

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));

                                        
                    {
    "data": {
        "active": "EcoPlus",
        "available": [
            "Eco",
            "EcoPlus",
            "Boost"
        ]
    }
}
                 

Send Command

requires authentication account type: any scope: api:ev-charger:control

dynamically validated

Send a command to an EV Charger

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));

                                        
                    {
    "data": {
        "code": 0,
        "success": true,
        "message": "Accepted"
    }
}
                 

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:

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:

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

curl --request GET \
    --get "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/charging-sessions?start_time=2019-03-18&end_time=2105-12-20&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/charging-sessions"
);

const params = {
    "start_time": "2019-03-18",
    "end_time": "2105-12-20",
    "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/charging-sessions'
params = {
  'start_time': '2019-03-18',
  'end_time': '2105-12-20',
  '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/charging-sessions',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'start_time' => '2019-03-18',
            'end_time' => '2105-12-20',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

                                        
                    {
    "data": [
        {
            "started_by": "9f42852",
            "meter_start": 933.4,
            "started_at": "2000-07-28T23:38:11Z",
            "stopped_by": null,
            "meter_stop": null,
            "stopped_at": null,
            "stop_reason": null
        },
        {
            "started_by": "54bd6d5",
            "meter_start": 1423.7,
            "started_at": "1981-02-18T17:06:26Z",
            "stopped_by": null,
            "meter_stop": null,
            "stopped_at": null,
            "stop_reason": null
        }
    ]
}
                 

Energy Flow Data

Get Energy Flow Data

requires authentication account type: any scope: api:inverter:data

Grouping IDs

Type IDs

Fetches the energy flow data for a given inverter between 2 times

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));

                                        
                    {
     "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
         ],
         ...
     ]
 }
                 

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

Inverter Presets

Inverter presets are a way to change inverter behaviour without needing to know which individual settings to change. One such example is the 'Timed Charge' preset, which will configure any inverter that supports batteries to force the battery to charge from the grid during the specified time period(s).

This abstraction allows for the same command to be sent to multiple inverters, regardless of their make or model.

Presets

Below is a list of all presets that are available.

Eco (ID: eco-mode) (Legacy ID: 0)

This setting will use your battery or solar to power your home's electric demand

This preset has a single enabled field that can be toggled to enable or disable the preset

Timed Charge (ID: timed-charge) (Legacy ID: 1)

This mode will trigger your battery to charge at the times you specify

This preset requires an array (or object, where the keys are the slot numbers) of slots that contain the following fields:

• start_time - The time that the slot should start
• end_time - The time that the slot should end
• percent_limit - The amount that this slot will charge up to. This is not available for all slots for all inverters

For most inverters, this preset also has an enabled field that can be toggled to enable or disable the preset

Examples of setting different slots can be seen to the right:

// modify slots 1 and 2 and enable all slots
{
    enabled: true,
    slots: [
        { 
            start_time: "00:00", 
            end_time: "06:00", 
            percent_limit: 50
        },
        { 
            start_time: "06:00", 
            end_time: "12:00", 
            percent_limit: 100
        }
    ]
}

// modify slots 2 and 4 and disable all slots
{
    enabled: false,
    slots: {
        1: { 
            start_time: "00:00", 
            end_time: "06:00", 
            percent_limit: 50
        },
        3: { 
            start_time: "06:00", 
            end_time: "12:00", 
            percent_limit: 100
        }
    }
}

Timed Discharge (ID: timed-discharge) (Legacy ID: 2)

This mode will trigger your battery to cover your home's electric demand only at the times you specify

This preset requires an array (or object, where the keys are the slot numbers) of slots that contain the following fields:

• start_time - The time that the slot should start
• end_time - The time that the slot should end
• percent_limit - The amount that this slot will discharge down to. This is not available for all slots for all inverters

For most inverters, this preset also has an enabled field that can be toggled to enable or disable the preset

Examples of setting different slots can be seen to the right:

// modify slots 1 and 2 and enable all slots
{
    enabled: true,
    slots: [
        { 
            start_time: "00:00", 
            end_time: "06:00", 
            percent_limit: 50
        },
        { 
            start_time: "06:00", 
            end_time: "12:00", 
            percent_limit: 100
        }
    ]
}

// modify slots 2 and 4 and disable all slots
{
    enabled: false,
    slots: {
        1: { 
            start_time: "00:00", 
            end_time: "06:00", 
            percent_limit: 50
        },
        3: { 
            start_time: "06:00", 
            end_time: "12:00", 
            percent_limit: 100
        }
    }
}

Timed Export (ID: timed-export) (Legacy ID: 3)

This mode will trigger your battery to discharge at its max power at the times you specify

This preset requires an array (or object, where the keys are the slot numbers) of slots that contain the following fields:

• start_time - The time that the slot should start
• end_time - The time that the slot should end
• percent_limit - The amount that this slot will export down to. This is not available for all slots for all inverters

For most inverters, this preset also has an enabled field that can be toggled to enable or disable the preset

Examples of setting different slots can be seen to the right:

// modify slots 1 and 2 and enable all slots
{
    enabled: true,
    slots: [
        { 
            start_time: "00:00", 
            end_time: "06:00", 
            percent_limit: 50
        },
        { 
            start_time: "06:00", 
            end_time: "12:00", 
            percent_limit: 100
        }
    ]
}

// modify slots 2 and 4 and disable all slots
{
    enabled: false,
    slots: {
        1: { 
            start_time: "00:00", 
            end_time: "06:00", 
            percent_limit: 50
        },
        3: { 
            start_time: "06:00", 
            end_time: "12:00", 
            percent_limit: 100
        }
    }
}

Battery Options (ID: battery-operating-range) (Legacy ID: 4)

Operating Range

This preset determines its information from multiple sources that change depending on the inverter. Call the 'Get Settings Presets' endpoint for the relevant inverter to determine the correct fields to send

Reset to Defaults (ID: reset-to-defaults) (Legacy ID: 5)

Reset all charge modes, timers and limits to their factory defaults

This preset does not require any data. Simply set the preset and the underlying settings will be set to the appropriate value

Plant Enable (ID: plant-ems-enable-control) (Legacy ID: 7)

This mode will enable the plant to minimise import and export from the grid

This preset has a single enabled field that can be toggled to enable or disable the preset

Grid Settings (ID: grid-settings) (Legacy ID: 14)

Modify various grid-related settings such as import and export limitations

This preset determines its information from multiple sources that change depending on the inverter. Call the 'Get Settings Presets' endpoint for the relevant inverter to determine the correct fields to send

Optimisation

When modifying a preset, the server will always attempt to modify all settings in the preset that correspond to the provided values, even if the values are already present on the inverter. This is to ensure that the inverter is always in a consistent state.

To improve the speed at which the presets are set, and to reduce the risk of failures, only provide data that needs to be changed.

For example, if you only wish to change the start and end time of the 2nd slot in the 'Timed Charge' preset, and don't need to change whether it is enabled or its percentage limit, you can send the command found to the right:

// POST inverter/{serial}/presets/1

{
    "slots": {
        "1": {
            "start_time": "14:00",
            "end_time": "16:00"
        }
    }
}

Get Setting Presets

requires authentication account type: any scope: api:inverter:control

Retrieves a list of available setting presets for a given inverter

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));

                                        
                    {
     "data": [
         {
             "id": 0,
             "identifier": "eco",
             "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"
                     ]
                 }
             }
         },
         ...
     ]
}
                 

Modify Preset

requires authentication account type: any scope: api:inverter:control

dynamically validated

Modify one or more inverter settings using a given preset

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));

                                        
                    {
    "data": {
        "success": true,
        "message": "Read Successfully"
    }
}
                 

Single

Get Settings List

requires authentication account type: any scope: api:inverter:control

Returns a set of inverter settings available to your account

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));

                                        
                    {
    "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"
            ]
        }
    ]
}
                 

Read Setting

requires authentication account type: any scope: api:inverter:control

Read a specific setting on the inverter

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));

                                        
                    {
    "data": {
        "value": 326.13
    }
}
                 

Modify Setting

requires authentication account type: any scope: api:inverter:control

Write a value to the setting on the inverter

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));

                                        
                    {
    "data": {
        "value": 326.13,
        "success": true,
        "message": "Read Successfully"
    }
}
                 

Multiple

Modify Setting (Multiple)

requires authentication account type: any scope: api:inverter:control

Write a value to a setting on multiple inverters

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));

                                        
                    {
     "SERIAL_1": {
         "response": 1,
     },
     "SERIAL_2": {
         "response": -2,
     }
}
                 

Read Setting (Multiple)

requires authentication account type: any scope: api:inverter:control

Read a specific setting on multiple inverters

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));

                                        
                    {
     "SERIAL_1": {
         "response": 1,
     },
     "SERIAL_2": {
        "response": -2,
     }
 }
                 

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:

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

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));

                                        
                    {
    "success": true
}
                 

                                        
                    {
    "success": false
}
                 

Get Latest System Data

requires authentication account type: any scope: api:inverter:read

Retrieves the latest system data from the inverter

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));

                                        
                    {
    "data": {
        "time": "2006-11-30T16:18:49Z",
        "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
    }
}
                 

Get Latest Meter Data

requires authentication account type: any scope: api:inverter:read

Retrieves the latest meter data from the inverter

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));

                                        
                    {
    "data": {
        "time": "1992-09-02T20:31:37Z",
        "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
    }
}
                 

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

curl --request GET \
    --get "https://api.givenergy.cloud/v1/inverter/CE1234G567/events?cleared=&start=2019-03-19&end=2105-12-20&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/events"
);

const params = {
    "cleared": "0",
    "start": "2019-03-19",
    "end": "2105-12-20",
    "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/events'
params = {
  'cleared': '0',
  'start': '2019-03-19',
  'end': '2105-12-20',
  '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/events',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'cleared' => '0',
            'start' => '2019-03-19',
            'end' => '2105-12-20',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

                                        
                    {
    "data": [
        {
            "event": "Parallel communication failure",
            "start_time": "2004-02-23T19:28:41Z",
            "end_time": null
        },
        {
            "event": "Inverter Current Fault",
            "start_time": "1996-05-14T07:43:24Z",
            "end_time": null
        }
    ]
}
                 

Get Data Points

requires authentication account type: any scope: api:inverter:data

Inverter Data Point Schema

Data Point

Power Data

Solar Power

Solar Arrays

Grid Power

Battery Data

Consumption Data

Inverter Data

Today/Total Data

Grid

Battery

Displays the entire data packet set from the chosen date

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));

                                        
                    {
    "data": [
        {
            "time": "1997-03-13T06:12:00Z",
            "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": "2019-02-19T19:55:15Z",
            "status": "WARNING",
            "power": {
                "solar": {
                    "power": 1696,
                    "arrays": [
                        {
                            "array": 1,
                            "voltage": 487.8,
                            "current": 6,
                            "power": 4946
                        },
                        {
                            "array": 2,
                            "voltage": 469.5,
                            "current": 12.2,
                            "power": 400
                        }
                    ]
                },
                "grid": {
                    "voltage": 167.9,
                    "current": 53.6,
                    "power": -19627,
                    "frequency": 50.4
                },
                "battery": {
                    "percent": 3,
                    "power": -224,
                    "temperature": 7.6
                },
                "consumption": {
                    "power": 49322
                },
                "inverter": {
                    "temperature": 24.1,
                    "power": -1620,
                    "output_voltage": 150.5,
                    "output_frequency": 50.1,
                    "eps_power": 31038
                }
            },
            "today": {
                "solar": 6372.2,
                "grid": {
                    "import": 5934.1,
                    "export": 4242.1
                },
                "battery": {
                    "charge": 3230.9,
                    "discharge": 3788.9
                },
                "consumption": 8714.2,
                "ac_charge": 7876.6
            },
            "total": {
                "solar": 3627.8,
                "grid": {
                    "import": 2198.6,
                    "export": 8016
                },
                "battery": {
                    "charge": 4981.1,
                    "discharge": 4981.1
                },
                "consumption": 2147,
                "ac_charge": 9886.1
            },
            "is_metered": true
        }
    ]
}
                 

Notifications

Notification Platform

Each notification must be sent to one or more platforms. Currently, the following platforms are supported:

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

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));

                                        
                    {
    "success": true
}
                 

                                        
                    {
    "success": false
}
                 

Site

Get Your Sites

requires authentication account type: any scope: api:site:list

Retrieves a list of your sites

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));

                                        
                    {
    "data": [
        {
            "id": 7,
            "name": "Jeremy Hill",
            "account": "yreynolds.814",
            "date_created": "1988-03-03",
            "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-08-24",
            "country": "TOKELAU",
            "timezone": "GMT",
            "tz_timezone": "Atlantic/South_Georgia",
            "latitude": -52.674876,
            "longitude": -141.434346,
            "type": "SINGLE_HYBIRD",
            "products": []
        }
    ]
}
                 

Get Single Site by ID

requires authentication account type: any scope: api:site:read

Gather a single site's information

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));

                                        
                    {
    "data": {
        "id": 9,
        "name": "Jeremy Hill",
        "account": "wilkinson.zach.820",
        "date_created": "1988-03-03",
        "country": "FAROE_IS",
        "timezone": "GMT",
        "tz_timezone": "Europe/Astrakhan",
        "latitude": 79.284177,
        "longitude": 1.10994,
        "type": "SINGLE_PHASE",
        "products": []
    }
}
                 

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.

Get Site Status

requires authentication account type: any scope: api:site:read

approved users only

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));

                                        
                    {
    "status": "vacant"
}
                 

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.

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));

                                        
                    {
    "success": true
}
                 

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

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));

                                        
                    {
    "data": [
        {
            "uuid": "40004020-501a-461e-9583-be2d8d40172e",
            "alias": "veniam",
            "other_data": {
                "graph_color": "#f0c27c",
                "hardware_id": "P",
                "local_key": "J"
            }
        },
        {
            "uuid": "ad9b2bcd-bf06-446c-bfae-e1a32e022d99",
            "alias": "sit",
            "other_data": {
                "graph_color": "#ea2f1a",
                "hardware_id": "Z",
                "local_key": "<"
            }
        }
    ]
}
                 

Create Smart Device

requires authentication account type: any scope: api:smart-device:create

Register a new smart device to your account

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));

                                        
                    {
    "data": [
        {
            "uuid": "ca505626-1e97-4fc2-bd18-d3159bd093a5",
            "alias": "iste",
            "other_data": {
                "graph_color": "#22c331",
                "hardware_id": "e",
                "local_key": "/"
            }
        },
        {
            "uuid": "5da597e2-d1b0-44ee-9f9c-0f177f282e87",
            "alias": "ut",
            "other_data": {
                "graph_color": "#913ee5",
                "hardware_id": "#",
                "local_key": "l"
            }
        }
    ]
}
                 

Get Smart Device by ID

requires authentication account type: any scope: api:smart-device:read

Get a smart device's information

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));

                                        
                    {
    "data": [
        {
            "uuid": "350a416b-b0bc-4170-a7b2-8644df3636ec",
            "alias": "veniam",
            "other_data": {
                "graph_color": "#f0c27c",
                "hardware_id": "P",
                "local_key": "J"
            }
        },
        {
            "uuid": "21058305-b387-477f-9793-e261a60e1f30",
            "alias": "nostrum",
            "other_data": {
                "graph_color": "#608742",
                "hardware_id": "_",
                "local_key": ")"
            }
        }
    ]
}
                 

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

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));

                                        
                    {
    "data": [
        {
            "time": "1987-03-27T09:58:41Z",
            "power": 509
        },
        {
            "time": "1973-09-26T22:30:28Z",
            "power": 206
        }
    ]
}
                 

Create Smart Device Data Point

requires authentication account type: any scope: api:smart-device:data

Store a data point against a smart device

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));

                                        
                    {
    "data": [
        {
            "time": "1980-03-31T11:29:44Z",
            "power": 622
        },
        {
            "time": "1971-06-10T18:04:05Z",
            "power": 567
        }
    ]
}
                 

Changelog

v1.31.0 (2024-11-19)

• Endpoints
  • Inverter Presets - Get Setting Presets
    • Added identifier property to response data. This is a new, human-readable ID that may be used in place of the numeric ID when calling the 'Modify Preset' endpoint.
      • It is recommended to use this new ID as it is more human-readable, making it easier to identify the preset you wish to modify in your integrations
  • Inverter Presets - Modify Preset
    • Both integer and string IDs now work for all presets
• Meta
  • Documentation - Presets
    • In the opening section, 'ID' has been renamed to 'Legacy ID' and moved to the right. The string ID has been put in the legacy ID's original place
    • Fixed an issue where charge/discharge slots 2 and 4 were incorrectly identified as slots 1 and 3 in the examples

v1.30.0 (2024-11-13)

• Endpoints
  • Account - List SSO associated accounts
    • Added an endpoint to list all user accounts associated with the user's SSO identity
• Authentication
  • Added api:sso and api:sso:list token scopes

v1.29.0 (2024-11-05)

• Endpoints
  • Inverter Control - Presets
    • Added more information about presets at the top of the section
    • Added information about the presets that are available across all inverter models
    • Consolidated similar presets into a single entry, for example timed charge for single- and three-phase inverters. This removes presets with IDs 6 & 8-13
    • Presets with time slots now accept multiple slots, depending on the inverter
    • Existing calls that modify a single slot are still supported, however users are encouraged to migrate to the new logic
    • Attempting to partially modify a preset by only including a subset of required parameters now only changes the appropriate settings on the inverter

v1.28.0 (2024-10-24)

• Endpoints
  • EV Charger
    • Updated the Get Charging Sessions endpoint to use Query Parameters instead of Body Parameters
  • Inverter Data
    • Removed the Body Parameters from the Get Events endpoint as they are already defined in Query Parameters

v1.27.0 (2024-09-30)

• Endpoints
  • Get Data Points
    • Added inverter data point response details

v1.26.0 (2024-09-10)

• Endpoints
  • Site
    • Added Get Site Status Endpoint
    • Added Update Site Status Endpoint

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

• 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 to inverter.connections.batteries

v1.22.0 (2024-03-25)

• Endpoints
  • Plant Information
    • Added standard_timezone to response data. This value follows the ISO-8601 international standard

v1.21.0 (2024-03-05)

• Endpoints
  • Account Information
    • Added standard_timezone to response data. This value follows the ISO-8601 international standard

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

v1.19.0 (2024/01/03)

• Endpoints
  • Get Your Communication Devices & Get Communication Device Information by Serial Number
    • Added meters to inverter.connections. This is an array of objects containing information about the meters connected to the inverter

v1.18.0 (2023-12-06)

• Endpoints
  • Get Your Communication Devices & Get Communication Device Information by Serial Number
    • Added module_number to inverter.connections.batteries. This number represents the battery's physical position in relation to other packs where the master pack has a module_number of 1. Each battery must have a unique value for module_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

v1.17.0 (2023-11-23)

• Endpoints
  • Get Your Communication Devices & Get Communication Device Information by Serial Number
    • Added inverter.flags to response data
  • Notifications
    • Added Send Notification endpoint
• 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'
• Authentication
  • Added api:notification and api:notification:send token scopes

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

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}'

v1.14.0 (2023-11-06)

• Endpoints
  • Account Information
    • Added postcode to response data
  • 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 be false erroneously but can never be true erroneously

v1.13.0 (2023-10-11)

• Endpoints
  • EV Charger
    • Added Get Charging Sessions endpoint

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
  • Fixed an issue where some endpoints with the 'account type' badge were not preventing accounts without that type from accessing them
• 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

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 and max_charge_rate to info
  • Get Settings List
    • Added missing validation property in the example response
    • Added validation_rules to the response data which includes computer-parseable validation rules
• 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
• 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

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'

v1.10.0 (2022-11-23)

• Endpoints
  • Inverter Control Read/Write Multiple
    • Added a maximum length of 1000 to the inverter_serials body parameter
  • Smart Device
    • Fixed example responses

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

v1.9.2 (2022-07-11)

• Endpoints
  • All With Inverter Data
    • The response data last_online and last_updated properties now return the correct time

v1.9.1 (2022-07-06)

• Endpoints
  • Get Your Sites
    • The response data account property now returns the correct value

v1.9.0 (2022-06-27)

• Endpoints
  • Modify Preset
    • The response data now includes the relevant error code if the command fails

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
• Meta
  • Added datetime data type
  • Renamed json data type to object to avoid type ambiguity

v1.7.0 (2022-05-03)

• Endpoints
  • Get Your Sites
    • Added site_id to the response data for each site
  • Site Data Endpoints
    • products now correctly returns an array of objects instead of a single object

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

• 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

v1.5.1 (2022-03-08)

• Endpoints
  • All With Pagination
    • Fixed pageSize URL parameter not being respected correctly

v1.5.0 (2022-03-08)

• Endpoints
  • Get Data Points
    • Added inverter.temperature, inverter.power, inverter.output_voltage, inverter.output_temperature and inverter.eps_power to the response data

v1.4.1 (2022-03-08)

• Endpoints
  • Get Communication Device Information by Serial Number
    • Fixed erroneous 404 response for some account types

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
  • 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
  • All With Pagination
    • Updated pagination page and pageSize query parameters type to integer instead of string
  • Get Your Communication Devices
    • Added missing paginated badge

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

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)

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 with grid.power (these values were always returning null)
      • Removed battery.charge/battery.charge, replaced with battery.power (these values were always returning null)
  • Inverter Control
    • Fixed some users not being able to read/write settings

v1.1.0 (2022-02-24)

• Endpoints

  • Inverter Control
    • Get Setting Presets
      • Added parameters property to response data
    • Read/Modify Setting
      • Removed erroneous id URL Parameter

• 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

• 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