MENU navbar-image

Introduction

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

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 retrieve your token by visiting Account Settings and clicking Generate in the 'GivEnergy API Key' section

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
requires account permission Your account must be able to do this to use this API endpoint
account type: account Your account must be at least this type to use this API endpoint
requires authentication You must provide a valid API key to use this API endpoint
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

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)

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 Key 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 Too many attempts
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

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

Account

Get Your Account Information

requires authentication   account type: any

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": 496,
        "name": "francesca.holmes",
        "role": "ENGINEER",
        "email": "joshua94@martin.com",
        "address": "Flat 60\nKyle Lights",
        "country": "SOUTH_KOREA",
        "telephone_number": "0738 286 7656",
        "timezone": "GMT +13"
    }
}
 

Request      

GET account

Get Account Information by ID

requires authentication   account type: engineer+   requires account read permission

Retrieves the information of a specific account by its ID

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/account/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/account/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/account/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/account/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": 496,
        "name": "lewis.campbell",
        "role": "OWNER",
        "email": "adam98@yahoo.com",
        "address": "56 Edwards Glen",
        "country": "SLOVAKIA",
        "telephone_number": "(0075) 381 2360",
        "timezone": "GMT -9"
    }
}
 

Request      

GET account/{id}

URL Parameters

id  integer  

The ID of the account.

Get Account Dongles by ID

requires authentication   account type: engineer+   requires account read permission

Retrieves a list of dongles for an account by its ID

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/account/consequatur/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/consequatur/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/consequatur/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/consequatur/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",
            "type": "GPRS",
            "commission_date": "1996-05-10T19:25:12Z",
            "inverter": {
                "serial": "nf0901b951",
                "status": "NORMAL",
                "last_online": "2002-06-13T10:34:03Z",
                "last_updated": "2011-01-31T10:52:07Z",
                "commission_date": "2016-01-31T15:58:59Z",
                "info": {
                    "battery_type": "LITHIUM",
                    "model": "Giv-HY5.0"
                },
                "warranty": {
                    "type": "Standard",
                    "expiry_date": "2021-01-31T15:58:59Z"
                },
                "firmware_version": {
                    "ARM": 420,
                    "DSP": 426
                },
                "connections": []
            }
        },
        {
            "serial_number": "02mlnf4nge",
            "type": "GPRS",
            "commission_date": "1979-04-21T15:56:42Z",
            "inverter": {
                "serial": "iw7734l833",
                "status": "WARNING",
                "last_online": "1998-12-12T05:04:42Z",
                "last_updated": "2008-05-12T13:34:57Z",
                "commission_date": "2002-07-19T02:13:10Z",
                "info": {
                    "battery_type": "LITHIUM",
                    "model": "Giv-HY3.6"
                },
                "warranty": {
                    "type": "Standard",
                    "expiry_date": "2007-07-19T02:13:10Z"
                },
                "firmware_version": {
                    "ARM": 420,
                    "DSP": 426
                },
                "connections": []
            }
        }
    ]
}
 

Request      

GET account/{account_id}/devices

paginated

URL Parameters

account_id  string  

The ID of the account.

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+

Retrieves the information of a specific account by its username

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/account/search/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/account/search/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/account/search/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/account/search/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": {
        "id": 496,
        "name": "kelly44",
        "role": "ADMIN",
        "email": "hall.noah@gmail.co.uk",
        "address": "Flat 31\nKing Lake",
        "country": "TONGA",
        "telephone_number": "(0064) 295 7686",
        "timezone": "GMT +4"
    }
}
 

Request      

GET account/search/{account_user_account}

URL Parameters

account_user_account  string  

The username of the account

Get Your Account Children Information

requires authentication   account type: engineer+   requires account read permission

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": 496,
            "name": "rose.phoebe",
            "role": "OWNER",
            "email": "adams.scott@gmail.com",
            "address": "80 Collins Land",
            "country": "CANARY_ISLANDS",
            "telephone_number": "+44(0)316836121",
            "timezone": "GMT -4"
        },
        {
            "id": 497,
            "name": "owen67",
            "role": "VIEWER",
            "email": "arthur94@gmail.com",
            "address": "33 Sean Valley",
            "country": "PARAGUAY",
            "telephone_number": "+44(0)4011 038979",
            "timezone": "GMT +9"
        }
    ]
}
 

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+   requires account read permission

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/17?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/17"
);

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/17'
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/17',
    [
        '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": 496,
            "name": "anna00",
            "role": "ENGINEER",
            "email": "owen.jack@gmail.co.uk",
            "address": "57 James Spring",
            "country": "DJIBOUTI",
            "telephone_number": "08691 273874",
            "timezone": "GMT +8"
        },
        {
            "id": 497,
            "name": "jmorgan",
            "role": "ADMIN",
            "email": "young.natalie@gmail.com",
            "address": "84 Palmer Forks",
            "country": "CAYMAN_ISLANDS",
            "telephone_number": "0958994135",
            "timezone": "GMT -4"
        }
    ]
}
 

Request      

GET account-children/{account}

paginated

URL Parameters

account  integer  

The ID of the account

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

Get Your Communication Devices

requires authentication   account type: any

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": "56ynla1zgh",
            "type": "WIFI",
            "commission_date": "2003-07-25T09:25:33Z",
            "inverter": {
                "serial": "uz5509s157",
                "status": "WAITING",
                "last_online": "2021-05-02T07:09:27Z",
                "last_updated": "2006-02-24T08:20:38Z",
                "commission_date": "2006-07-04T14:45:00Z",
                "info": {
                    "battery_type": "LEAD_ACID",
                    "model": "Giv-AC3.0"
                },
                "warranty": {
                    "type": "Standard",
                    "expiry_date": "2011-07-04T14:45:00Z"
                },
                "firmware_version": {
                    "ARM": 420,
                    "DSP": 426
                },
                "connections": []
            }
        },
        {
            "serial_number": "96bdta5bpt",
            "type": "GPRS",
            "commission_date": "2019-10-25T08:06:09Z",
            "inverter": {
                "serial": "ba7322q046",
                "status": "ERROR",
                "last_online": "1998-01-25T09:29:41Z",
                "last_updated": "2004-03-01T11:39:36Z",
                "commission_date": "2019-11-20T20:25:38Z",
                "info": {
                    "battery_type": "LEAD_ACID",
                    "model": "Giv-HY3.6"
                },
                "warranty": {
                    "type": "Standard",
                    "expiry_date": "2024-11-20T20:25:38Z"
                },
                "firmware_version": {
                    "ARM": 420,
                    "DSP": 426
                },
                "connections": []
            }
        }
    ]
}
 

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

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": "12tqtq2xba",
        "type": "WIFI",
        "commission_date": "1973-05-15T08:08:53Z",
        "inverter": {
            "serial": "iw8795x985",
            "status": "NORMAL",
            "last_online": "2021-11-24T05:22:06Z",
            "last_updated": "2006-03-06T18:17:06Z",
            "commission_date": "1990-01-31T07:41:25Z",
            "info": {
                "battery_type": "LITHIUM",
                "model": "Giv-AC3.0"
            },
            "warranty": {
                "type": "Standard",
                "expiry_date": "1995-01-31T07:41:25Z"
            },
            "firmware_version": {
                "ARM": 420,
                "DSP": 426
            },
            "connections": []
        }
    }
}
 

Request      

GET communication-device/{id}

URL Parameters

id  string  

The serial number of the communication device

Energy Flow Data

Get Energy Flow Data

requires authentication   account type: any   requires inverter read permission

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

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
Example request:
curl --request POST \
    "https://api.givenergy.cloud/v1/inverter/consequatur/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/consequatur/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/consequatur/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/consequatur/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_id}/energy-flows

URL Parameters

inverter_id  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

Get Setting Presets

requires authentication   account type: any

Retrieves a list of available setting presets for a given inverter

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/inverter/consequatur/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/consequatur/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/consequatur/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/consequatur/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}/presets

URL Parameters

inverter  string  

The serial number of the inverter

Modify Preset

requires authentication   account type: any

dynamically validated

Modify one or more inverter settings using a given preset

Example request:
curl --request POST \
    "https://api.givenergy.cloud/v1/inverter/consequatur/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/consequatur/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/consequatur/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/consequatur/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}/presets/{id}

URL Parameters

inverter  string  

The serial number of the inverter

id  string  

The preset ID

Get Settings List

requires authentication   account type: any   requires inverter read permission

Returns a set of inverter settings available to your account

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/inverter/consequatur/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/consequatur/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/consequatur/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/consequatur/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": 101,
        "name": "Inverter Max Output Reactive Power Percent"
    }
}
 

Request      

GET inverter/{inverter}/settings

URL Parameters

inverter  string  

The serial number of the inverter

Read Setting

requires authentication   account type: any   requires inverter read permission   requires setting permission

Read a specific setting on the inverter

Example request:
curl --request POST \
    "https://api.givenergy.cloud/v1/inverter/consequatur/settings/1/read" \
    --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/consequatur/settings/1/read"
);

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/consequatur/settings/1/read'
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/consequatur/settings/1/read',
    [
        '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": {
        "value": true
    }
}
 

Request      

POST inverter/{inverter}/settings/{setting}/read

URL Parameters

inverter  string  

The serial number of the inverter

setting  integer  

Modify Setting

requires authentication   account type: any   requires inverter read permission   requires setting permission

Write a value to the setting on the inverter

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

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

let body = {
    "value": "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/consequatur/settings/1/write'
payload = {
    "value": "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/consequatur/settings/1/write',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'value' => 'consequatur',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


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

Request      

POST inverter/{inverter}/settings/{setting}/write

URL Parameters

inverter  string  

The serial number of the inverter

setting  integer  

Body Parameters

value  mixed  

The value of the setting

Modify Setting (Multiple)

requires authentication   account type: any   requires inverter read permission   requires setting permission

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

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   requires inverter read permission   requires setting permission

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

setting_id  integer  

The ID of the setting to modify

Inverter Data

Get Latest System Data

requires authentication   account type: any   requires inverter read permission

Retrieves the latest system data from the inverter

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/inverter/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/inverter/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/inverter/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/inverter/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": {
        "time": "1984-12-01T13:11:55Z",
        "solar": {
            "power": 3761.9,
            "arrays": [
                {
                    "array": 1,
                    "voltage": 202.9,
                    "current": 788.7,
                    "power": 98.3
                },
                {
                    "array": 2,
                    "voltage": 626.5,
                    "current": 206.8,
                    "power": 561.2
                }
            ]
        },
        "grid": {
            "voltage": 1509.2,
            "current": 4814,
            "power": -4862.3,
            "frequency": 221.3
        },
        "battery": {
            "percent": 65,
            "power": 1344,
            "temperature": 7524065.5
        },
        "inverter": {
            "temperature": 32577.4,
            "power": 86477,
            "output_voltage": 148.8,
            "output_frequency": 13756748.86,
            "eps_power": 4741
        },
        "consumption": 36915
    }
}
 

Request      

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

URL Parameters

inverter  string  

The serial number of the inverter

Get Latest Meter Data

requires authentication   account type: any   requires inverter read permission

Retrieves the latest meter data from the inverter

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/inverter/consequatur/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/consequatur/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/consequatur/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/consequatur/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": "2009-04-10T00:03:00Z",
        "today": {
            "solar": 9389.9,
            "grid": {
                "import": 6983,
                "export": 70.8
            },
            "battery": {
                "charge": 18361.5,
                "discharge": 4519.6
            },
            "consumption": 16302.1
        },
        "total": {
            "solar": 61741.4,
            "grid": {
                "import": 88996.3,
                "export": 60066.2
            },
            "battery": {
                "charge": 32605.3,
                "discharge": 32605.3
            },
            "consumption": 70135.5
        }
    }
}
 

Request      

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

URL Parameters

inverter  string  

The serial number of the inverter

Get Events

requires authentication   account type: any   requires inverter read permission

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/consequatur/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\": \"2016-09-18\",
    \"end\": \"2103-06-22\"
}"
const url = new URL(
    "https://api.givenergy.cloud/v1/inverter/consequatur/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": "2016-09-18",
    "end": "2103-06-22"
};

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

url = 'https://api.givenergy.cloud/v1/inverter/consequatur/events'
payload = {
    "cleared": false,
    "start": "2016-09-18",
    "end": "2103-06-22"
}
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/consequatur/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' => '2016-09-18',
            'end' => '2103-06-22',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

Example response (200):


{
    "data": [
        {
            "event": "BMS Discharger Over Current",
            "start_time": "2002-08-05T08:30:47Z",
            "end_time": null
        },
        {
            "event": "lightning protection fault",
            "start_time": "1987-05-10T09:46:57Z",
            "end_time": null
        }
    ]
}
 

Request      

GET inverter/{inverter}/events

paginated

URL Parameters

inverter  string  

The serial number of the inverter

Query Parameters

start  ISO8601-datetime optional  

Start time

end  ISO8601-datetime optional  

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   requires inverter read permission

Displays the entire data packet set from the chosen date

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/inverter/consequatur/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/consequatur/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/consequatur/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/consequatur/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": "1995-12-16T12:14:26Z",
            "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": -7116,
                    "output_voltage": 144.7,
                    "output_frequency": 49.69,
                    "eps_power": 24672
                }
            },
            "today": {
                "solar": 43739.3,
                "grid": {
                    "import": 31683.6,
                    "export": 53843.5
                },
                "battery": {
                    "charge": 86912.7,
                    "discharge": 43503.9
                },
                "consumption": 56736.6
            },
            "total": {
                "solar": 43533.2,
                "grid": {
                    "import": 46257.7,
                    "export": 70458.1
                },
                "battery": {
                    "charge": 10340.8,
                    "discharge": 10340.8
                },
                "consumption": -119054
            }
        },
        {
            "time": "2008-01-27T09:28:24Z",
            "power": {
                "solar": {
                    "power": 4669,
                    "arrays": [
                        {
                            "array": 1,
                            "voltage": 327.2,
                            "current": 14.7,
                            "power": 3162
                        },
                        {
                            "array": 2,
                            "voltage": 467.5,
                            "current": 9.6,
                            "power": 3517
                        }
                    ]
                },
                "grid": {
                    "voltage": 38.6,
                    "current": 23.4,
                    "power": 10138,
                    "frequency": 50.85
                },
                "battery": {
                    "percent": 0,
                    "power": 1147,
                    "temperature": -9.1
                },
                "consumption": {
                    "power": 1557
                },
                "inverter": {
                    "temperature": 3.3,
                    "power": 37241,
                    "output_voltage": 124.6,
                    "output_frequency": 49.35,
                    "eps_power": 42873
                }
            },
            "today": {
                "solar": 31754.7,
                "grid": {
                    "import": 82575.2,
                    "export": 77348.3
                },
                "battery": {
                    "charge": 43720.1,
                    "discharge": 17527.4
                },
                "consumption": 98808.7
            },
            "total": {
                "solar": 87637.7,
                "grid": {
                    "import": 56903.5,
                    "export": 91852.3
                },
                "battery": {
                    "charge": 1357,
                    "discharge": 1357
                },
                "consumption": -78689.5
            }
        }
    ]
}
 

Request      

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

paginated

URL Parameters

inverter  string  

The serial number of the inverter

date  ISO8601-date  

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

Site

Get Your Sites

requires authentication   account type: any

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": 149,
            "name": "Jeremy Hill",
            "account": "amy.owen",
            "date_created": "1987-05-06",
            "country": "GEORGIA",
            "timezone": "GMT",
            "latitude": 79.284177,
            "longitude": 1.10994,
            "products": []
        },
        {
            "id": 150,
            "name": "Amelia Young",
            "account": "emma.king",
            "date_created": "2012-12-02",
            "country": "THAILAND",
            "timezone": "GMT",
            "latitude": -17.801298,
            "longitude": 171.10862,
            "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   requires site read permission

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": 149,
        "name": "Jeremy Hill",
        "account": "kyle.lewis",
        "date_created": "1987-05-06",
        "country": "GEORGIA",
        "timezone": "GMT",
        "latitude": 79.284177,
        "longitude": 1.10994,
        "products": []
    }
}
 

Request      

GET site/{id}

URL Parameters

id  integer  

The ID of the site.

Smart Device

Get Your Smart Devices

requires authentication   account type: any

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": "5afc382f-50ec-4450-8292-0a3e6832207b",
            "alias": "veniam",
            "other_data": []
        },
        {
            "uuid": "4d80dd49-4c78-45ec-b132-eb534d69123d",
            "alias": "laudantium",
            "other_data": []
        }
    ]
}
 

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

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": "04c6ce6c-a78d-4705-a48e-7db6874f40fa",
            "alias": "iste",
            "other_data": []
        },
        {
            "uuid": "6fd94efc-fe5e-4132-93db-1f1e7fc21016",
            "alias": "debitis",
            "other_data": []
        }
    ]
}
 

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

Get a smart device's information

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/smart-device/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/smart-device/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/smart-device/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/smart-device/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": [
        {
            "uuid": "a4c0c2d0-bf8a-4c69-a48f-6e1620594ba5",
            "alias": "veniam",
            "other_data": []
        },
        {
            "uuid": "16b7176c-1299-4483-9bf8-fa6324f80e2a",
            "alias": "nihil",
            "other_data": []
        }
    ]
}
 

Request      

GET smart-device/{id}

URL Parameters

id  integer  

The ID of the smart device.

Get Smart Device Data Points by ID

requires authentication   account type: any

Get a list of a smart device's data points

Example request:
curl --request GET \
    --get "https://api.givenergy.cloud/v1/smart-device/consequatur/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/consequatur/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/consequatur/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/consequatur/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": "1986-06-14T01:36:48Z",
            "power": 495
        },
        {
            "time": "2017-12-04T21:47:10Z",
            "power": 402
        }
    ]
}
 

Request      

GET smart-device/{smart-device_id}/data

paginated

URL Parameters

smart-device_id  string  

The ID of the smart-device.

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

Store a data point against a smart device

Example request:
curl --request POST \
    "https://api.givenergy.cloud/v1/smart-device/consequatur/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/consequatur/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/consequatur/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/consequatur/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": "1979-10-13T05:23:05Z",
            "power": 498
        },
        {
            "time": "1973-05-15T08:08:53Z",
            "power": 369
        }
    ]
}
 

Request      

POST smart-device/{smart_device_uuid}/data

URL Parameters

smart_device_uuid  string  

Body Parameters

time  ISO8601-datetime  

The date & time that the data point was created

power  integer  

Changelog

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