This version of the API follows the newer OpenAPI V1 API Growatt has made available.
It extends our "Legacy" ShinePhone so methods from there should be available, but it's safer to rely on the methods described in this file where possible.
The public v1 API requires token-based authentication
import growattServer
api = growattServer.OpenApiV1(token="YOUR_API_TOKEN")
# Get a list of growatt plants.
plants = api.plant_list_v1()
print(plants)Methods that work across all device types.
| Method | Arguments | Description |
|---|---|---|
api.plant_list() |
None | Get a list of plants registered to your account. |
api.plant_details(plant_id) |
plant_id: String | Get detailed information about a power station. |
api.plant_energy_overview(plant_id) |
plant_id: String | Get energy overview data for a plant. |
api.plant_energy_history(plant_id, start_date, end_date, time_unit, page, perpage) |
plant_id: String, start_date: Date, end_date: Date, time_unit: String, page: Int, perpage: Int | Get historical energy data for a plant for multiple days/months/years. |
api.device_list(plant_id) |
plant_id: String | Get a list of devices in specified plant. |
Devices offer a generic way to interact with your device using the V1 API without needing to provide your S/N every time. And can be used instead of the more specific device methods in the API class.
import growattServer
from growattServer.open_api_v1.devices import Sph, Min
api = growattServer.OpenApiV1(token="YOUR_API_TOKEN")
my_inverter = Sph(api, 'YOUR_DEVICE_SERIAL_NUMBER') # or Min(api, 'YOUR_DEVICE_SERIAL_NUMBER')
my_inverter.detail()
my_inverter.energy()
my_inverter.energy_history()
my_inverter.read_parameter()
my_inverter.write_parameter()| Method | Arguments | Description |
|---|---|---|
device.energy() |
None | Get current energy data for any inverter, including power and energy values. |
device.detail() |
None | Get detailed data for any inverter. |
device.energy_history(start_date=None, end_date=None, timezone=None, page=None, limit=None) |
start_date: Date, end_date: Date, timezone: String, page: Int, limit: Int | Get energy history data for any inverter (7-day max range). |
device.read_parameter(parameter_id, start_address=None, end_address=None) |
parameter_id: String, start_address: Int, end_address: Int | Read a specific setting for any inverter. |
device.write_parameter(parameter_id, parameter_values) |
parameter_id: String, parameter_values: Dict/Array | Set parameters on any inverter. Parameter values can be a single value, a list, or a dictionary. |
For more details see: OpenApiV1 Devices
The remaining methods below all actually use these device methods.
Methods for MIN devices (type 7).
| Method | Arguments | Description |
|---|---|---|
api.min_energy(device_sn) |
device_sn: String | Get current energy data for a min inverter, including power and energy values. |
api.min_detail(device_sn) |
device_sn: String | Get detailed data for a min inverter. |
api.min_energy_history(device_sn, start_date=None, end_date=None, timezone=None, page=None, limit=None) |
device_sn: String, start_date: Date, end_date: Date, timezone: String, page: Int, limit: Int | Get energy history data for a min inverter (7-day max range). |
api.min_settings(device_sn) |
device_sn: String | Get all settings for a min inverter. |
api.min_read_parameter(device_sn, parameter_id, start_address=None, end_address=None) |
device_sn: String, parameter_id: String, start_address: Int, end_address: Int | Read a specific setting for a min inverter. see: details |
api.min_write_parameter(device_sn, parameter_id, parameter_values) |
device_sn: String, parameter_id: String, parameter_values: Dict/Array | Set parameters on a min inverter. Parameter values can be a single value, a list, or a dictionary. see: details |
api.min_write_time_segment(device_sn, segment_id, batt_mode, start_time, end_time, enabled=True) |
device_sn: String, segment_id: Int, batt_mode: Int <0=load priority, 1=battery priority, 2=grid priority>, start_time: datetime.time, end_time: datetime.time, enabled: Bool | Update a specific time segment for a min inverter. see: details |
api.min_read_time_segments(device_sn, settings_data=None) |
device_sn: String, settings_data: Dict | Read all time segments from a MIN inverter. Optionally pass settings_data to avoid redundant API calls. see: details |
Methods for SPH devices (type 5).
| Method | Arguments | Description |
|---|---|---|
api.sph_detail(device_sn) |
device_sn: String | Get detailed data and settings for an SPH hybrid inverter. see: details |
api.sph_energy(device_sn) |
device_sn: String | Get current energy data for an SPH inverter, including power and energy values. |
api.sph_energy_history(device_sn, start_date=None, end_date=None, timezone=None, page=None, limit=None) |
device_sn: String, start_date: Date, end_date: Date, timezone: String, page: Int, limit: Int | Get energy history data for an SPH inverter (7-day max range). |
api.sph_read_parameter(device_sn, parameter_id=None, start_address=None, end_address=None) |
device_sn: String, parameter_id: String (optional), start_address: Int (optional), end_address: Int (optional) | Read a specific parameter (only pv_on_off supported). see: details |
api.sph_write_parameter(device_sn, parameter_id, parameter_values) |
device_sn: String, parameter_id: String, parameter_values: Dict/Array | Set parameters on an SPH inverter. see: details |
Convenience methods that wrap the core SPH methods above for common use cases.
| Method | Arguments | Description |
|---|---|---|
api.sph_write_ac_charge_times(...) |
device_sn, charge_power, charge_stop_soc, mains_enabled, periods | Helper: wraps sph_write_parameter() with type mix_ac_charge_time_period. see: details |
api.sph_write_ac_discharge_times(...) |
device_sn, discharge_power, discharge_stop_soc, periods | Helper: wraps sph_write_parameter() with type mix_ac_discharge_time_period. see: details |
api.sph_read_ac_charge_times(...) |
device_sn, settings_data (optional) | Helper: parses charge config from sph_detail() response. see: details |
api.sph_read_ac_discharge_times(...) |
device_sn, settings_data (optional) | Helper: parses discharge config from sph_detail() response. see: details |
Methods from classic API should be available, but it's safer to rely on the methods described in this section where possible. There is no guarantee that the classic API methods will work, or remain stable through updates.
Some variables you may want to set.
api.server_url The growatt server URL, default: 'https://openapi.growatt.com/v1/'
You may need a different URL depending on where your account is registered:
'https://openapi-cn.growatt.com/v1/' (Chinese server) 'https://openapi-us.growatt.com/v1/' (North American server) 'https://openapi.growatt.com/v1/' (Other regional server: e.g. Europe)
api = growattServer.GrowattApiV1(token="YOUR_API_TOKEN") # Initialize with your API token