As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile) You can switch the language used with the tabs at the top right (or from the nav menu at the top left on mobile).
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.
https://api.givenergy.cloud/v1To authenticate requests, include an Authorization header with the value "Bearer "
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
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
| 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 |
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
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//data-points/ where an inverter serial number must replace and an ISO8601-date must replace 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
Most endpoints provide simple validation rules in the URL parameters , Query Parameters or Body 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
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
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 |
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 |
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 |
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
The example response data is randomly generated and is not indicative of any actual values returned by the API
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
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:
Receiving an error response code does not always mean that the device did not process the request. When modifying a setting, if a response code marked as potentially successful (see below) is returned, you should either send the command again or read the same setting on the device to confirm if the command was successful
| 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 |
| 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 |
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 |
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 >>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
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 " \ --header "Content-Type: application/json" \ --header "Accept: application/json"const url = new URL( "https://api.givenergy.cloud/v1/account" ); const headers = < "Authorization": "Bearer ", "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 ', '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 ', 'Content-Type' => 'application/json', 'Accept' => 'application/json', ], ] ); $body = $response->getBody(); print_r(json_decode((string) $body));Received response :
Request failed with error:
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 " \ --header "Content-Type: application/json" \ --header "Accept: application/json"const url = new URL( "https://api.givenergy.cloud/v1/account/1234" ); const headers = < "Authorization": "Bearer ", "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 ', '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 ', 'Content-Type' => 'application/json', 'Accept' => 'application/json', ], ] ); $body = $response->getBody(); print_r(json_decode((string) $body));Received response :
Request failed with error:
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 " \ --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 ", "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 ', '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 ', 'Content-Type' => 'application/json', 'Accept' => 'application/json', ], 'query' => [ 'page' => '1', ], ] ); $body = $response->getBody(); print_r(json_decode((string) $body));< "data": [ < "serial_number": "49niih5fqc", "firmware_version": null, "type": "GPRS", "commission_date": "1997-07-07T23:44:24Z", "inverter": < "serial": "BA2061Q787", "status": "ERROR", "last_online": "2022-12-30T05:26:03Z", "last_updated": "2019-08-01T13:58:47Z", "commission_date": "1972-12-12T05:21:56Z", "info": < "battery_type": "LITHIUM", "battery": < "nominal_capacity": 52, "nominal_voltage": 307.2, "depth_of_discharge": 0.85 >, "model": "GIV-HV-8.0-G3", "max_charge_rate": 6000 >, "warranty": < "type": "Standard Legacy", "expiry_date": "1977-12-12T05:21:56Z" >, "firmware_version": < "ARM": 420, "DSP": 426 >, "connections": < "batteries": [] >, "flags": [] > >, < "serial_number": "14jsne0awg", "firmware_version": null, "type": "WIFI", "commission_date": "2015-03-01T20:59:15Z", "inverter": < "serial": "NF8687R802", "status": "LOST", "last_online": "1996-04-10T14:56:40Z", "last_updated": "2023-10-13T15:40:33Z", "commission_date": "1992-12-21T02:09:09Z", "info": < "battery_type": "LITHIUM", "battery": < "nominal_capacity": 52, "nominal_voltage": 307.2, "depth_of_discharge": 0.85 >, "model": "AIO-HY-6.0", "max_charge_rate": 6000 >, "warranty": < "type": "Standard Legacy", "expiry_date": "1997-12-21T02:09:09Z" >, "firmware_version": < "ARM": 420, "DSP": 426 >, "connections": < "batteries": [] >, "flags": [] > > ] > Received response :
Request failed with error:
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 " \ --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 ", "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 ', '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 ', 'Content-Type' => 'application/json', 'Accept' => 'application/json', ], ] ); $body = $response->getBody(); print_r(json_decode((string) $body));Received response :
Request failed with error:
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 " \ --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 ", "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 ', '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 ', 'Content-Type' => 'application/json', 'Accept' => 'application/json', ], 'query' => [ 'page' => '1', ], ] ); $body = $response->getBody(); print_r(json_decode((string) $body));Received response :
Request failed with error:
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 " \ --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 ", "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 ', '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 ', 'Content-Type' => 'application/json', 'Accept' => 'application/json', ], 'query' => [ 'page' => '1', ], ] ); $body = $response->getBody(); print_r(json_decode((string) $body));Received response :
Request failed with error:
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.
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 |
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 " \ --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 ", "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 ', '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 ', 'Content-Type' => 'application/json', 'Accept' => 'application/json', ], 'query' => [ 'page' => '1', ], ] ); $body = $response->getBody(); print_r(json_decode((string) $body));< "data": [ < "serial_number": "WF2345G123", "type": "WIFI", "commission_date": "2021-01-01T00:00:00Z", "inverter": < "serial": "CE2345G123", "status": "WAITING", "last_online": "2023-01-01T00:00:00Z", "last_updated": "2023-01-01T00:00:00Z", "commission_date": "2021-01-01T00:00:00Z", "info": < "battery_type": "LITHIUM", "battery": < "nominal_capacity": 110, "nominal_voltage": 51.2 >, "model": "GIV-AC-3.0", "max_charge_rate": 2560 >, "warranty": < "type": "Standard", "expiry_date": "2033-01-01T00:00:00Z" >, "firmware_version": < "ARM": 420, "DSP": 426 >, "connections": < "batteries": [ < "module_number": 1, "serial": "BB2345G123", "firmware_version": "1035", "capacity": < "full": 110, "design": 110 >, "cell_count": 16, "has_usb": true, "nominal_voltage": 51.2 > ], "meters": [ < "address": 1, "serial_number": 212345678, "manufacturer_code": "0000", "type_code": 1500, "hardware_version": 1000, "software_version": 1000, "baud_rate": 9600 >] >, "flags": [] > > ] > Received response :
Request failed with error:
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 " \ --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 ", "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 ', '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 ', 'Content-Type' => 'application/json', 'Accept' => 'application/json', ], ] ); $body = $response->getBody(); print_r(json_decode((string) $body));< "data": < "serial_number": "WF2345G123", "type": "WIFI", "commission_date": "2021-01-01T00:00:00Z", "inverter": < "serial": "CE2345G123", "status": "WAITING", "last_online": "2023-01-01T00:00:00Z", "last_updated": "2023-01-01T00:00:00Z", "commission_date": "2021-01-01T00:00:00Z", "info": < "battery_type": "LITHIUM", "battery": < "nominal_capacity": 110, "nominal_voltage": 51.2 >, "model": "GIV-AC-3.0", "max_charge_rate": 2560 >, "warranty": < "type": "Standard", "expiry_date": "2033-01-01T00:00:00Z" >, "firmware_version": < "ARM": 420, "DSP": 426 >, "connections": < "batteries": [ < "module_number": 1, "serial": "BB2345G123", "firmware_version": "1035", "capacity": < "full": 110, "design": 110 >, "cell_count": 16, "has_usb": true, "nominal_voltage": 51.2 > ], "meters": [ < "address": 1, "serial_number": 212345678, "manufacturer_code": "0000", "type_code": 1500, "hardware_version": 1000, "software_version": 1000, "baud_rate": 9600 >] >, "flags": [] > > > Received response :
Request failed with error:
requires authentication account type: any scope: api:inverter:read
Retrieves the latest system data from the EMS
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 |
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 |
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 |
This will only work with Plant EMS
Example request:
curl --request GET \ --get "https://api.givenergy.cloud/v1/ems/consequatur/system-data/latest" \ --header "Authorization: Bearer " \ --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 ", "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 ', '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 ', 'Content-Type' => 'application/json', 'Accept' => 'application/json', ], ] ); $body = $response->getBody(); print_r(json_decode((string) $body));< "data": < "battery_power": 9214, "battery_wh_remaining": 58276, "calculated_load_power": 15168, "car_power": -27828, "error_code": 40330, "grid_power": 16772, "measured_load_power": 19053, "status": 3, "time": null, "total_generation": 8035, "warning_code": 48384, "inverters": [ < "active_power": -8597, "number": 1, "serial_number": "il6029p206", "soc": 88, "status": 4, "temperature": 3.2 >, < "active_power": -2221, "number": 2, "serial_number": "nl3168l361", "soc": 79, "status": 4, "temperature": 10.3 >, < "active_power": 24191, "number": 3, "serial_number": "uy0262d251", "soc": 43, "status": 2, "temperature": 28.4 >, < "active_power": null, "number": 4, "serial_number": null, "soc": null, "status": 0, "temperature": null >], "meters": [ < "active_power": null, "number": 1, "status": 0, "type": 0 >, < "active_power": null, "number": 2, "status": 2, "type": 1 >, < "active_power": null, "number": 3, "status": 0, "type": 3 >, < "active_power": null, "number": 4, "status": 2, "type": 2 >, < "active_power": null, "number": 5, "status": 0, "type": 0 >, < "active_power": null, "number": 6, "status": 0, "type": 0 >, < "active_power": null, "number": 7, "status": 0, "type": 0 >, < "active_power": null, "number": 8, "status": 0, "type": 0 >] > > Received response :
Request failed with error:
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.
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 |
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 " \ --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 ", "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 ', '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 ', 'Content-Type' => 'application/json', 'Accept' => 'application/json', ], 'query' => [ 'page' => '1', ], ] ); $body = $response->getBody(); print_r(json_decode((string) $body));Received response :
Request failed with error:
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 " \ --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 ", "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 ', '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 ', 'Content-Type' => 'application/json', 'Accept' => 'application/json', ], ] ); $body = $response->getBody(); print_r(json_decode((string) $body));Received response :
Request failed with error:
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.
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.
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.
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 |
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 " \ --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 ", "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 ', '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 ', '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));Received response :
Request failed with error:
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:
(This replaces command_id in the request parameters)
A brief description of the command goes here
This is a list of parameters that must be sent with this command
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
Instructs the charger to start charging
This command requires no 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 []Instructs the charger to stop charging
This command requires no 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 []Sets the maximum charge power
Must be between 6 and 32.
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
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
enabled boolean true false
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 trueConfigures the server to instruct the charger to stop charging if the charging session puts this much energy into the vehicle
limit number optional
Must be between 0.1 and 250.
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
Create a new schedule. The newly created schedule is not yet active on the charger
schedule_id string optional
Must not be greater than 30 characters.
Must be a valid date in the format H:i .
Must be a valid date in the format H:i .
Must be between 6 and 32.
Must be at least 0. Must not be greater than 6.
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" >] > ] >Instructs the charger to unlock the plug from the vehicle. The vehicle may override this command
This command requires no 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 one or all schedules from the charger
schedule_id string optional
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 []Changes the charger's current operating mode
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
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
Sends a command to restart the charger immediately
hard_reset boolean optional true false
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 []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
Must be at least 600. Must not be greater than 1800.
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 nullRegister one or more ID tags to the charger
Must have at least 1 items.
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.
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 one or of the charger's registered ID tags
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 nullRename one of the charger's ID tags
Must not be greater than 20 characters. Must be at least 1 character.
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 nullUpdate the charger's installation mode
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 |
installation_mode string
Must be one of standalone , ct_meter , or inverter_control .
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"A description has not been provided for this command
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 the charger's active schedule. If no schedule ID is provided the currently active schedule will be deactivated
schedule_id string optional
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
Set the maximum import capacity of the charger's main supply in amps
value integer optional
Must be between 40 and 100.
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
Turn the charger's front panel LED on or off
value boolean true false
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 the behaviour of the charger and inverter when in inverter control mode
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:
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 |
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.
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.
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 .
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
Performs a factory reset on the charger
This command requires no 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 the configuration mode of the charger
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 |
configuration_mode string
Must be one of A , B , C , D , or E .
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
Enable or disable local Modbus control on the charger
value boolean true false
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
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.
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.
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" >>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
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 " \ --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 ", "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 ', '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 ', 'Content-Type' => 'application/json', 'Accept' => 'application/json', ], ] ); $body = $response->getBody(); print_r(json_decode((string) $body));Received response :
Request failed with error:
requires authentication account type: any scope: api:ev-charger:control
Fetch the current data for the given command and EV Charger
A 422 error will be thrown if an invalid command ID is provided or if the given EV charger does not support the given command
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 " \ --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 ", "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 ', '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 ', 'Content-Type' => 'application/json', 'Accept' => 'application/json', ], ] ); $body = $response->getBody(); print_r(json_decode((string) $body));Received response :
Request failed with error:
requires authentication account type: any scope: api:ev-charger:control
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 " \ --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 ", "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 ', '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 ', 'Content-Type' => 'application/json', 'Accept' => 'application/json', ], ] ); $body = $response->getBody(); print_r(json_decode((string) $body));Received response :
Request failed with error:
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.
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 |
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 .
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.
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 " \ --header "Content-Type: application/json" \ --header "Accept: application/json" \ --data "< \"start_time\": \"2019-01-06\", \"end_time\": \"2105-10-10\" >" 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 ", "Content-Type": "application/json", "Accept": "application/json", >; let body = < "start_time": "2019-01-06", "end_time": "2105-10-10" >; 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-01-06", "end_time": "2105-10-10" >params = < 'page': '1', >headers = < 'Authorization': 'Bearer ', '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 ', 'Content-Type' => 'application/json', 'Accept' => 'application/json', ], 'query' => [ 'page' => '1', ], 'json' => [ 'start_time' => '2019-01-06', 'end_time' => '2105-10-10', ], ] ); $body = $response->getBody(); print_r(json_decode((string) $body));Received response :
Request failed with error:
requires authentication account type: any scope: api:inverter:data
The energy flow data is calculated using energy readings from the meter and energy and power readings from the inverter. Because of this, the energy flow readings may be lower than expected if the inverter is disconnected from our servers for periods of 30 minutes or more. It should also be noted that, because these are calculated values, they are simply an indication of energy values from different sources and should never be used in place of meter readings Please note that energy values are calculated as energy that flows directly from the source to its destination. Because of this, energy may be counted twice in some scenarios. For example, if the solar panels generate 1kWh that is used to charge the battery, then the battery exports that same energy to the grid, PV to Battery and Battery to Grid will both increase by a value of 1 Due to the way energy flow records are stored and calculated, the returned start and end times are based on the inverter's local time and are not formatted to ISO8601 standards. The start_date and end_date body parameters follow the same rules
| 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 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 " \ --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 ", "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 ', '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 ', '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));