NAV Navbar
shell javascript
  • Introduction
  • Endpoints
  • Authentication
  • Settings and stats
  • Synchronization
  • Notifications
  • Introduction

    Welcome to the EVNotify API! You can use the API to set and fetch useful information.

    To use the API, you can either send the requests directly (over Shell) or you can use the easy-to-use JavaScript Library, which you will find within the EVNotifyAPI Repository on GitHub.

    This API is in an early-access development. Feel free to enhance this API Documentation and send suggestions to improve the API by itself.

    To be able to use this API, you must register an account. With registering an account, you agree to the terms of use of EVNotify.

    Endpoints

    The API for EVNotify can be accessed over HTTP as well as HTTPS. HTTP is deprecated and for security-reasons you should use the HTTPS endpoint. Some requests may require HTTPS only, so HTTP will be removed some time. If your application is still using the HTTP endpoint, you should be thinking about upgrading to HTTPS endpoint.

    Authentication

    To be able to interact with the EVNotify API, most requests requires an authentication. This is done by providing your so called AKey, which is your account identifier, to the request together with your personal token.

    Get a new key

    If you don't have an AKey yet, you have to create a new account in order to be able to interact with the whole API. To get a new AKey, you can do so with the following request. This will return a currently unused AKey, which you can register.

    HTTPS Request

    POST https://evnotify.de:8743/getkey

    curl "https://evnotify.de:8743/getkey"
      -H "Content-Type: application/json"
    

    The request returns JSON like this:

    {
      "akey": 1234
    }
    
    var evnotify = new EVNotify();
    
    // get an unused key
    evnotify.getKey(function(err, key) {
      console.log('Key: ', key);  // Key: 1234 for example
    });
    

    Register a new account

    After retrieving an unused AKey, you can register it. You need to specify the AKey, as well as a password. For your own safety, you should choose a strong password. The minimum length for a valid password is 6 characters.

    HTTPS Request

    POST https://evnotify.de:8743/register

    URL Parameters

    Parameter Description
    akey The AKey to register
    password The password to use
    curl "https://evnotify.de:8743/register"
      -H "Content-Type: application/json"
      -X POST -d '{"akey":"akey","password":"password"}'
    

    The request returns JSON like this:

    {
      "message": "Registration successful",
      "token": "secrettoken"
    }
    
    var evnotify = new EVNotify();
    
    // register new account
    evnotify.register('akey', 'password', function(err, token) {
      console.log('Token: ', token);  // Contains the token for authentication
    });
    

    Login with existing account

    Once you've registered an account - or already have an account, you can login with your credentials. This will give you the token, which authenticates your account.

    HTTPS Request

    POST https://evnotify.de:8743/register

    URL Parameters

    Parameter Description
    akey The AKey of the account to login
    password The password of the account
    curl "https://evnotify.de:8743/login"
      -H "Content-Type: application/json"
      -X POST -d '{"akey":"akey","password":"password"}'
    

    The request returns JSON like this:

    {
      "message": "Login successful",
      "token": "secrettoken"
    }
    
    var evnotify = new EVNotify();
    
    // login with account
    evnotify.login('akey', 'password', function(err, token) {
      console.log('Token: ', token);  // Contains the token for authentication
    });
    

    Change the password for an account

    In order to be able to change the password for an account, you need to first enter your old password. Currently it is not possible to recover a lost password.

    HTTPS Request

    POST https://evnotify.de:8743/password

    URL Parameters

    Parameter Description
    akey The AKey of the account to change the password for
    token The token of the account
    password The old password of the account
    newpassword The new password to set
    curl "https://evnotify.de:8743/password"
      -H "Content-Type: application/json"
      -X POST -d '{"akey":"akey","token": "token","password":"oldpassword", "newpassword": "newpassword"}'
    

    The request returns JSON like this:

    {
      "message": "Password change succeeded"
    }
    
    var evnotify = new EVNotify();
    
    // change password for account
    evnotify.changePW('oldpassword', 'newpassword', function(err, changed) {
      console.log('Password changed: ', changed);  // True, if change was successful
    });
    

    Renew the account token

    In order to be able to renew the token of your account, you will need to provide the AKey as well as the password of the account. Changing the account token in regular periods is a good security manner.

    HTTPS Request

    POST https://evnotify.de:8743/renewtoken

    URL Parameters

    Parameter Description
    akey The AKey of the account to renew the token for
    password The password of the account
    curl "https://evnotify.de:8743/renewtoken"
      -H "Content-Type: application/json"
      -X POST -d '{"akey":"akey","password":"password"}'
    

    The request returns JSON like this:

    {
      "message": "Token renewed",
      "token": "newtoken"
    }
    
    var evnotify = new EVNotify();
    
    // renew token of the account
    evnotify.renewToken('password', function(err, token) {
      console.log('New token: ', token);  // The new token
    });
    

    Settings and stats

    Get settings and stats from account

    Every account has a collection of settings and stats. Those collection store information about the connection and settings for the state of charge monitoring and notification.

    HTTPS Request

    POST https://evnotify.de:8743/settings

    URL Parameters

    Parameter Description
    akey The AKey of the account to retrieve the settings for
    token The token of the account
    password The password of the account
    option must be 'GET' to retrieve the settings
    curl "https://evnotify.de:8743/settings"
      -H "Content-Type: application/json"
      -X POST -d '{"akey":"akey","token": "token","password":"password", "option": "GET"}'
    

    The request returns JSON like this:

    {
      "message": "Get settings succeeded",
      "settings": {
        "email": "email",
        "telegram": "telegram",
        "soc": "soc",
        "curSoC": "curSoC",
        "device": "device",
        "polling": "polling",
        "autoSync": "autoSync",
        "lng": "lng",
        "push": "push"
      }
    }
    
    var evnotify = new EVNotify();
    
    // get the settings and stats for account
    evnotify.getSettings('password', function(err, settingsObj) {
      console.log('Settings: ', settingsObj);  // Object containing all the settings and stats
    });
    

    Set settings and stats for account

    You can modify the settings for the state of charge monitoring, notification and other settings and stats for the account. Be careful, since wrong changes can break a working notification or other things.

    HTTPS Request

    POST https://evnotify.de:8743/settings

    URL Parameters

    Parameter Description
    akey The AKey of the account to retrieve the settings for
    token The token of the account
    password The password of the account
    option must be 'SET' to apply the settings
    optionObj object containing all the properties to save (see getSettings properties output to get full list)
    curl "https://evnotify.de:8743/settings"
      -H "Content-Type: application/json"
      -X POST -d '{"akey":"akey","token": "token","password":"password", "option": "SET", "optionObj": "{}"}'
    

    The request returns JSON like this:

    {
      "message": "Set settings succeeded"
    }
    
    var evnotify = new EVNotify(),
        settingsObj = {}; // the settings object containing all properties
    
    // set the settings and stats for account
    evnotify.setSettings('password', settingsObj, function(err, set) {
      console.log('Settings saved: ', set);  // True, if successful
    });
    

    Synchronization

    Synchronize the settings and stats

    If you want to synchronize the settings and stats of an account without entering a password (for example when you want to synchronize them in the background), you can make use of the sync request. This request allows you to retrieve or set the settings without being prompted for a password. Please note, that this requires to have 'autoSync' option set previously with the setSettings request, if not enabled yet.

    HTTPS Request

    POST https://evnotify.de:8743/sync

    URL Parameters

    Parameter Description
    akey The AKey of the account to sync the settings for
    token The token of the account
    type determines whether you want to retrieve the settings ('PULL' as type) or set the settings ('PUSH' as type)
    syncObj the settings object you want to set (only necessary if 'PUSH' as type)
    curl "https://evnotify.de:8743/sync"
      -H "Content-Type: application/json"
      -X POST -d '{"akey":"akey","token":"token", "type": "PULL"}'
    

    The sync request (PULL) returns JSON like this:

    {
      "message": "Pull for sync succeeded",
      "syncRes": {
          "email": "email",
          "telegram": "telegram",
          "soc": "soc",
          "curSoC": "curSoC",
          "device": "device",
          "polling": "polling",
          "autoSync": "autoSync",
          "lng": "lng",
          "push": "push"
      }
    }
    
    curl "https://evnotify.de:8743/sync"
      -H "Content-Type: application/json"
      -X POST -d '{"akey":"akey","token":"token", "type": "PUSH", syncObj: "{}"}'
    

    The sync request (PUSH) returns JSON like this:

    {
      "message": "Push for sync succeeded",
      "syncRes": true
    }
    
    var evnotify = new EVNotify(),
        syncObj = {};   // the settings object containing all required information
    
    // retrieve the settings
    evnotify.pullSettings(function(err, settingsObj) {
      console.log('Settings: ', settingsObj);  // The settings and stats of the account
    });
    
    // set the settings
    evnotify.pushSettings(syncObj, function(err, pushed) {
      console.log('Push succeeded: ', pushed);
    });
    

    Synchronize the state of charge

    The main advantage of EVNotify is the monitoring of the state of charge. To be able to track it and fetch it at any time, you'll need to inform the server about the current value. You can also manually set the 'curSoC' property within the sync (type 'PUSH') or setSettings request. But the syncSoC request will only update the state of charge and decreases the data usage.

    HTTPS Request

    POST https://evnotify.de:8743/syncSoC

    URL Parameters

    Parameter Description
    akey The AKey of the account to sync the state of charge for
    token The token of the account
    soc The state of charge you want to submit
    curl "https://evnotify.de:8743/syncSoC"
      -H "Content-Type: application/json"
      -X POST -d '{"akey":"akey","token":"token", "soc": 42}'
    

    The request returns JSON like this:

    {
      "message": "Sync for soc succeeded"
    }
    
    var evnotify = new EVNotify();
    
    // submit the current state of charge
    evnotify.syncSoC(42, function(err, synced) {
      console.log('SoC sync succeeded: ', synced);
    });
    

    Notifications

    After submitting the current state of charge, you may want to send out notifications, if the desired state of charge has been achieved. This process will NOT be automatically triggered, even when you set a soc threshold. The notification request will send the notifications to all available notification ways, which were available / enabled at the time of the request. If no notification way has been declared, no notification will be sent out, but also no error will be received.

    HTTPS Request

    POST https://evnotify.de:8743/notification

    URL Parameters

    Parameter Description
    akey The AKey of the account to send the notifications for
    token The token of the account
    curl "https://evnotify.de:8743/notification"
      -H "Content-Type: application/json"
      -X POST -d '{"akey":"akey","token":"token"}'
    

    The request returns JSON like this:

    {
      "message": "Notifications successfully sent"
    }
    
    var evnotify = new EVNotify();
    
    // sends all available notification types which are enabled for account
    evnotify.sendNotification(function(err, sent) {
      console.log('Notifications sent: ', sent);
    });