Note: The number of users of this project has grown considerably. This is great. Unfortunately, the operation of solar prognosis (Solarprognose) is not free of charge. I would be thankful if you donate some euro. Donate

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).
Because in some seconds extremely many API requests arrive please use preferredNextApiRequestAt!

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
&project=Please add here your projects website or your contact email so that I can get in contact with you if necessary.
&item=ITEM&id=ID
Alternative: &item=ITEM&token=TOKEN
Alternative: If you have only one location you do not need to send item/id/token, the API will return data for first location
&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

Tip: If you do not send item and id/token the API returns the data for the first location. If you have only one location then this makes it easier.
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;
STATUS_ERROR_INVALID_ALGORITHM = -28;

preferredNextApiRequestAt

Please use the with the API request returned "preferredNextApiRequestAt". It returns the second of the hour when you should query the API. Every user is assigned a time, so that the requests are equally split over the hours. It also contains "epochTimeUtc" which you can directly use to time the execution of your API request.
...
"preferredNextApiRequestAt":{
    "secondOfHour":120, # (Execute the api request in the 120. second of the hour.)
    "epochTimeUtc":1626796920 # (Execute the next api request at this epoch time.)
}

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