API - Application Program Interface Description

The Solarprediction API is based on HTTP requests. The response messages are in JSON (JavaScript Object Notation) or XML.
Important: To reduce traffic and server load please use a local cache on your webserver. I recommend caching the result for at least one hour (the weather does not change that fast).

Solarprediction API

The HTTP requests for daily or hourly prediction of production should be in the following format:

http://www.solarprognose.de/web/solarprediction/api/v1?
access-token=ACCESS-TOKEN
&item=ITEM&id=ID
Alternative: &item=ITEM&token=TOKEN
&type=hourly|daily
&_format=json|xml
&algorithm=mosmix|own-v1|clearsky
&day=DAY
&start_epoch_time=START_EPOCH_TIME&end_epoch_time=END_EPOCH_TIME
&start_day=START_DAY&end_day=END_DAY
&snomminixml=true # for snom VoIP telephones

ACCESS-TOKEN

Your API Access Token.

ITEM and ID

ITEM
location or plant or inverter or module_field
ID
The ID is the id of the item.

ITEM and TOKEN

ITEM and TOKEN is required to access items in the prediction which are not public: &item=inverter&token=
If you access with your access-token then you can access your private (non-public) items.

Dates and Periods

DAY

allowed values: from -2 to 6
Then you will get the data from the day relative to now. Attention: This may be limited by your plan! The error "STATUS_ERROR_INVALID_END_DAY" may occur if the value is higher than in your plan.

START_DAY

allowed values: from -2 to 6
For requesting data from a specific time period. This defines the start day relative from today. Attention: This may be limited by your plan! The error "STATUS_ERROR_INVALID_END_DAY" may occur if the value is higher than in your plan.

END_DAY

allowed values: from -2 to 6
For requesting data from a specific time period. This defines the end day relative from today. Attention: This may be limited by your plan! The error "STATUS_ERROR_INVALID_END_DAY" may occur if the value is higher than in your plan.

START_EPOCH_TIME

e. g.: 1439650241 For requesting data from a specific time period. This defines the start epoch time. Attention: This may be limited by your plan! The error "STATUS_ERROR_INVALID_END_DAY" may occur if the value is higher than in your plan.

END_EPOCH_TIME

e. g.: 1439650241 For requesting data from a specific time period. This defines the end epoch time. Attention: This may be limited by your plan! The error "STATUS_ERROR_INVALID_END_DAY" may occur if the value is higher than in your plan.

Status Codes

If you are using a invalid api key then you will receive the HTTP Status Code 401 Unauthorized.

STATUS_OK = 0;
STATUS_ERROR_INVALID_ACCESS_TOKEN = -2;
STATUS_ERROR_MISSING_PARAMETER_ACCESS_TOKEN = -3;
STATUS_ERROR_EMPTY_PARAMETER_ACCESS_TOKEN = -4;
STATUS_ERROR_INVALID_TYPE = -5;
STATUS_ERROR_MISSING_TYPE = -6;
STATUS_ERROR_INVALID_ID = -7;
STATUS_ERROR_ACCESS_DENIED = -8;
STATUS_ERROR_INVALID_ITEM = -9;
STATUS_ERROR_INVALID_TOKEN = -10;
STATUS_ERROR_NO_SOLAR_DATA_AVAILABLE = -11;
STATUS_ERROR_NO_DATA = -12;
STATUS_ERROR_INTERNAL_ERROR = -13;
STATUS_ERROR_UNKNOWN_ERROR = -14;
STATUS_ERROR_INVALID_START_DAY = -15;
STATUS_ERROR_INVALID_END_DAY = -16;
STATUS_ERROR_INVALID_DAY = -17;
STATUS_ERROR_INVALID_WEATHER_SERVICE_ID = -18;
STATUS_ERROR_DAILY_QUOTA_EXCEEDED = -19;
STATUS_ERROR_INVALID_OR_MISSING_ELEMENT_ITEM = -20;
STATUS_ERROR_NO_PARAMETER = -21;
STATUS_ERROR_INVALID_PERIOD = -22;
STATUS_ERROR_INVALID_START_EPOCH_TIME = -23;
STATUS_ERROR_INVALID_END_EPOCH_TIME = -24;
STATUS_ERROR_ACCESS_DENIED_TO_ITEM_DUE_TO_LIMIT = -25;
STATUS_ERROR_NO_CLEARSKY_VALUES = -26;
STATUS_ERROR_MISSING_INPUT_ID_AND_TOKEN = -27;

Examples

Request:

http://www.solarprognose.de/web/solarprediction/api/v1?access-token=454jelfd&item=inverter&id=2&type=hourly

Result:

{
    "status":0,
    "iLastPredictionGenerationEpochTime":1576681137,
    "datalinename":"Süd",
    "data":{
        "1576735200":[0,0], // timestamp: kilowatt/kw, accumulated kwh
        "1576738800":[0.064,0.064],
        "1576742400":[0.606,0.67],
        "1576746000":[1.148,1.818],
        "1576749600":[1.647,3.465],
        "1576753200":[0.295,3.76],
        "1576756800":[0.273,4.033],
        "1576760400":[1.3,5.333],
        "1576764000":[0.305,5.638],
        "1576767600":[0.014,5.652],
        "1576771200":[0,5.652],
        ... the other days follow
    }
}

Request:

http://www.solarprognose.de/web/solarprediction/api/v1?access-token=454jelfd&item=inverter&id=2&type=daily

Result:

{
    "iLastPredictionGenerationEpochTime":1576686390,
    "status": 0,
    "datalinename": "SMASB2000TL"
    "data": {
        "20151212": 1.978, // yyymmdd: kwh per day
        "20151213": 1.999,
        "20151214": 4.049,
        "20151215": 5.567,
        "20151216": 1.948,
        "20151217": 1.925
    },
}

Request:

http://www.solarprognose.de/web/solarprediction/api/v1?_format=json&access-token=454jelfd&item=inverter&id=2&type=hourly&day=1

Result:

{
    "status":0,
    "iLastPredictionGenerationEpochTime":1576681137,
    "datalinename":"Süd",
    "data":{
        "1576735200":[0,0],
        "1576738800":[0.064,0.064],
        "1576742400":[0.606,0.67],
        "1576746000":[1.148,1.818],
        "1576749600":[1.647,3.465],
        "1576753200":[0.295,3.76],
        "1576756800":[0.273,4.033],
        "1576760400":[1.3,5.333],
        "1576764000":[0.305,5.638],
        "1576767600":[0.014,5.652],
        "1576771200":[0,5.652]
    }
}

http://www.solarprognose.de/web/solarprediction/api/v1?access-token=454jelfd&item=inverter&token=DEF&type=hourly
http://www.solarprognose.de/web/solarprediction/api/v1?access-token=454jelfd&item=inverter&token=DEF&type=daily
http://www.solarprognose.de/web/solarprediction/api/v1?access-token=454jelfd&item=inverter&token=DEF&type=hourly&day=-1