MENU navbar-image

Introduction

This documentation provides all the information needed to work with the GivEnergy APIs

GivEnergy's public API is free for both personal & commercial use. Commercial use of the free API is rate restricted. A paid Commercial option is also available with custom access rates and additional features. To find out more our enhanced commercial offering, please visit this web page.

Base URL

https://api.givenergy.cloud/v1

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_API_KEY}"

All authenticated endpoints are marked with a requires authentication badge in the documentation below. This is also explained in the Badges section of this document

You can manage your API tokens by visiting the API Tokens page

Headers

Always ensure to have the following headers set with every request. If these headers are not included the response may not return valid data

Accept: application/json
Content-Type: application/json

Badges

Badge Description
scopes: api:inverter:read, api:inverter:control The API token used needs all of these scopes to be able to use this API endpoint
account type: account (only, +) Your account must be at exactly this type (only) or at least this type (+) to use this API endpoint
requires authentication You must provide a valid API token to use this API endpoint
rate limited: limit,minutes This endpoint has a custom rate limit of limit requests every minutes minute(s). See Rate Limiting for more information
paginated This endpoint returns additional pagination metadata. See Pagination for more information
dynamically validated This endpoint's parameters are dynamically validated. See Dynamic Validation for more information
approved users only This endpoint is only accessible by authorised users

Request Parameters

Most requests require 1 or more parameters to be passed into the request to search for specific data or to refine the data that is received

This section of the documentation describes to how to enter these parameters, how they are validated and what might happen

Parameter Types

Most endpoints found in this document provide details about which URL parameters, Query Parameters and Body Parameters may be passed into the request

URL Parameters are passed directly into the URL, and are indicated by a variable name inside curly brackets. For example: inverter/{inverter}/data-points/{date} where an inverter serial number must replace {inverter} and an ISO8601-date must replace {date} inverter/XXXXXXXXXX/data-points/2022-01-06

Query Parameters are appended to the end of the URL, following a question mark (?) and a list of ampersand (&) delimited key=value pairs, where key is the name of the parameter and value is its value. For example: https://api.givenergy.cloud/v1/inverter/XXXXXXXXXX/data-points/2022-01-06?page=1&pageSize=20 includes parameter page with a value of 1

Body Parameters are passed into the request body. Examples may be seen for each request in the 'Example request' section

Validation

Documented Validation

Most endpoints provide simple validation rules in the URL parameters, Query Parameters or Body Parameters

For example

URL Parameters

a-url-parameter string optional

Denotes that the URL parameter must be a string, and that it can be optional. A list of data types can be found in the Data Types section of this document

Dynamic Validation

Some endpoints require and validate parameters differently depending on the content of other parameters.

Some endpoints may also return validation input required for a different endpoint, for example: calling the Get Setting Presets endpoint will return a parameters property which is a list of parameters that must be entered in the body of the Modify Preset endpoint in order to properly make the request

These endpoints will be marked with a dynamically validated badge

Due to the way that these endpoints are validated and handled, their dynamic content may change at any time. Well-defined endpoint parameters and response data will never change in this way

The parameters will be a json object, where each key is the property and its corresponding value adheres to the following format:

Property Description
description The description of the parameter
validation An array of validation rules for this parameter

An example of this can be seen in the code section

{
     "data": [
         {
             "id": 0,
             "name": "Eco",
             "description": "This mode will dynamically charge and discharge your batteries to minimise your import from the grid",
             "parameters": {
                 "enabled": {
                     "description": "Enable or disable the preset",
                     "validation": [
                         "required",
                         "boolean"
                     ]
                 }
             }
         },
         ...
     ]
}

The array of validation rules will either be one the types described in Data Types or one of the following:

Name Description
optional The parameter is not required
required The parameter is required
min:value The value must be at least value
max:value The value must be no larger than value
numeric The value must be numeric (integer or decimal)
alpha:length The value must be a string of alphanumeric characters with length length
between:min,max The value must be between min and max
date_format:format,format2,... The value must be a string that matches one of the PHP date formats
bitwise:bits Value must be an empty string (for no values) or a comma-separated list of values from 1 to bits
in:value1,value2,... The value must be exactly one of the allowed values
object The value must be a valid JSON object
property:property:rule1,rule2,... The value of property on the value must pass all of the validation rules
hex:length The value must be a string of hexadecimal characters with length length

Validation Errors

If any invalid url, query or body parameters are passed into the request and a 422 status code is returned, data will be returned with the following format:

Property Description
message A description of the validation error. Typically "The given data was invalid."
errors An object of key => value errors, where key is the validation property that has errors, and value is an array of failed validation messages
{
    "message": "The given data was invalid.",
    "errors": {
        "value": [
            "The value field is required."
        ]
    }
}

Response Codes

The GivEnergy API uses conventional HTTP response codes to indicate the success or failure of an API request. The table below contains a summary of the typical response codes:

Code Description
200 The response was successful
201 The response was successful and a resource was created
400 Valid data was given but the request has failed
401 No valid API Token was given
403 Your account is not authorised to visit this endpoint or view this resource
404 The request endpoint or resource could not be found
422 The payload has missing required parameters or invalid data was given
429 Rate limit quota exceeded
500 The request failed due to an internal server error
502 The request failed due to an internal server error
503 The API is offline for maintenance
504 The request took too long to process

Response Format

Responses will always return a JSON object as long as the correct headers are set

Any successful response (status 2XX) will have its relevant data returned in the data property on the JSON object

See the 'Example Response' section for each endpoint to see how the response might look

Paginated responses will include additional data. See Pagination for more information

Response data will be different if invalid request data is provided. See Validation for more information

Remote Control Codes

When performing read or write commands to a device, a response value will be returned

When sending a command to a single device, the response value, a message and a boolean indicating if the response was successful will also be returned

When sending a command to multiple devices at once, only the response value will be returned. The response value may be either the value sent to the device, a different value (indicating that the device modified its value, but not to the one received) or one of the below error codes:

Code Description Potentially Successful?
-1 The device did not respond before the request timed out Yes
-2 The device is offline No
-3 The device does not exist or your account does not have access to the device No
-4 There were one or more validation errors. Additional information may be available No
-5 There was a server error Yes
-6 There was no response from the server Yes

Data Types

Type Description Examples
ISO8601-type Type is either date or datetime See this link for more information date 2022-01-01
datetime 2022-01-01T12:34:56Z
datetime A generic datetime, formatted YYYY-MM-DD hh:mm:ss. This data type is typically used when fetching data from endpoints that operate based on the system or user's local time 2022-01-01 06:30:00
type,delimited A string of comma-separated values where type is the type of each value 1,2,3
yes,no,maybe
string A simple string Hello!
integer A whole number 1
100
-5000
decimal,precision A decimal number with precision number of digits after the decimal point decimal,1 1.5
decimal,6 0.000001
decimal,0 5
type[] An array of values with type type integer[] [1, 2, 3]
string[] ["yes", "no", "maybe"]
object A valid JSON object { "some": "json", "data": { "that": { "can": "be nested" }, "and": [ "include", "arrays", "of", "data" ] } }
boolean A simple boolean. A string of "true" or "false" is invalid 1
0
true
false

Pagination

Paginated responses are typically returned when the data being requested is part of a collection, for example retrieving a list of user accounts or hardware associated with a particular user

Paginated results always include links and meta properties which contain the following information

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

Property Description
first The link to the first page of paginated results
last The link to the last page of paginated results
prev The link to the previous page of paginated results
next The link to the next page of paginated results

Meta

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

Property Description
current_page The currently visited page's page number
from The number of the first record in this page, in comparison to all records
last_page The number of the last page in the collection
path The current uri, without any additional pagination query parameters
per_page The number of records returned with this response
to The number of the last record in this page, in comparison to all records
total The total number of records
{
    "data": [
        ...
    ],
    "links": {
        "first": "https://api.givenergy.cloud/v1/inverter/XXXXXXXXXX/events?page=1",
        "last": "https://api.givenergy.cloud/v1/inverter/XXXXXXXXXX/events?page=3",
        "prev": null,
        "next": "https://api.givenergy.cloud/v1/inverter/XXXXXXXXXX/events?page=2",
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 3,
        "path": "https://api.givenergy.cloud/v1/inverter/XXXXXXXXXX/events",
        "per_page": 15,
        "to": 15,
        "total": 35
    }
}

Rate Limiting

This API is rate limited, meaning that requests will not be processed if the user exceeds a certain number of requests in a given window. The window starts when the first request is made that counts towards the rate limit and ends after the specified number of minutes has elapsed

Every request that returns a response from the API counts towards the rate limit regardless of the response code received

The default global rate limit is 300 requests per minute shared across all endpoints

If the rate limit is exceeded, a response with code 429 will be returned

Every response will include the following headers to assist with managing rate limiting:

Header Description
X-RateLimit-Limit The maximum number of requests that the user is permitted to make per minute
X-RateLimit-Remaining The number of requests remaining in the current rate limit window

Certain endpoints may have a rate custom rate limit defined which is specific to that endpoint

Requests to endpoints with custom rate limits do not count towards the global rate limit

Account

Get Your Account Information

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

Retrieves your account information

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/account" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/account"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/account'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/account',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": {
        "id": 2,
        "name": "frank28.203",
        "first_name": "Anna",
        "surname": "Adams",
        "role": "OWNER",
        "email": "kelly44@allen.co.uk",
        "address": "Flat 60\nKyle Lights",
        "postcode": "SP1 1NE",
        "country": "UNITED_KINGDOM",
        "telephone_number": "0738 286 7656",
        "timezone": "GMT",
        "standard_timezone": "Europe/London"
    }
}
                 

Request   

GET account

Get Account Information by ID

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

Retrieves the information of a specific account by its ID

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/account/1234" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/account/1234"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/account/1234'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/account/1234',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": {
        "id": 3,
        "name": "patel.joshua.941",
        "first_name": "Amy",
        "surname": "Owen",
        "role": "EXTERNAL",
        "email": "wright.dylan@clark.net",
        "address": "84 John Lake",
        "postcode": "AB22 8ZW",
        "country": "UNITED_KINGDOM",
        "telephone_number": "+44(0)0083 429653",
        "timezone": "GMT",
        "standard_timezone": "Europe/London"
    }
}
                 

Request   

GET account/{user_id}

URL Parameters

user_id   string  

The ID of the user.

Get Account Dongles by ID

requires authentication account type: engineer+ scopes: api:inverter:list, api:account:read

Retrieves a list of dongles for an account by its ID

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/account/qkunze/devices?page=1" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/account/qkunze/devices"
);

const params = {
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/account/qkunze/devices'
params = {
  'page': '1',
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/account/qkunze/devices',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": [
        {
            "serial_number": "49niih5fqc",
            "firmware_version": null,
            "type": "GPRS",
            "commission_date": "1997-07-21T09:43:01Z",
            "inverter": {
                "serial": "FC4716A325",
                "status": "NORMAL",
                "last_online": "2024-04-01T22:13:11Z",
                "last_updated": "2007-10-27T01:50:39Z",
                "commission_date": "1990-12-29T23:49:01Z",
                "info": {
                    "battery_type": "LITHIUM",
                    "battery": {
                        "nominal_capacity": 0,
                        "nominal_voltage": 0,
                        "depth_of_discharge": 0.8
                    },
                    "model": "Commercial EMS",
                    "max_charge_rate": 0
                },
                "warranty": {
                    "type": "Standard Legacy",
                    "expiry_date": "1995-12-29T23:49:01Z"
                },
                "firmware_version": {
                    "ARM": null,
                    "DSP": null
                },
                "connections": {
                    "batteries": []
                },
                "flags": []
            }
        },
        {
            "serial_number": "28sobz4oqi",
            "firmware_version": null,
            "type": "GPRS",
            "commission_date": "1996-01-17T23:27:53Z",
            "inverter": {
                "serial": "ED8493J072",
                "status": "LOST",
                "last_online": "2001-06-13T16:13:36Z",
                "last_updated": "1995-10-07T10:09:08Z",
                "commission_date": "1982-01-13T04:36:37Z",
                "info": {
                    "battery_type": "LITHIUM",
                    "battery": {
                        "nominal_capacity": 0,
                        "nominal_voltage": 0,
                        "depth_of_discharge": 1
                    },
                    "model": "Gateway",
                    "max_charge_rate": 0
                },
                "warranty": {
                    "type": "Standard Legacy",
                    "expiry_date": "1987-01-13T04:36:37Z"
                },
                "firmware_version": {
                    "ARM": 420,
                    "DSP": 426
                },
                "connections": {
                    "datalog": {
                        "serial_number": "28sobz4oqi",
                        "firmware_version": null,
                        "type": "GPRS",
                        "commission_date": "1996-01-17T23:27:53Z"
                    },
                    "batteries": []
                },
                "flags": []
            }
        }
    ]
}
                 

Request   

GET account/{user_username}/devices

paginated

URL Parameters

user_username   string  

The username of the user.

Query Parameters

page   integer optional  

Page number to return

pageSize   integer optional  

Number of items to return in a page. Defaults to 15

Get Account Information by Username

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

Retrieves the information of a specific account by its username

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/account/search/qkunze" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/account/search/qkunze"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/account/search/qkunze'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/account/search/qkunze',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": {
        "id": 18,
        "name": "lmartin.14",
        "first_name": "Jack",
        "surname": "Palmer",
        "role": "VIEWER",
        "email": "noah.phillips@rogers.biz",
        "address": "Flat 31\nKing Lake",
        "postcode": "AB11 5QE",
        "country": "UNITED_KINGDOM",
        "telephone_number": "(0064) 295 7686",
        "timezone": "GMT",
        "standard_timezone": "Europe/London"
    }
}
                 

Request   

GET account/search/{user_username}

URL Parameters

user_username   string  

The username of the user.

Get Your Account Children Information

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

Retrieves a list of accounts that your account has access to

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/account-children?page=1" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/account-children"
);

const params = {
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/account-children'
params = {
  'page': '1',
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/account-children',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": [
        {
            "id": 19,
            "name": "wright.dylan.123",
            "first_name": "Paul",
            "surname": "Edwards",
            "role": "SUB_CONTRACTOR",
            "email": "stephanie07@gmail.com",
            "address": "84 Alexandra Square",
            "postcode": "WS11 1ZY",
            "country": "UNITED_KINGDOM",
            "telephone_number": "04527298086",
            "timezone": "GMT",
            "standard_timezone": "Europe/London"
        },
        {
            "id": 20,
            "name": "michael37.776",
            "first_name": "Archie",
            "surname": "Jones",
            "role": "SUB_CONTRACTOR",
            "email": "jmorgan@gmail.com",
            "address": "39 Grace Ferry",
            "postcode": "LE4 4JR",
            "country": "UNITED_KINGDOM",
            "telephone_number": "0047 3552779",
            "timezone": "GMT -1",
            "standard_timezone": "Atlantic/Azores"
        }
    ]
}
                 

Request   

GET account-children

paginated

Query Parameters

page   integer optional  

Page number to return

pageSize   integer optional  

Number of items to return in a page. Defaults to 15

Get Account Children Information by ID

requires authentication account type: company+ scopes: api:account:read, api:account:list

Retrieves a list of accounts that the specified account has access to

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/account-children/1234?page=1" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/account-children/1234"
);

const params = {
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/account-children/1234'
params = {
  'page': '1',
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/account-children/1234',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": [
        {
            "id": 21,
            "name": "rose.phoebe.616",
            "first_name": "Jessica",
            "surname": "King",
            "role": "VIEWER",
            "email": "jackson.amy@owen.com",
            "address": "80 Collins Land",
            "postcode": "MK9 2AD",
            "country": "UNITED_KINGDOM",
            "telephone_number": "+44(0)316836121",
            "timezone": "GMT",
            "standard_timezone": "Europe/London"
        },
        {
            "id": 22,
            "name": "molly.watson.814",
            "first_name": "Isabelle",
            "surname": "Williams",
            "role": "OWNER",
            "email": "wilkinson.zach@smith.info",
            "address": "33 Sean Valley",
            "postcode": "TW15 3EQ",
            "country": "UNITED_KINGDOM",
            "telephone_number": "0975301722",
            "timezone": "GMT +6",
            "standard_timezone": "Asia/Qostanay"
        }
    ]
}
                 

Request   

GET account-children/{user_id}

paginated

URL Parameters

user_id   string  

The ID of the user.

Query Parameters

page   integer optional  

Page number to return

pageSize   integer optional  

Number of items to return in a page. Defaults to 15

Communication Device

Inverter Flags

When a communication device has an inverter present, the inverter will have a flags property. This is a list of strings that represent the flags that apply to that inverter. If a flag is not present in the array, it does not apply to that inverter.

{
    "serial_number": "COMMDEVICE",
    ...
    "inverter": {
        ...
        "flags": [
            "full-power-discharge-in-eco-mode",
            ...
        ]
    }
}

All currently available flags can be found in the below table:

Flag Description
full-power-discharge-in-eco-mode When present, the inverter will discharge the battery at full power during a scheduled DC discharge irrespective of the value of the Eco mode setting. If this flag is missing, Eco mode must be disabled for the battery to discharge at full power during a scheduled DC discharge

Get Your Communication Devices

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

View a collection of communication devices you have access to

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/communication-device?page=1" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/communication-device"
);

const params = {
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/communication-device'
params = {
  'page': '1',
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/communication-device',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": [
        {
            "serial_number": "WF2345G123",
            "type": "WIFI",
            "commission_date": "2021-01-01T00:00:00Z",
            "inverter": {
                "serial": "CE2345G123",
                "status": "WAITING",
                "last_online": "2023-01-01T00:00:00Z",
                "last_updated": "2023-01-01T00:00:00Z",
                "commission_date": "2021-01-01T00:00:00Z",
                "info": {
                    "battery_type": "LITHIUM",
                    "battery": {
                        "nominal_capacity": 110,
                        "nominal_voltage": 51.2
                    },
                    "model": "GIV-AC-3.0",
                    "max_charge_rate": 2560
                },
                "warranty": {
                    "type": "Standard",
                    "expiry_date": "2033-01-01T00:00:00Z"
                },
                "firmware_version": {
                    "ARM": 420,
                    "DSP": 426
                },
                "connections": {
                    "batteries": [
                        {
                            "module_number": 1,
                            "serial": "BB2345G123",
                            "firmware_version": "1035",
                            "capacity": {
                                "full": 110,
                                "design": 110
                            },
                            "cell_count": 16,
                            "has_usb": true,
                            "nominal_voltage": 51.2
                        }
                    ],
                    "meters": [
                        {
                            "address": 1,
                            "serial_number": 212345678,
                            "manufacturer_code": "0000",
                            "type_code": 1500,
                            "hardware_version": 1000,
                            "software_version": 1000,
                            "baud_rate": 9600
                        }
                    ]
                },
                "flags": []
            }
        }
    ]
}
                 

Request   

GET communication-device

paginated

Query Parameters

page   integer optional  

Page number to return

pageSize   integer optional  

Number of items to return in a page. Defaults to 15

Get Communication Device Information by Serial Number

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

Get a communication device's information by serial number

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/communication-device/consequatur" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/communication-device/consequatur"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/communication-device/consequatur'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/communication-device/consequatur',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": {
        "serial_number": "WF2345G123",
        "type": "WIFI",
        "commission_date": "2021-01-01T00:00:00Z",
        "inverter": {
            "serial": "CE2345G123",
            "status": "WAITING",
            "last_online": "2023-01-01T00:00:00Z",
            "last_updated": "2023-01-01T00:00:00Z",
            "commission_date": "2021-01-01T00:00:00Z",
            "info": {
                "battery_type": "LITHIUM",
                "battery": {
                    "nominal_capacity": 110,
                    "nominal_voltage": 51.2
                },
                "model": "GIV-AC-3.0",
                "max_charge_rate": 2560
            },
            "warranty": {
                "type": "Standard",
                "expiry_date": "2033-01-01T00:00:00Z"
            },
            "firmware_version": {
                "ARM": 420,
                "DSP": 426
            },
            "connections": {
                "batteries": [
                    {
                        "module_number": 1,
                        "serial": "BB2345G123",
                        "firmware_version": "1035",
                        "capacity": {
                            "full": 110,
                            "design": 110
                        },
                        "cell_count": 16,
                        "has_usb": true,
                        "nominal_voltage": 51.2
                    }
                ],
                "meters": [
                    {
                        "address": 1,
                        "serial_number": 212345678,
                        "manufacturer_code": "0000",
                        "type_code": 1500,
                        "hardware_version": 1000,
                        "software_version": 1000,
                        "baud_rate": 9600
                    }
                ]
            },
            "flags": []
        }
    }
}
                 

Request   

GET communication-device/{communicationDevice_serial_number}

URL Parameters

communicationDevice_serial_number   string  

The serial number of the communicationDevice.

EMS Data

Get Latest EMS System Data

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

Retrieves the latest system data from the EMS

EMS Status

The status of the EMS is returned with every EMS datapoint and indicates the operating status of the EMS. The status is an integer that can be one of the following values:

Status Description
0 WAITING
1 NORMAL
2 WARNING
3 ERROR
4 UPDATING
5 BYPASS

EMS Inverters

An array of inverters is returned with every EMS data point and contains the serial number, status, etc. of each connected inverter.

Inverter Statuses

The status of the given inverter is reported with every inverter and indicates the operating status of the inverter. The status is an integer that can be one of the following values:

Status Description
0 DISABLED
1 WAITING
2 ONLINE
3 WARNING
4 ERROR
5 FLASH
7 OFFLINE

EMS Meters

An array of meters is returned with every EMS data point and contains the type, status, etc. of each meter.

Meter Statuses

The status reported with every meter and indicates the operating status of the meter. The status is an integer that can be one of the following values:

Status Description
0 DISABLED
1 ONLINE
2 OFFLINE

Meter Types

The type is reported with every meter and indicates the operating type of meter. The type is an integer that can be one of the following values:

Type Description
0 GRID
1 GENERATION
2 LOAD
3 OTHER

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/ems/consequatur/system-data/latest" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/ems/consequatur/system-data/latest"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/ems/consequatur/system-data/latest'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/ems/consequatur/system-data/latest',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": {
        "battery_power": 9214,
        "battery_wh_remaining": 58276,
        "calculated_load_power": 15168,
        "car_power": -27828,
        "error_code": 40330,
        "grid_power": 16772,
        "measured_load_power": 19053,
        "status": 3,
        "time": null,
        "total_generation": 8035,
        "warning_code": 48384,
        "inverters": [
            {
                "active_power": -8597,
                "number": 1,
                "serial_number": "il6029p206",
                "soc": 88,
                "status": 4,
                "temperature": 3.2
            },
            {
                "active_power": -2221,
                "number": 2,
                "serial_number": "nl3168l361",
                "soc": 79,
                "status": 4,
                "temperature": 10.3
            },
            {
                "active_power": 24191,
                "number": 3,
                "serial_number": "uy0262d251",
                "soc": 43,
                "status": 2,
                "temperature": 28.4
            },
            {
                "active_power": null,
                "number": 4,
                "serial_number": null,
                "soc": null,
                "status": 0,
                "temperature": null
            }
        ],
        "meters": [
            {
                "active_power": null,
                "number": 1,
                "status": 0,
                "type": 0
            },
            {
                "active_power": null,
                "number": 2,
                "status": 2,
                "type": 1
            },
            {
                "active_power": null,
                "number": 3,
                "status": 0,
                "type": 3
            },
            {
                "active_power": null,
                "number": 4,
                "status": 2,
                "type": 2
            },
            {
                "active_power": null,
                "number": 5,
                "status": 0,
                "type": 0
            },
            {
                "active_power": null,
                "number": 6,
                "status": 0,
                "type": 0
            },
            {
                "active_power": null,
                "number": 7,
                "status": 0,
                "type": 0
            },
            {
                "active_power": null,
                "number": 8,
                "status": 0,
                "type": 0
            }
        ]
    }
}
                 

Request   

GET ems/{inverter_serial_number}/system-data/latest

URL Parameters

inverter_serial_number   string optional  

The serial number of the EMS

EV Charger

GivEnergy EV chargers follow version 1.6 of the Open Charge Point Protocol (OCPP 1.6).

Where applicable, EV Charger data returned by the API regarding will be transformed in such a way that it adheres to the OCPP 1.6 standard.

EV Charger Status

The below table is a complete list of all possible statuses that an OCPP 1.6 charger may report at any given time. Each charger may only report one status at once. Non- GivEnergy EV chargers will have their status (if applicable) normalised to an OCPP 1.6 status.

Status Description
Available The EV charger is not plugged in to a vehicle
Preparing The EV charger is plugged into a vehicle and is ready to start a charge
Charging The EV charger is charging the connected EV
SuspendedEVSE The charging session has been stopped by the EV charger
SuspendedEV The charging session has been stopped by the EV
Finishing The charging session has finished, but the EV charger isn't ready to start a new charging session
Reserved The EV charger has been reserved for a future charging session
Unavailable The EV charger cannot start new charging sessions
Faulted The EV charger is reporting an error

Info

Get Your EV Chargers

requires authentication account type: customer only scope: api:ev-charger:list

Return a list of EV chargers registered to your account

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/ev-charger?page=1" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/ev-charger"
);

const params = {
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/ev-charger'
params = {
  'page': '1',
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/ev-charger',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": [
        {
            "uuid": "ae6050fe-dfb0-497f-b59f-4b90d56766ef",
            "serial_number": "02622517580214",
            "type": "GivEnergy",
            "alias": "Garage",
            "online": false,
            "went_offline_at": null,
            "status": "Charging"
        },
        {
            "uuid": "306c6ee0-633b-4a09-82f7-6199152adee0",
            "serial_number": "96893553879883",
            "type": "GivEnergy",
            "alias": "EV Charger 1",
            "online": false,
            "went_offline_at": null,
            "status": "Unavailable"
        }
    ]
}
                 

Request   

GET ev-charger

paginated

Query Parameters

page   integer optional  

Page number to return

pageSize   integer optional  

Number of items to return in a page. Defaults to 15

Get EV Charger by UUID

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

Return information about a single EV charger by its UUID

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": {
        "uuid": "8bf66e82-4f1d-4ee9-9cc4-75da52bf15e7",
        "serial_number": "70458130637647",
        "type": "GivEnergy",
        "alias": "Garage",
        "online": false,
        "went_offline_at": null,
        "status": "Preparing"
    }
}
                 

Request   

GET ev-charger/{charger_uuid}

URL Parameters

charger_uuid   string  

The UUID of the charger.

Meter Data

Data Points

A 'data point' is a collection of sensor readings taken at a point in time from an EV charger's meter.

GivEnergy EV chargers typically capture one data point per meter per minute.

Meters

Each EV charger has 1 or more meters.

A 'meter' is a physical location where data is monitored.

GivEnergy EV chargers use the following meter IDs:

ID Name Information
0 EV Charger These readings are taken by the EV charger internally
1 Grid Meter These readings are taken by the EM115 meter monitoring the grid, if there is one installed
2 PV 1 Meter These readings are taken by the EM115 meter monitoring PV generation source 1, if there is one installed
3 PV 2 Meter These readings are taken by the EM115 meter monitoring PV generation source 2, if there is one installed

Each data point has at least 1 measurand.

Measurands

A 'measurand' is a reading taken from a certain sensor on the given meter. For example, measurand 13 (Power.Active.Import) is the amount of power that is currently being used by the EV charger to charge the vehicle.

The below table can be used to map the value returned from the API to something more meaningful;

Value Name Description
0 Current.Export Instantaneous current flow from EV
1 Current.Import Instantaneous current flow to EV
2 Current.Offered Maximum current offered to EV
3 Energy.Active.Export.Register Energy exported by EV (Wh or kWh)
4 Energy.Active.Import.Register Energy imported by EV (Wh or kWh)
5 Energy.Reactive.Export.Register Reactive energy exported by EV (varh or kvarh)
6 Energy.Reactive.Import.Register Reactive energy imported by EV (varh or kvarh)
7 Energy.Active.Export.Interval Energy exported by EV (Wh or kWh)
8 Energy.Active.Import.Interval Energy imported by EV (Wh or kWh)
9 Energy.Reactive.Export.Interval Reactive energy exported by EV. (varh or kvarh)
10 Energy.Reactive.Import.Interval Reactive energy imported by EV. (varh or kvarh)
11 Frequency Instantaneous reading of powerline frequency
12 Power.Active.Export Instantaneous active power exported by EV. (W or kW)
13 Power.Active.Import Instantaneous active power imported by EV. (W or kW)
14 Power.Factor Instantaneous power factor of total energy flow
15 Power.Offered Maximum power offered to EV
16 Power.Reactive.Export Instantaneous reactive power exported by EV. (var or kvar)
17 Power.Reactive.Import Instantaneous reactive power imported by EV. (var or kvar)
18 RPM Fan speed in RPM
19 SoC State of charge of charging vehicle in percentage
20 Temperature Temperature reading inside Charge Point.
21 Voltage Instantaneous AC RMS supply voltage

Each measurand may be accompanied by a unit of measure.

Units of measure

Each measurand has a maximum of 1 unit. The measurand does not necessarily have a unit of measure if the unit can be implied or is not needed, for example RPM.

The below table can be used to map the value returned from the API to something more meaningful:

Value Unit
0 Wh
1 kWh
2 varh
3 kvarh
4 W
5 kW
6 VA
7 kVA
8 var
9 kvar
10 A
11 V
12 Celsius
13 Fahrenheit
14 K
15 Percent

Get Data Points

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

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/meter-data?start_time=2023-06-01T00%3A00%3A00Z&end_time=2023-06-02T00%3A00%3A00Z&measurands[]=1&meter_ids[]=1&page=1" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/meter-data"
);

const params = {
    "start_time": "2023-06-01T00:00:00Z",
    "end_time": "2023-06-02T00:00:00Z",
    "measurands[0]": "1",
    "meter_ids[0]": "1",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/meter-data'
params = {
  'start_time': '2023-06-01T00:00:00Z',
  'end_time': '2023-06-02T00:00:00Z',
  'measurands[0]': '1',
  'meter_ids[0]': '1',
  'page': '1',
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/meter-data',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'start_time' => '2023-06-01T00:00:00Z',
            'end_time' => '2023-06-02T00:00:00Z',
            'measurands[0]' => '1',
            'meter_ids[0]' => '1',
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": [
        {
            "meter_id": 0,
            "timestamp": "2023-06-01 08:00:00",
            "measurements": [
                {
                    "measurand": 13,
                    "value": 1145,
                    "unit": 4
                },
                {
                    "measurand": 11,
                    "value": 50.2,
                    "unit": null
                },
                {
                    "measurand": 21,
                    "value": 230.5,
                    "unit": 11
                }
            ]
        }
    ]
}
                 

Request   

GET ev-charger/{charger_uuid}/meter-data

paginated

URL Parameters

charger_uuid   string  

The UUID of the charger.

Query Parameters

start_time   string  

The time of the earliest data point. Must be a valid date. Must be a date before now.

end_time   string  

The time of the latest data point. Must be a valid date. Must be a date after start_time.

measurands   string[]  

One or more measurands to filter by.

meter_ids   integer[]  

The IDs of the measuring devices to fetch data for.

page   integer optional  

Page number to return

pageSize   integer optional  

Number of items to return in a page. Defaults to 15

Commands

Commands

Below is a list of commands that may be sent to a charger. Some chargers may not support some commands based on hardware, firmware, software or other limitations. You can determine which commands may be sent to a specific charger by calling the Get EV Charger Commands endpoint

Each command is formatted in the following way:

command-id

(This replaces command_id in the request parameters)

A brief description of the command goes here

Request Data

This is a list of parameters that must be sent with this command

Command Data

This is the data that is stored against each command and is returned by the API. An example of this data can be found in the code example to the right of the page for each command.

A response value of null typically means that this command will never return data.

Command Data
{
    "type": "a description of this parameter can be found here"
}

start-charge

Instructs the charger to start charging

Request Data

This command requires no data

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
[]

stop-charge

Instructs the charger to stop charging

Request Data

This command requires no data

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
[]

adjust-charge-power-limit

Sets the maximum charge power

Request Data

limit   number  

Must be between 6 and 32.

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
{
    "min": "The minimum value that may be set",
    "max": "The maximum value that may be set",
    "value": "The value that is currently set",
    "unit": "The power limit unit. Can be either A or W"
}

set-plug-and-go

Determines if the charger should be in 'plug-and-go' mode, which is where the charger starts a charge as soon as a vehicle is connected, as long as the charger is communicating with the server

Request Data

enabled   boolean  

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
true

set-session-energy-limit

Configures the server to instruct the charger to stop charging if the charging session puts this much energy into the vehicle

Request Data

limit   number optional  

Must be between 0.1 and 250.

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
{
    "min": 0.1,
    "max": 1000,
    "value": 54.5,
    "unit": "kWh"
}

set-schedule

Create a new schedule. The newly created schedule is not yet active on the charger

Request Data

schedule_id   string optional  

name   string  

Must not be greater than 30 characters.

periods   string[]  

periods[].start_time   string  

Must be a valid date in the format H:i.

periods[].end_time   string  

Must be a valid date in the format H:i.

periods[].limit   number  

Must be between 6 and 32.

periods[].days   integer[]  

Must be at least 0. Must not be greater than 6.

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
{
    "schedules": [
        {
            "id": "The ID of the schedule",
            "name": "The name of the schedule",
            "is_active": "Whether this schedule is active on the charger",
            "periods": [
                {
                    "days": "An array of days of the week that this schedule period runs. From 0 (Monday) to 6 (Sunday)",
                    "start_time": "The start time of this interval formatted H:i",
                    "end_time": "The end time of this interval formatted H:i",
                    "limit": "The power limit of this period in Amps"
                }
            ]
        }
    ]
}

unlock-connector

Instructs the charger to unlock the plug from the vehicle. The vehicle may override this command

Request Data

This command requires no data

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
[]

delete-charging-profile

Delete one or all schedules from the charger

Request Data

schedule_id   string optional  

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
[]

change-mode

Changes the charger's current operating mode

EV Charger Modes

GivEnergy EV chargers have a set number of operational modes. The charger must have one and only one mode selected at all times

Mode information can be found in the table below:

ID Name Description
SuperEco Eco+ The vehicle will charge from excess solar only at a minimum of 6A (1.4kW)
Eco Eco The vehicle will charge at a minimum of 6A (1.4kW) from a combination of excess solar and grid power. If excess solar exceeds 6A (1.4kW), this will be diverted into the EV
Boost Boost The vehicle will charge from a combination of solar and grid up to the “Max Current” limit
ModbusSlave Inverter Control The vehicle will charge based upon instructions that it has been given by the GivEnergy Inverter

Any active schedule set on the charger will override the current mode. That is, if a schedule is set to start at 4PM, the charger will adhere to the current mode until 4PM then the schedule will start

Request Data

mode   string  

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
{
    "active": "The currently active mode ID",
    "available": "An array of IDs of modes that are available for this charger"
}

restart-charger

Sends a command to restart the charger immediately

Request Data

hard_reset   boolean optional  

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
[]

change-randomised-delay-duration

Sets the randomised delay function on the charger.

Due to government regulations, every EV charger that is capable of starting a charge based on some schedule must start the charge at some random number of seconds after the schedule was set to start. This is to alleviate strain on the grid caused by many chargers starting at once

More information can be found on the gov.uk website

Request Data

duration   number  

Must be at least 600. Must not be greater than 1800.

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
null

add-id-tags

Register one or more ID tags to the charger

Request Data

id_tags   string[]  

Must have at least 1 items.

id_tags[].id   string  

Must not be greater than 20 characters. Must be at least 1 character.

id_tags[].alias   string optional  

id_tags[].expiry_date   string optional  

Must be a valid date.

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
{
    "id_tags": [
        {
            "id": "The ID of the ID tag",
            "alias": "The alias of the ID tag. Can be null",
            "expiry_date": "The date that the ID tag will no longer work for this charger. Can be null",
            "created_at": "The date that the ID tag was registered to this charger"
        }
    ],
    "maximum_id_tags": "The maximum number of ID tags that may be registered to this charger"
}

delete-id-tags

Delete one or of the charger's registered ID tags

Request Data

id_tags   string[]  

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
null

rename-id-tag

Rename one of the charger's ID tags

Request Data

tag_id   string  

Must not be greater than 20 characters. Must be at least 1 character.

alias   string  

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
null

installation-mode

Deprecated

Update the charger's installation mode

Installation Modes

Notice
Installation modes are now handled in an enhanced way through the utilisation of the configuration-mode command. It is advised to refrain from using the installation-mode command, as it may lead to unintended side effects. Further information on configuration modes can be found in the dedicated section.

Each charger must specify an installation mode in order to change its operating mode. Typically the installation mode is specified during setup using the GivEnergy app, however it may also be changed via the portal or API. The installation mode may be changed at any time.

The installation mode describes which type of additional hardware the charger is connected to aid in operation or provide better functionality.

Each installation mode supports 1 or more operating modes.

GivEnergy EV chargers use the following installation modes:

ID Name Description Available Modes
standalone Standalone The charger works as a standalone unit with no additional monitoring devices Boost
ct_meter CT + Meter The charger is connected to at least 1x EM115 meter with CT clamp. One of these meters must monitor grid import and export Boost Eco EcoPlus
inverter_control Inverter Control The charger is connected to a GivEnergy inverter ModbusSlave

Request Data

installation_mode   string  

Must be one of standalone, ct_meter, or inverter_control.

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
"standalone"

setup-version

A description has not been provided for this command

Request Data

setup_version   integer  

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

A description has not been provided for this command's data

set-active-schedule

Set the charger's active schedule. If no schedule ID is provided the currently active schedule will be deactivated

Request Data

schedule_id   string optional  

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
{
    "schedule_id": "The ID of the currently active schedule, if there is one"
}

set-max-import-capacity

Set the maximum import capacity of the charger's main supply in amps

Request Data

value   integer optional  

Must be between 40 and 100.

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

A description has not been provided for this command's data

enable-front-panel-led

Turn the charger's front panel LED on or off

Request Data

value   boolean  

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

A description has not been provided for this command's data

configure-inverter-control

Configure the behaviour of the charger and inverter when in inverter control mode

Inverter Control

If a GivEnergy inverter is installed at the same location as a GivEnergy EV charger, the charger can be configured to work in tandem with the inverter to realise new features.

Right now, this behaviour is managed by the GivEnergy Cloud and requires that both the inverter and EV charger have a persistent internet connection. In the future we plan on having this behaviour managed by the inverter itself, which will allow the inverter and EV charger to work together even if the internet connection is lost and provides the added benefit of quick response times.

Benefits of using inverter control include:

To enable inverter control, you need to do the following:

Configuration Options

inverter_battery_export_split

This option controls how much of the excess solar generation is sent to the battery and how much is sent to the EV charger.

The default value for this option is 0.5 (50%).

Since the EV charger requires a minimum of 6A of export to charge, any export under 6A will be used to charge the battery.

Any export over 6A will be smartly split between the battery and the EV charger, attempting to meet your configured split percentage where possible.

If the total export power is greater than 6A, the charger will always charge at minimum 6A.

Please see the below table for some examples:

Export Power (A) Value Battery % EV % Battery Charge (A) EV Charger Charge (A)
6 0.5 50 50 0 6
12 0.5 50 50 6 6
9 0.5 50 50 3 6
12 0.75 75 25 6 6
5 0.1 10 90 5 0
32 0.9 90 10 26 6
32 0.8 80 20 25.6 6.4
32 0.1 10 90 3.2 28.8

max_battery_discharge_power_to_evc

This option controls the maximum power (in watts) that the GivEnergy battery may discharge to be used by the EV charger when solar is not generating.

The default value for this option is 0.

The battery will still discharge to cover other local demand where available.

mode

This option controls the operational mode of the EV charger.

The default value for this option is SuperEco.

Set a value of SuperEco to instruct the charger to only charge from excess solar at a minimum of 6A.

Set a value of Eco to instruct the charger to charge at a minimum of 6A, importing from the grid if there is 6A of excess solar available.

Set a value of Boost to prevent the battery from discharging beyond the max_battery_discharge_power_to_evc plus home demand value when the car is charging. Charges will need to be started manually by either using an RFID tag or the start-charge command.

Request Data

inverter_battery_export_split   string optional  

Must be at least 0 characters. Must not be greater than 1 character.

max_battery_discharge_power_to_evc   integer optional  

Must be at least 0.

mode   string optional  

Must be one of Eco, SuperEco, or Boost.

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
{
    "inverter_battery_export_split": 0,
    "max_battery_discharge_power_to_evc": 0,
    "mode": "SuperEco"
}

perform-factory-reset

Performs a factory reset on the charger

Request Data

This command requires no data

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
[]

configuration-mode

Change the configuration mode of the charger

Configuration Modes

Each charger must specify a configuration mode in order to change its operating mode. Typically the configuration mode is specified during setup using the GivEnergy app, however it may also be changed via the portal or API. The configuration mode may be changed at any time.

The configuration mode describes which (if any) additional hardware is installed alongside the EV charger to aid in operation or provide better functionality.

Each configuration mode supports 1 or more operating modes.

GivEnergy EV chargers use the following configuration modes:

ID Name Description Available Modes
A Standalone EVC installed with internet connectivity & mains supply only Boost
B Standalone With PV EVC installed with internet connectivity & mains supply only, with third party solar inverter and no meters Boost
C CT Meter EVC installed with internet connectivity, mains supply, wired comms cable & compatible meter Boost, Eco, SuperEco
D Inverter Control Cloud EVC installed with internet connectivity, mains supply & compatible GivEnergy PV inverter associated with the same GivEnergy cloud account ModbusSlave
E Inverter Control Local (coming soon) EVC installed with internet connectivity, mains supply & compatible GivEnergy PV inverter wired into charger comms port ModbusSlave

Request Data

configuration_mode   string  

Must be one of A, B, C, D, or E.

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

Command Data
{
    "value": "The value of current configuration mode of the charger"
}

enable-local-control

Enable or disable local Modbus control on the charger

Request Data

value   boolean  

Command Data

A description of the command data can be found to the right. A concrete example may be found in the endpoint details further down this document

A description has not been provided for this command's data

Send Command Response

When sending a command to the charger, the response will typically be formatted as per the code example found below:

Where code is one of the following:

Value Code Description
0 SUCCESS The command was sent successfully
-1 TIMEOUT The charger did not respond to the command in time
-2 CHARGER_OFFLINE The charger did not receive the request because it was offline
-3 INVALID_DATA The charger did not receive the request because the data was invalid
-4 FAILURE The charger actioned the request but did not respond as expected
-5 ERROR There was a error with either the server or charger at some point between sending the request and receiving the response

success is a boolean that indicates whether or not the request was successful.

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

Error Response

If the response code received is ERROR (-5), additional data will be sent with the response. The content of the data will be different depending on if it was the server or the charger that experienced the error.

Charger Error

The charger has indicated that it encountered a problem with either its hardware or firmware and could not process the request as expected. error.code will be present in the response data and will be one of the following values:

Code Description
NotImplemented The charger could not recognise this type of request
NotSupported The charger could not handle this type of request
InternalError The charger experienced an internal error whilst processing the request
ProtocolError The charger could not handle the request because the request data was incomplete
SecurityError The charger could not handle the request because of an internal security issue
FormationViolation The charger could not handle the request because the request data was not structured correctly
PropertyConstraintViolation The charger could not handle the request because one or more fields on the data contained an invalid value
OccurenceConstraintViolation The charger could not handle the request because one or more fields on the data contained a value which violates occurrence constraints
TypeConstraintViolation The charger could not handle the request because one or more fields on the data contained a value which was the wrong type
GenericError An error occurred which is not covered by the other error codes

These error codes are specified in the OCPP1.6 protocol.

The response may also include data which is extra data returned by the EV Charger that may be useful to diagnose the cause of the error and prevent it from happening again.

{
    "code": -5,
    "success": false,
    "message": "CallError",
    "error": {
        "code": "NotImplemented",
        "type": "Error",
        "message": "This charger does not implement this request"
    },
    "data": {
        "extra": "extra information would be here"
    }
}

Server Error

The server has encountered a problem when sending the request or processing the response. These errors will be picked up by our internal monitoring but should be reported if possible

{
    "code": -5,
    "success": false,
    "message": "Error",
    "error": {
        "type": "Error",
        "message": "There was an error on the server"
    }
}

Get Supported Commands

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

Fetch a list of all commands that are supported for the given EV charger

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

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

Request   

GET ev-charger/{charger_uuid}/commands

URL Parameters

charger_uuid   string  

The UUID of the charger.

Get Command Data

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

Fetch the current data for the given command and EV Charger

The below response example is for the change-mode command

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands/setup-version" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands/setup-version"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands/setup-version'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands/setup-version',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

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

Request   

GET ev-charger/{charger_uuid}/commands/{command_id}

URL Parameters

charger_uuid   string  

The UUID of the charger.

command_id   string  

The ID of the command.

Send Command

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

dynamically validated

Send a command to an EV Charger

Example request:
curl --request POST \
    "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands/setup-version" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands/setup-version"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands/setup-version'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/commands/setup-version',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

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

Request   

POST ev-charger/{charger_uuid}/commands/{command_id}

URL Parameters

charger_uuid   string  

The UUID of the charger.

command_id   string  

The ID of the command.

Charging Sessions

A 'charging session' or 'transaction' is a single charge of a vehicle. A session starts when the vehicle starts to charge, whether it has been done locally using an ID tag, remotely using the portal, app, or API or automatically by using plug and go or inverter control.

Each charging session contains the following information:

Key Description Type Optional?
started_by The ID tag used to start the charge string No
meter_start The kWh reading of the import meter when this session started float No
started_at The date and time that the session started datetime No
stopped_by The ID tag used to stop the charge. string Yes
meter_stop The kWh reading of the import meter when this session stopped float Yes
stopped_at The date and time that the session stopped datetime Yes
stop_reason The reason that this session stopped. See Stop Reasons for more information string Yes

Optional fields will be null if the session has not been stopped.

Stop Reasons

When a charging session is stopped, the stop_reason field will be populated with one of the following values to indicate why the session was stopped:

Reason Description
EmergencyStop The emergency stop button was pressed
EVDisconnected The charging cable was disconnected from the EV
HardReset A hard reset command was received
Local An RFID tag was used to stop the charging session
Other Other
PowerLoss The charger experienced a complete loss of power
Reboot A locally initiated reboot occurred
Remote The charging session was stopped remotely
SoftReset A soft reset command was received
UnlockCommand An unlock connector command was received
DeAuthorized The charging session was not authorised to start

ID Tags

Starting a Session

When a session is started, the ID tag used to start the session is logged. The ID tag value is different depending on how the session was started:

If the session is started locally using a physical ID tag, this will be the ID tag number which can be found on the tag itself.

If the session is started by a user using the app, API or portal, the value will be their user ID.

If the session is started by plug and go, the value will be PLUG_AND_GO.

If the session is started by inverter control, the value will be INVERTER_CONTROL.

Ending a session

When a session is ended, the same rules as above apply. If the session is stopped locally by the charger or EV (for example if the EV is unplugged), the ID tag value will be the same as the one used to start the session.

Get Charging Sessions

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

Fetch a list of all charging sessions for the given EV charger

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/charging-sessions?page=1" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"start_time\": \"2019-02-02\",
    \"end_time\": \"2105-11-05\"
}"
const url = new URL(
    "https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/charging-sessions"
);

const params = {
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "start_time": "2019-02-02",
    "end_time": "2105-11-05"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/charging-sessions'
payload = {
    "start_time": "2019-02-02",
    "end_time": "2105-11-05"
}
params = {
  'page': '1',
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, json=payload, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/ev-charger/66529e01-d113-3473-8d6f-9e11e09332ea/charging-sessions',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'page' => '1',
        ],
        'json' => [
            'start_time' => '2019-02-02',
            'end_time' => '2105-11-05',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": [
        {
            "started_by": "9f42852",
            "meter_start": 933.4,
            "started_at": "2000-07-04T09:03:34Z",
            "stopped_by": null,
            "meter_stop": null,
            "stopped_at": null,
            "stop_reason": null
        },
        {
            "started_by": "54bd6d5",
            "meter_start": 1423.7,
            "started_at": "1981-02-09T18:02:07Z",
            "stopped_by": null,
            "meter_stop": null,
            "stopped_at": null,
            "stop_reason": null
        }
    ]
}
                 

Request   

GET ev-charger/{charger_uuid}/charging-sessions

paginated

URL Parameters

charger_uuid   string  

The UUID of the charger.

Query Parameters

page   integer optional  

Page number to return

pageSize   integer optional  

Number of items to return in a page. Defaults to 15

Body Parameters

start_time   string optional  

Must be a valid date. Must be a date before or equal to end_time.

end_time   string optional  

Must be a valid date. Must be a date after or equal to start_time.

Energy Flow Data

Get Energy Flow Data

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

Grouping IDs

Grouping ID Name Description
0 Half Hourly Groups the data into 30-minute intervals
1 Daily Groups the data into 24-hour intervals
2 Monthly Groups the data into monthly intervals
3 Yearly Groups the data into yearly intervals
4 Total Groups the data into a single interval, spanning from the start time to the end time

Type IDs

Type ID Name Description
0 PV to Home The amount of energy generated by the solar panels to be used immediately for local consumption
1 PV to Battery The amount of energy generated by the solar panels that has been used to charge the battery
2 PV to Grid The amount of energy generated by the solar panels that has been exported to the grid
3 Grid to Home The amount of energy imported from the grid that has been used immediately for local consumption
4 Grid to Battery The amount of energy imported from the grid that has been used to charge the battery
5 Battery to Home The amount of energy discharged by the battery that has been used for local consumption
6 Battery to Grid The amount of energy discharged by the battery that has been exported to the grid

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

Example request:
curl --request POST \
    "https://api.givenergy.cloud/v1/inverter/CE1234G567/energy-flows" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"start_time\": \"2022-01-01\",
    \"end_time\": \"2022-01-01\",
    \"grouping\": 0,
    \"types\": [
        0,
        1,
        2,
        5
    ]
}"
const url = new URL(
    "https://api.givenergy.cloud/v1/inverter/CE1234G567/energy-flows"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "start_time": "2022-01-01",
    "end_time": "2022-01-01",
    "grouping": 0,
    "types": [
        0,
        1,
        2,
        5
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/energy-flows'
payload = {
    "start_time": "2022-01-01",
    "end_time": "2022-01-01",
    "grouping": 0,
    "types": [
        0,
        1,
        2,
        5
    ]
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://api.givenergy.cloud/v1/inverter/CE1234G567/energy-flows',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'start_time' => '2022-01-01',
            'end_time' => '2022-01-01',
            'grouping' => 0,
            'types' => [
                0,
                1,
                2,
                5,
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
     "data": [
         "start_time": "2022-01-01 00:00",
         "end_time": "2022-01-01 00:30",
         "data": [
             "0": 4.5,
             "1": 8.3,
             "2": 1.2,
             "5": 7.3
         ],
         ...
     ]
 }
                 

Request   

POST inverter/{inverter_serial_number}/energy-flows

URL Parameters

inverter_serial_number   string  

The serial number of the inverter.

Body Parameters

start_time   datetime  

The start time of the query. Based on the inverter's local time

end_time   datetime  

The end time of the query. Based on the inverter's local time

grouping   integer  

The way in which to group the data. See the above table for a complete list of grouping IDs

types   integer[] optional  

An array of type IDs. See the above table for a complete list of type IDs. Leave blank to fetch all types

Response

Response Fields

data   object[]  

The response data

data[].start_time   datetime  

The start time of that energy flow record

data[].end_time   datetime  

The end time of that energy flow record

data[].data   object  

An object where the property is the type and the value is the amount of energy for that period in Kilowatt-Hours (kWh). For example, { "0": 1, "4": 2 } means type 0 (PV to Home) has a value of 1 and type 4 (Grid to Battery) has a value of 2. The value has a maximum precision of 2 decimal places

Inverter Control

Presets

Get Setting Presets

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

Retrieves a list of available setting presets for a given inverter

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/inverter/CE1234G567/presets" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/inverter/CE1234G567/presets"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/presets'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/inverter/CE1234G567/presets',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
     "data": [
         {
             "id": 0,
             "name": "Eco",
             "description": "This mode will dynamically charge and discharge your batteries to minimise your import from the grid",
             "parameters": {
                 "enabled": {
                     "description": "Enable or disable the preset",
                     "validation": [
                         "required",
                         "boolean"
                     ]
                 }
             }
         },
         ...
     ]
}
                 

Request   

GET inverter/{inverter_serial_number}/presets

URL Parameters

inverter_serial_number   string  

The serial number of the inverter.

Modify Preset

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

dynamically validated

Modify one or more inverter settings using a given preset

Example request:
curl --request POST \
    "https://api.givenergy.cloud/v1/inverter/CE1234G567/presets/consequatur" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/inverter/CE1234G567/presets/consequatur"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/presets/consequatur'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://api.givenergy.cloud/v1/inverter/CE1234G567/presets/consequatur',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

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

Request   

POST inverter/{inverter_serial_number}/presets/{preset}

URL Parameters

inverter_serial_number   string  

The serial number of the inverter.

preset   string  

The preset.

Single

Get Settings List

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

Returns a set of inverter settings available to your account

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/inverter/CE1234G567/settings" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/inverter/CE1234G567/settings"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/settings'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/inverter/CE1234G567/settings',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": [
        {
            "id": 266,
            "name": "DC Discharge 3 End Time",
            "validation": "Value format should be HH:mm. Use correct time range for hour and minutes",
            "validation_rules": [
                "date_format:H:i"
            ]
        }
    ]
}
                 

Request   

GET inverter/{inverter_serial_number}/settings

URL Parameters

inverter_serial_number   string  

The serial number of the inverter.

Read Setting

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

Read a specific setting on the inverter

Example request:
curl --request POST \
    "https://api.givenergy.cloud/v1/inverter/CE1234G567/settings/17/read" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"context\": \"consequatur\"
}"
const url = new URL(
    "https://api.givenergy.cloud/v1/inverter/CE1234G567/settings/17/read"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "context": "consequatur"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/settings/17/read'
payload = {
    "context": "consequatur"
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://api.givenergy.cloud/v1/inverter/CE1234G567/settings/17/read',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'context' => 'consequatur',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

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

Request   

POST inverter/{inverter_serial_number}/settings/{setting_id}/read

URL Parameters

inverter_serial_number   string  

The serial number of the inverter.

setting_id   integer  

The ID of the setting.

Body Parameters

context   string optional  

Additional context to record against this command. Appears on the remote control history in 'via'

Modify Setting

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

Write a value to the setting on the inverter

Example request:
curl --request POST \
    "https://api.givenergy.cloud/v1/inverter/CE1234G567/settings/17/write" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"value\": \"consequatur\",
    \"context\": \"consequatur\"
}"
const url = new URL(
    "https://api.givenergy.cloud/v1/inverter/CE1234G567/settings/17/write"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "value": "consequatur",
    "context": "consequatur"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/settings/17/write'
payload = {
    "value": "consequatur",
    "context": "consequatur"
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://api.givenergy.cloud/v1/inverter/CE1234G567/settings/17/write',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'value' => 'consequatur',
            'context' => 'consequatur',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

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

Request   

POST inverter/{inverter_serial_number}/settings/{setting_id}/write

URL Parameters

inverter_serial_number   string  

The serial number of the inverter.

setting_id   integer  

The ID of the setting.

Body Parameters

value   mixed  

The value of the setting

context   string optional  

Additional context to record against this command. Appears on the remote control history in 'via'

Multiple

Modify Setting (Multiple)

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

Write a value to a setting on multiple inverters

Example request:
curl --request POST \
    "https://api.givenergy.cloud/v1/multi-control/write" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"inverter_serials\": [
        \"SERIAL_1\",
        \"SERIAL_2\"
    ],
    \"setting_id\": 17,
    \"value\": \"1\"
}"
const url = new URL(
    "https://api.givenergy.cloud/v1/multi-control/write"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "inverter_serials": [
        "SERIAL_1",
        "SERIAL_2"
    ],
    "setting_id": 17,
    "value": "1"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/multi-control/write'
payload = {
    "inverter_serials": [
        "SERIAL_1",
        "SERIAL_2"
    ],
    "setting_id": 17,
    "value": "1"
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://api.givenergy.cloud/v1/multi-control/write',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'inverter_serials' => [
                'SERIAL_1',
                'SERIAL_2',
            ],
            'setting_id' => 17,
            'value' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

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

Request   

POST multi-control/write

Body Parameters

inverter_serials   string[]  

An array of inverter serial numbers to send the command to with a maximum length of 1000

setting_id   integer  

The ID of the setting to modify

value   mixed  

The value of the setting

Read Setting (Multiple)

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

Read a specific setting on multiple inverters

Example request:
curl --request POST \
    "https://api.givenergy.cloud/v1/multi-control/read" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"inverter_serials\": [
        \"SERIAL_1\",
        \"SERIAL_2\"
    ],
    \"setting_id\": 17
}"
const url = new URL(
    "https://api.givenergy.cloud/v1/multi-control/read"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "inverter_serials": [
        "SERIAL_1",
        "SERIAL_2"
    ],
    "setting_id": 17
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/multi-control/read'
payload = {
    "inverter_serials": [
        "SERIAL_1",
        "SERIAL_2"
    ],
    "setting_id": 17
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://api.givenergy.cloud/v1/multi-control/read',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'inverter_serials' => [
                'SERIAL_1',
                'SERIAL_2',
            ],
            'setting_id' => 17,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

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

Request   

POST multi-control/read

Body Parameters

inverter_serials   string[]  

An array of inverter serial numbers to send the command to with a maximum length of 1000

setting_id   integer  

The ID of the setting to modify

Inverter Data

Inverter Statuses

The status of the given inverter is reported with every data point and indicates the operating status of the inverter. The status is a string that can be one of the following values:

Status Description
NORMAL The inverter is operating normally and is processing an amount power
WAITING The inverter is operating normally and is not processing any power
LOST The inverter is offline
UNKNOWN The inverter has recently connected to the GivEnergy platform and has not yet updated its status
ERROR The inverter is reporting one or more faults. Its performance will be impacted
WARNING The inverter is reporting one or more warnings. Its performance may not be impacted
UPDATING The inverter is currently updating its firmware
BYPASS The inverter is currently in bypass mode

Request Inverter Data

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

approved users only

Sends a command to the inverter to force it to persist a data point

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/inverter/CE1234G567/request-data" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/inverter/CE1234G567/request-data"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/request-data'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/inverter/CE1234G567/request-data',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (success):

                                        
                    {
    "success": true
}
                 

Example response (failure):

                                        
                    {
    "success": false
}
                 

Request   

GET inverter/{inverter_serial_number}/request-data

URL Parameters

inverter_serial_number   string  

The serial number of the inverter.

Get Latest System Data

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

Retrieves the latest system data from the inverter

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/inverter/CE1234G567/system-data/latest" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/inverter/CE1234G567/system-data/latest"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/system-data/latest'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/inverter/CE1234G567/system-data/latest',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": {
        "time": "2006-10-31T23:16:07Z",
        "status": "Normal",
        "solar": {
            "power": 1526,
            "arrays": [
                {
                    "array": 1,
                    "voltage": 369.8,
                    "current": 918.5,
                    "power": 881
                },
                {
                    "array": 2,
                    "voltage": 413.1,
                    "current": 654.2,
                    "power": 563
                }
            ]
        },
        "grid": {
            "voltage": 2155.3,
            "current": -4688.5,
            "power": -3270,
            "frequency": 259.5
        },
        "battery": {
            "percent": 83,
            "power": -2484,
            "temperature": 85
        },
        "inverter": {
            "temperature": 80,
            "power": 37241,
            "output_voltage": 222.1,
            "output_frequency": 49.28,
            "eps_power": 224
        },
        "consumption": 38674
    }
}
                 

Request   

GET inverter/{inverter_serial_number}/system-data/latest

URL Parameters

inverter_serial_number   string  

The serial number of the inverter.

Get Latest Meter Data

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

Retrieves the latest meter data from the inverter

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/inverter/CE1234G567/meter-data/latest" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/inverter/CE1234G567/meter-data/latest"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/meter-data/latest'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/inverter/CE1234G567/meter-data/latest',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": {
        "time": "1992-08-15T14:35:09Z",
        "today": {
            "solar": 5690.3,
            "grid": {
                "import": 9880.9,
                "export": 4294.6
            },
            "battery": {
                "charge": 91852.3,
                "discharge": 65419.6
            },
            "consumption": 938.6,
            "ac_charge": 30996.9
        },
        "total": {
            "solar": 57462.4,
            "grid": {
                "import": 184.9,
                "export": 5659
            },
            "battery": {
                "charge": 8763.7,
                "discharge": 8763.7
            },
            "consumption": 66779,
            "ac_charge": 26925.1
        },
        "is_metered": true
    }
}
                 

Request   

GET inverter/{inverter_serial_number}/meter-data/latest

URL Parameters

inverter_serial_number   string  

The serial number of the inverter.

Get Events

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

Retrieves a list of faults that were triggered from the inverter and when they were cleared

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/inverter/CE1234G567/events?start=consequatur&end=consequatur&cleared=&page=1" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"cleared\": false,
    \"start\": \"2019-02-03\",
    \"end\": \"2105-11-05\"
}"
const url = new URL(
    "https://api.givenergy.cloud/v1/inverter/CE1234G567/events"
);

const params = {
    "start": "consequatur",
    "end": "consequatur",
    "cleared": "0",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "cleared": false,
    "start": "2019-02-03",
    "end": "2105-11-05"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/events'
payload = {
    "cleared": false,
    "start": "2019-02-03",
    "end": "2105-11-05"
}
params = {
  'start': 'consequatur',
  'end': 'consequatur',
  'cleared': '0',
  'page': '1',
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, json=payload, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/inverter/CE1234G567/events',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'start' => 'consequatur',
            'end' => 'consequatur',
            'cleared' => '0',
            'page' => '1',
        ],
        'json' => [
            'cleared' => false,
            'start' => '2019-02-03',
            'end' => '2105-11-05',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": [
        {
            "event": "Parallel communication failure",
            "start_time": "2004-01-27T07:53:39Z",
            "end_time": null
        },
        {
            "event": "Inverter Current Fault",
            "start_time": "1996-04-23T02:23:48Z",
            "end_time": null
        }
    ]
}
                 

Request   

GET inverter/{inverter_serial_number}/events

paginated

URL Parameters

inverter_serial_number   string  

The serial number of the inverter.

Query Parameters

start   string optional  

ISO8601-datetime Start time

end   string optional  

ISO8601-datetime End time

cleared   boolean optional  

Whether 'cleared' events should be included with the data. Default is false

page   integer optional  

Page number to return

pageSize   integer optional  

Number of items to return in a page. Defaults to 15

Body Parameters

cleared   boolean optional  

start   string optional  

Must be a valid date. Must be a date before tomorrow.

end   string optional  

Must be a valid date. Must be a date after start.

Get Data Points

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

Inverter Data Point Schema

Data Point

Field Description Unit Type
time Timestamp data point was reported - ISO8601-datetime
status Status of the inverter - string
power See power data section below - -
today See today/total data section below - -
total See today/total data section below - -
is_metered Whether the data point includes readings from the grid meter - boolean

Power Data

Field Description Unit Type
solar See solar power section below - -
grid See grid power section below - -
battery See battery data section below - -
consumption See consumption data section below - -
inverter See inverter data section below - -

Solar Power

Field Description Unit Type
power Total solar power generated W integer
arrays List of solar arrays providing power, see solar arrays section below - SolarArray[]

Solar Arrays

Field Description Unit Type
array Array number - integer
voltage Solar array voltage V decimal,1
current Solar array current A decimal,1
power Power being generated by the solar array W integer

Grid Power

Field Description Unit Type
voltage Grid voltage V decimal,1
current Grid current A decimal,1
power Power supplied from(-)/to(+) the grid W integer
frequency Grid frequency Hz decimal,2

Battery Data

Field Description Unit Type
percent Battery percentage % integer
power Power charging(-)/discharging(+) from the battery W integer
temperature Battery temperature °C decimal,1

Consumption Data

Field Description Unit Type
power Power consumed by the site W integer

Inverter Data

Field Description Unit Type
temperature Inverter temperature °C decimal,1
power Power output/input from the inverter W integer
output_voltage Inverter voltage V decimal,1
output_frequency Inverter frequency Hz decimal,2
eps_power EPS power (emergency power supply) W integer

Today/Total Data

Field Description Unit Type
solar PV generation energy today/total kWh decimal,1
grid See grid section below - -
battery See battery section - -
consumption Power consumption today/total kWh decimal,1
ac_charge AC charge energy today/total kWh decimal,1

Grid

Field Description Unit Type
import Grid import energy today/total kWh decimal,1
export Grid export energy today/total kWh decimal,1

Battery

Field Description Unit Type
charge Battery charge today/total kWh decimal,1
discharge Battery discharge today/total kWh decimal,1

Displays the entire data packet set from the chosen date

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/inverter/CE1234G567/data-points/consequatur?page=1" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/inverter/CE1234G567/data-points/consequatur"
);

const params = {
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/inverter/CE1234G567/data-points/consequatur'
params = {
  'page': '1',
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/inverter/CE1234G567/data-points/consequatur',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": [
        {
            "time": "1997-02-19T03:53:16Z",
            "status": "LOST",
            "power": {
                "solar": {
                    "power": 4703,
                    "arrays": [
                        {
                            "array": 1,
                            "voltage": 198.6,
                            "current": 3.3,
                            "power": 491
                        },
                        {
                            "array": 2,
                            "voltage": 170.8,
                            "current": 10,
                            "power": 2806
                        }
                    ]
                },
                "grid": {
                    "voltage": 128.3,
                    "current": 98.1,
                    "power": 19821,
                    "frequency": 49.25
                },
                "battery": {
                    "percent": 79,
                    "power": -2289,
                    "temperature": 12
                },
                "consumption": {
                    "power": 22636
                },
                "inverter": {
                    "temperature": 50,
                    "power": -9476,
                    "output_voltage": 144.7,
                    "output_frequency": 49.69,
                    "eps_power": 24672
                }
            },
            "today": {
                "solar": 4373.9,
                "grid": {
                    "import": 3168.4,
                    "export": 5384.4
                },
                "battery": {
                    "charge": 8691.3,
                    "discharge": 4350.4
                },
                "consumption": 5673.7,
                "ac_charge": 8021.5
            },
            "total": {
                "solar": 4353.3,
                "grid": {
                    "import": 4625.8,
                    "export": 7045.8
                },
                "battery": {
                    "charge": 1034.1,
                    "discharge": 1034.1
                },
                "consumption": 7757.1,
                "ac_charge": 9568.8
            },
            "is_metered": true
        },
        {
            "time": "2013-10-23T04:13:45Z",
            "status": "UNKNOWN",
            "power": {
                "solar": {
                    "power": 3748,
                    "arrays": [
                        {
                            "array": 1,
                            "voltage": 439.3,
                            "current": 0.5,
                            "power": 3339
                        },
                        {
                            "array": 2,
                            "voltage": 26.9,
                            "current": 9.9,
                            "power": 3324
                        }
                    ]
                },
                "grid": {
                    "voltage": 66.5,
                    "current": 77.6,
                    "power": 20120,
                    "frequency": 49.75
                },
                "battery": {
                    "percent": 60,
                    "power": 799,
                    "temperature": 50.1
                },
                "consumption": {
                    "power": 47610
                },
                "inverter": {
                    "temperature": 29.3,
                    "power": -7702,
                    "output_voltage": 167.6,
                    "output_frequency": 49.01,
                    "eps_power": 21174
                }
            },
            "today": {
                "solar": 452,
                "grid": {
                    "import": 9389.9,
                    "export": 1836.2
                },
                "battery": {
                    "charge": 6270.8,
                    "discharge": 5510.6
                },
                "consumption": 9864.4,
                "ac_charge": 4178.8
            },
            "total": {
                "solar": 4574.4,
                "grid": {
                    "import": 6372.2,
                    "export": 3627.8
                },
                "battery": {
                    "charge": 15.7,
                    "discharge": 15.7
                },
                "consumption": 3788.9,
                "ac_charge": 300.3
            },
            "is_metered": true
        }
    ]
}
                 

Request   

GET inverter/{inverter_serial_number}/data-points/{date}

paginated

URL Parameters

inverter_serial_number   string  

The serial number of the inverter.

date   string optional  

ISO8601-date required The date to fetch the data. This assumes the date at the system's local time

Query Parameters

page   integer optional  

Page number to return

pageSize   integer optional  

Number of items to return in a page. Defaults to 15

Notifications

Notification Platform

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

Platform Description
persist Persists a notification to the user's notifications center in the portal and mobile app
push Sends a push notification to all devices that the user is logged in to on the mobile app

Send Notification

requires authentication account type: any scope: api:notification:send rate limited: 10,60

Sends a notification to your account on the specified platforms

A failure indicates that the notification could not be sent to one or more of the specified platforms

To help prevent misuse of this endpoint, the values of body and title must meet the following requirements:

As this endpoint is used and user behaviour patterns are analyzed, the validation rules may change over time without warning to keep users safe. If modifications to this endpoint's validation rules are made, this endpoint's documentation will be updated and details of the change will be included in the changelog found at the bottom of this document

To help users identify the origin of notifications sent via this endpoint, a message will be included at the end of the notification body that either states the name of the third-party application that sent the notification or the name of the token used, whichever is applicable

Users and third-party applications found to be abusing this endpoint will have their API access revoked

Example request:
curl --request POST \
    "https://api.givenergy.cloud/v1/notification/send" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"platforms\": [
        \"persist\"
    ],
    \"title\": \"Something amazing has happened!\",
    \"body\": \"Here is some information about the amazing thing that has happened\",
    \"icon\": \"mdi-account-outline\"
}"
const url = new URL(
    "https://api.givenergy.cloud/v1/notification/send"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "platforms": [
        "persist"
    ],
    "title": "Something amazing has happened!",
    "body": "Here is some information about the amazing thing that has happened",
    "icon": "mdi-account-outline"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/notification/send'
payload = {
    "platforms": [
        "persist"
    ],
    "title": "Something amazing has happened!",
    "body": "Here is some information about the amazing thing that has happened",
    "icon": "mdi-account-outline"
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://api.givenergy.cloud/v1/notification/send',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'platforms' => [
                'persist',
            ],
            'title' => 'Something amazing has happened!',
            'body' => 'Here is some information about the amazing thing that has happened',
            'icon' => 'mdi-account-outline',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (success):

                                        
                    {
    "success": true
}
                 

Example response (failure):

                                        
                    {
    "success": false
}
                 

Request   

POST notification/send

Body Parameters

platforms   string[]  

One or more platforms to send the notification to.

title   string  

Title of the notification. Must meet the API requirements for notification content. Must be at least 10 characters.

body   string  

Body of the notification. Must meet the API requirements for notification content. Must be at least 20 characters.

icon   string  

The notification's icon. Must be a valid material design icon prefixed with mdi-. Must start with one of mdi-.

Site

Get Your Sites

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

Retrieves a list of your sites

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/site?page=1" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/site"
);

const params = {
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/site'
params = {
  'page': '1',
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/site',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": [
        {
            "id": 7,
            "name": "Jeremy Hill",
            "account": "yreynolds.814",
            "date_created": "1988-02-17",
            "country": "FAROE_IS",
            "timezone": "GMT",
            "tz_timezone": "Europe/Astrakhan",
            "latitude": 79.284177,
            "longitude": 1.10994,
            "type": "SINGLE_PHASE",
            "products": []
        },
        {
            "id": 8,
            "name": "Heather Thompson",
            "account": "anderson.ian.503",
            "date_created": "2018-07-16",
            "country": "TOKELAU",
            "timezone": "GMT",
            "tz_timezone": "Atlantic/South_Georgia",
            "latitude": -52.674876,
            "longitude": -141.434346,
            "type": "SINGLE_HYBIRD",
            "products": []
        }
    ]
}
                 

Request   

GET site

paginated

Query Parameters

page   integer optional  

Page number to return

pageSize   integer optional  

Number of items to return in a page. Defaults to 15

Get Single Site by ID

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

Gather a single site's information

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/site/17" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/site/17"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/site/17'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/site/17',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

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

Request   

GET site/{site_plant_id}

URL Parameters

site_plant_id   integer  

The ID of the site plant.

Site Status

Site Status

The site's status indicates if the site is occupied and if they have opted in to any available schemes.

If the site status is null, it is assumed that this site is not part of any scheme.

Status Description
vacant Vacant
opted_in Opted In
opted_out Opted Out

Get Site Status

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

approved users only

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/site/17/status" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/site/17/status"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/site/17/status'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/site/17/status',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "status": "vacant"
}
                 

Request   

GET site/{site_plant_id}/status

URL Parameters

site_plant_id   integer  

The ID of the site plant.

Update Site Status

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

approved users only

Update the status of a site. Provide a status of null to delete the status.

Modifying the site status will automatically perform any modifications to any hardware on that site as required.

Example request:
curl --request POST \
    "https://api.givenergy.cloud/v1/site/17/status" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
const url = new URL(
    "https://api.givenergy.cloud/v1/site/17/status"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/site/17/status'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://api.givenergy.cloud/v1/site/17/status',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "success": true
}
                 

Request   

POST site/{site_plant_id}/status

URL Parameters

site_plant_id   integer  

The ID of the site plant.

Body Parameters

status   string optional  

Smart Device

Device

Get Your Smart Devices

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

List the smart devices registered to your account

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/smart-device?page=1" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/smart-device"
);

const params = {
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/smart-device'
params = {
  'page': '1',
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/smart-device',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": [
        {
            "uuid": "48a8d332-c5e8-40d4-82e8-f82f645ba669",
            "alias": "veniam",
            "other_data": {
                "graph_color": "#f0c27c",
                "hardware_id": "P",
                "local_key": "J"
            }
        },
        {
            "uuid": "a642da10-7e0f-4bdb-8d52-9954ddb3415e",
            "alias": "ea",
            "other_data": {
                "graph_color": "#6e7655",
                "hardware_id": "p",
                "local_key": "!"
            }
        }
    ]
}
                 

Request   

GET smart-device

paginated

Query Parameters

page   integer optional  

Page number to return

pageSize   integer optional  

Number of items to return in a page. Defaults to 15

Create Smart Device

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

Register a new smart device to your account

Example request:
curl --request POST \
    "https://api.givenergy.cloud/v1/smart-device" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"serial_number\": \"consequatur\",
    \"alias\": \"consequatur\",
    \"product_name\": \"consequatur\",
    \"manufacturer\": \"consequatur\",
    \"other_data\": []
}"
const url = new URL(
    "https://api.givenergy.cloud/v1/smart-device"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "serial_number": "consequatur",
    "alias": "consequatur",
    "product_name": "consequatur",
    "manufacturer": "consequatur",
    "other_data": []
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/smart-device'
payload = {
    "serial_number": "consequatur",
    "alias": "consequatur",
    "product_name": "consequatur",
    "manufacturer": "consequatur",
    "other_data": []
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://api.givenergy.cloud/v1/smart-device',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'serial_number' => 'consequatur',
            'alias' => 'consequatur',
            'product_name' => 'consequatur',
            'manufacturer' => 'consequatur',
            'other_data' => [],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": [
        {
            "uuid": "5f774acf-c1f8-4397-8ab8-11f0f7591f95",
            "alias": "iste",
            "other_data": {
                "graph_color": "#22c331",
                "hardware_id": "e",
                "local_key": "/"
            }
        },
        {
            "uuid": "a8a72437-e91e-40b9-9962-7eba1094630c",
            "alias": "ut",
            "other_data": {
                "graph_color": "#913ee5",
                "hardware_id": "#",
                "local_key": "l"
            }
        }
    ]
}
                 

Request   

POST smart-device

Body Parameters

serial_number   string  

The serial number of the smart device.

alias   string optional  

An alternate name for the smart device.

product_name   string optional  

The model name of the product.

manufacturer   string optional  

The name of the product's manufacturer.

other_data   object optional  

Get Smart Device by ID

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

Get a smart device's information

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea'
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": [
        {
            "uuid": "dc9fa757-190c-4916-a5f9-a34ffd1e7c1d",
            "alias": "veniam",
            "other_data": {
                "graph_color": "#f0c27c",
                "hardware_id": "P",
                "local_key": "J"
            }
        },
        {
            "uuid": "49aa4fdd-b9ec-4244-957a-890653cbe6fa",
            "alias": "sit",
            "other_data": {
                "graph_color": "#ea2f1a",
                "hardware_id": "Z",
                "local_key": "<"
            }
        }
    ]
}
                 

Request   

GET smart-device/{smartDevice_uuid}

URL Parameters

smartDevice_uuid   string  

The UUID of the smartDevice.

Data

Get Smart Device Data Points by ID

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

Get a list of a smart device's data points

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea/data?page=1" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea/data"
);

const params = {
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea/data'
params = {
  'page': '1',
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers, params=params)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea/data',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'page' => '1',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": [
        {
            "time": "1987-03-13T13:05:30Z",
            "power": 509
        },
        {
            "time": "2020-02-06T18:59:47Z",
            "power": 884
        }
    ]
}
                 

Request   

GET smart-device/{smartDevice_uuid}/data

paginated

URL Parameters

smartDevice_uuid   string  

The UUID of the smartDevice.

Query Parameters

page   integer optional  

Page number to return

pageSize   integer optional  

Number of items to return in a page. Defaults to 15

Create Smart Device Data Point

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

Store a data point against a smart device

Example request:
curl --request POST \
    "https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea/data" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"time\": \"consequatur\",
    \"power\": 17
}"
const url = new URL(
    "https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea/data"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "time": "consequatur",
    "power": 17
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
import requests
import json

url = 'https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea/data'
payload = {
    "time": "consequatur",
    "power": 17
}
headers = {
  'Authorization': 'Bearer {YOUR_API_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://api.givenergy.cloud/v1/smart-device/66529e01-d113-3473-8d6f-9e11e09332ea/data',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'time' => 'consequatur',
            'power' => 17,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):

                                        
                    {
    "data": [
        {
            "time": "1980-03-23T05:34:16Z",
            "power": 622
        },
        {
            "time": "1971-06-09T14:15:47Z",
            "power": 567
        }
    ]
}
                 

Request   

POST smart-device/{smartDevice_uuid}/data

URL Parameters

smartDevice_uuid   string  

The UUID of the smartDevice.

Body Parameters

time   ISO8601-datetime  

The date & time that the data point was created

power   integer  

Changelog

v1.27.0 (2024-09-30)

v1.26.0 (2024-09-10)

v1.25.0 (2024-05-29)

v1.24.0 (2024-05-01)

v1.23.0 (2024-04-25)

v1.22.0 (2024-03-25)

v1.21.0 (2024-03-05)

v1.20.0 (2024-02-28)

v1.19.0 (2024/01/03)

v1.18.0 (2023-12-06)

v1.17.0 (2023-11-23)

v1.16.0 (2023-11-15)

v1.15.0 (2023-11-10)

v1.14.0 (2023-11-06)

v1.13.0 (2023-10-11)

v1.12.0 (2023-08-15)

v1.11.0 (2023-06-09)

v1.10.2 (2023-05-12)

v1.10.1 (2022-12-06)

v1.10.0 (2022-11-23)

v1.9.3 (2022-09-26)

v1.9.2 (2022-07-11)

v1.9.1 (2022-07-06)

v1.9.0 (2022-06-27)

v1.8.0 (2022-05-09)

v1.7.0 (2022-05-03)

v1.6.0 (2022-04-19)

v1.5.2 (2022-04-04)

v1.5.1 (2022-03-08)

v1.5.0 (2022-03-08)

v1.4.1 (2022-03-08)

v1.4.0 (2022-03-04)

v1.3.1 (2022-03-03)

v1.3.0 (2022-03-02)

v1.2.0 (2022-02-28)

v1.1.0 (2022-02-24)

v1.0.0 (2022-02-21)

Initial Release