About Solar API¶

This is an overview to the API, such as the standards and protocols followed by the API, the development languages supported by the API, and the functions that the API can implement.

Solar API provides REST APIs that cover the core business processes of photovoltaic systems. Based on these APIs, developers can access resources within the system to develop various applications.

API list¶

Solar API provides the following API services：

Login Service：provide service like login, choose orgnization.

Master Data Service：provide service like get device attributes, list devices.

Metric Service：provide service like query metrics.

Domain Service：provide service like get latest value of domain points.

Dimension Service：provide service like get city,province items.

Analytics Service：provide service like corrective action, down events.

Log Service：provide service like query / add task log.

Note

Solar API does not support second-level calls.
It is recommended to call the irradiation intensity per 20s.
It is recommended to call the daily production per 60s or more.
It is recommended to call the tomorrow’s production per 1h or more.

API Request Structure¶

Solar API contains following parts：

Request URI¶

METHOD {URI-scheme}://{apigw-address}/{service-name}/{version}/{endpoint-URL}?{query-param={}}

Details：

METHOD：HTTP Method, like GET、POST.
URI-sheme：protocal, support https.
apigw-address：API gateway address, like app-portal-xxx.envisioniot.com.
service-name：service name, like solar-api.
version：API version, like v1.0.
endpoint-URL：resource name or operations on resources, like loginService/login.
query-param：query parameters, like token=1234. use & as delimiter if there are multiple parameters, e.g. token={}&time_group={}&points={}&mdmids={}

Taking query asset information as an example, the API request format is as follows:

GET
https://{apigw-address}/solar-api/mdmService/getObjects?token=token&mdmids=123,4646&types=102

Request Header¶

Fields required by REST API specification or the HTTP specification are bound in the request header.

The commonly used request header is Content-Type, which represents the data submission method. In general, its value can be set toapplication / json; charset = UTF-8; if file upload or other form submission is performed, the value is set to multipart / form-data; charset = UTF-8.

For service account call, below headers are required, please see token authentication for detail.

```
apim-accesstoken: accessToken
apim-signature: apim-signature
apim-timestamp: timestamp
```

Request Body¶

It is used to supplement the Request URI to provide more complex input parameters, such as the following example, the request body contains attributes such as username and password:

POST
https://{apigw-address}/solar-api/v1.0/loginService/login
{
  "username":"your userName",
  "password":"your password"
}

API Response¶

This is the response structure of API.

For example

Solar API respond json like below:

{
    "data": [
        {
            "timeGroup": "D,M,Y,T",
            "description": "production hours",
            "metric": "SITE.FullHour"
        }
    ],
    "status": 0,
    "msg": "success"
}

The detailed description of the return parameters is as follows:

Name	Required	Datatype	Description
status	true	Int	API response status code, 0 means the request was successful. For the meaning of other status codes, please refer to the common return codes and the error codes in the API documentation.
msg	true	String	Explanation and description of status codes. Success is success or OK. If the API request fails, a specific error message is returned.
data	false	Array or Object	The API returns a result set. The data types include: basic data types, complex types, or arrays.

Common parameters¶

The common parameters of each API will be described here.

Object types¶

API support these object types:

Code	Description
102	site
202	grid meter
206	inverter
207	combiner box
208	weather station
211	energy meter
212	substation
217	ac combiner box
218	soiling station
236	tracker
300	device group, such as racking, soiling zone

Common response code¶

API respond below common codes:

Code	Description
0	success
10001	ginvalid parameters
10002	login failed
10006	internal server error
10007	token is empty
10008	no object id provided
10009	token authentication failure
10010	token expired
10011	missing required parameters

Example:

10006 error example: internal server error
{
    "status": 10006,
    "msg": "service Execute Exception"
}

10007 error example: token is empty
{
    "status": 10007,
    "msg": "token is empty"
}

10008 error example: object id is null
{
    "status": 10008,
    "msg": "mdmid is null"
}

10009 error example: token authentication failure
{
    "status": 10009,
    "msg": "token authentication failure"
}

10010 error example: token expired
{
    "status": 10010,
    "msg": "token expired"
}

10011 error example: missing params
{
    "status": 10011,
    "msg": "missing params"
}