PV-Log API V1 Documentation

Document Version: 0.3
Date: 4.Jan.2013

Getting Started

Hello developers!!

Thank you very much for your interest in the PV-Log API. The team of PV-Log strongly believes in the change of our energy system to 100% renewable energies. Our vision of PV-Log is an open platform for comparing, analyzing and sharing solar energy yields, independently from single technologies or system restrictions. With the PV-Log API you have the possibility to create own applications, interesting tools, devices for data pushing and a lot more.

We tried to program the API for an easy and intuitive use. We want, that you enjoy developing your programs and applications. As we all know, there are always things to improve, therefore we are very happy to get your feedback and hear from you. Don´t hesitate to contact us.

Now, let´s have fun and develop your first App or program using the PV-Log API.

Best regards,

PV-Log Team

General

a) Secret API Key

All developers, who want to use the PV-Log, need a secret API key, which must be transmitted with every call. Without a valid secret API key, the API won´t respond.
Ask for your personal secret API key sending an Email to:
email@pv-log.com

Important: The secret API key must be stored in your application in a way, that it´s not visible for your users.

b) Help

Developer board:
There is a developer board, where you can get a lot of information. Please contact us for getting access:
email@pv-log.com


API call: /help

For a quick realtime overview of the available API resources use:
https://api.pv-log.com/api/v1/[secret-api-key]/help

c) API Calls with SSL

It´s obligatory to use SSL for your API Calls on our live system. The address of the API is:
https://api.pv-log.com/api/v1/[secret-api-key]/
(On the test system no SSL is possible)

d) Return Value / Format Json

API calls are always answered with a Json response with the following scheme:

{

"result": [

],

"messages": [

]

}

Array “result”

The array “result” contains the result objects of the API call.

Array “messages”

The array “messages” contains messages about your call. Here an example:

"messages": [

{

"code":"20",

"title":"Invalid Plant Key",

"type":2,

"typestatus":"error"

}

]

code: is the message code
title: message title
type: 2=error, 3=success

typestatus: is the type readable

e) Authentication

There are two authentication methods:

Method 1 (Standard): PV-Log Plant Key

Every plant has an unique plant key, which is only visible to the user of the plant. It can be found in “My Profil”.

Example: dfjd48hs54


With the user entering the PV-Log plant key into your program, he is allowing your application to access his plant data of this specific plant, including updates of yield data etc..

Method 2: Username and Password

This authentication method is only needed, when user data needs to be accessed.

You have to use the API login call with Post-Variables: username, password:
https://www.pv-log.com/api/v1/[secret-api-key]/user/login
The result is a session token which must be used in further calls. (Shell scripts using curl must save the cookie and send the cookie on later calls together with the token. Only the token is not enough.)

User login test page: https://www.pv-log.com/api/v1/test-user-login.html 

f) HTTP Headers

[@todo]

g) Rights

You need certain rights for some API calls. If you don´t have them you will get an error message and no result. You can see your rights under “account” using the API call:
https://www.pv-log.com/api/v1/[secret-api-key]/help

h) Rate Limits

API calls are rate limited. You will get a corresponding error message, if you reach a limit. Please contact us, if you need higher limits.

i) Sending Energy Yield Data / Format Json

You can push energy yield data to the PV-Log API using the PV-Log Json data format.
Here you find the documentation of the PV-Log Json file format: http://goo.gl/kPq6Zu

Example File: http://www.pv-log.com/Resources/Public/Upload/2015-05-22-pvlog.json

Energy yield push test page: https://pv-log.com/api/v1/test-yield-update.html 

REST API Resources

a) Available Methods:

The actual list of available methods you will get with the API call:
https://www.pv-log.com/api/v1/[secret-api-key]/help