Nefarious Planetary Meddling
    Wondering what’s next for npm?Check out our public roadmap! »

    southern-company-api
    TypeScript icon, indicating that this package has built-in type declarations

    2.1.5 • Public • Published

    Southern Company API

    Travis Coveralls npm license

    Node.js Library to access utility data from Southern Company power utilities (Alabama Power, Georgia Power, Gulf Power, Mississippi Power)

    In search of testers with active accounts not in a time of use plan.
    No coding required, just need to verify API responses. Open an issue if you would like to help.

    Example

    /* Importing Library */
    import {SouthernCompanyAPI} from 'southern-company-api';
    /* Or requiring for a script */
    var SouthernCompanyAPI = require('../southern-company-api').SouthernCompanyAPI;
    
    /* Instantiating API */
    const SouthernCompany = new SouthernCompanyAPI({
      username: 'username',
      password: 'password',
      accounts: ['123123123']
    });
    
    /* Listening for login success */
    SouthernCompany.on('connected', ()=>{
      console.info('Connected...');
    
      async function fetchMonthly() {
        /* Getting Monthly Data */
        const monthlyData = await SouthernCompany.getMonthlyData();
    
        /* Printing Monthly Data */
        console.info('Monthly Data', JSON.stringify(monthlyData));
      }
      fetchMonthly();
    
      async function fetchDaily() {
        /* Getting Daily Data */
        const startDate = new Date(2020, 2, 1);
        const endDate = new Date();
        const dailyData = await SouthernCompany.getDailyData(startDate, endDate);
    
        /* Printing daily data */
        console.info('Daily Data', JSON.stringify(dailyData));
      }
      fetchDaily();
    });
    
    /* Listening for any errors */
    SouthernCompany.on('error', console.error);

    API

    Login

    Login by passing username and password as a config object when instantiating.

    /* Instantiating API */
    const API = new SouthernCompanyAPI({
      username: 'username',
      password: 'password'
    });

    Events

    The instantiated object extends the EventEmitter class built into node. To listen for events use the .on(eventName, listener) method.

    Current Events:

    • connected (On connection success)
    • reconnected (On reconnection success)
    • error (On login failure)
    /* Listening for connection success */
    API.on('connected', ()=>{
      console.info('Connected...');
    });
    
    /* Listening for connection success */
    API.on('reconnected', ()=>{
      console.info('Reconnected...');
    });
    
    
    /* Listening for any errors */
    API.on('error', (error)=>{
      console.error('An error occured', error);
    });

    Data methods

    getMonthlyData()

    Description This method collects all monthly data on all accounts from the time they were opened to the last complete month of data.

    Arguments

    • None

    Returns

    • Promise

    Promise Return

    • data Each index of array is an account retrieved
      • name Name of the account
      • accountNumber Account number
      • data Each object of array is a month of data
        • date M/YYYY of data
        • cost Total energy cost for the month
        • kWh Total amount of kWh used during the month
        • bill Amount billed for the month
    • error Description of error

    Example

    /* Getting Monthly Data */
    const monthlyData = await API.getMonthlyData();
    
    /* Printing monthly data */
    console.info('Monthly Data', JSON.stringify(monthlyData));
    
    /* Result */
    [{
      "name":"Apartment",
      "accountNumber":0000000000,
      "data":[
        {"date":"2017-03-01T06:00:00.000Z","cost":66.66,"kWh":416,"bill":87},
        {"date":"2017-04-01T06:00:00.000Z","cost":62.23,"kWh":380,"bill":87},
        {"date":"2017-05-01T06:00:00.000Z","cost":65.42,"kWh":406,"bill":87}
      ]
    }]

    getDailyData()

    Description This method collects daily data from the startDate provided to the endDate provided.

    Arguments

    • startDate First date (Date) to include in collection
    • endDate Last date (Date) to include in collection

    Returns

    • Promise

    Promise Return

    • data Each index of array is an account retrieved
      • name Name of the account
      • accountNumber Account number
      • data Each object of array is a month of data
        • date M/D/YYYY of data
        • cost Total energy cost for the date
        • kWh Total amount of kWh used during the date

    Example

    /* Getting Daily Data */
    const startDate = new Date(2017, 05, 01);
    const endDate = new Date(2017, 05, 02);
    const dailyData = await SouthernCompany.getDailyData(startDate, endDate);
    
    /* Printing daily data */
    console.info('Daily Data', JSON.stringify(data));
    
    /* Result */
    [{
      "name":"Apartment",
      "accountNumber": 0000000000,
      "data":[
        {"date":"2017-05-01T06:00:00.000Z", "cost":2.17, "kWh":12.76},
        {"date":"2017-05-02T06:00:00.000Z", "cost":77, "kWh":77}
      ]
    }]

    How Authentication Works

    1. Login Page is loaded
    1. Grab the RequestVerificationToken from the login Page
    • RequestVerificationToken can be found at the bottom of the page in a script tag. Inside the tag the RequestVerificationToken is assigned to webauth.aft
    1. Login Request is initialized
    • Method POST
    • URL https://webauth.southernco.com/api/login
    • Headers
      • RequestVerificationToken: RequestVerificationToken
      • Content-Type: application/json
    • Body (JSON Object):
      • username: username
      • password: password
      • params
        • ReturnUrl 'null'
    1. Grab the ScWebToken from the JSON response. Can be found in the response.data.html as a value on a hidden input with the name ScWebToken
    2. Grab the new ScWebToken from the set cookies from a secondary LoginComplete request.
    3. This secondary Southern Company Web Token can be traded in for a Southern Company JSON Web Token (ScJwtToken) that can be used with the API.
    1. Grab the ScJwtToken from the response's cookies
    • Cookie's name is ScJwtToken and contains the ScJwtToken
    • This ScJwtToken can be used to authenticate all other API requests.

    Keywords

    none

    Install

    npm i southern-company-api

    DownloadsWeekly Downloads

    7

    Version

    2.1.5

    License

    MIT

    Unpacked Size

    46.6 kB

    Total Files

    15

    Last publish

    Collaborators

    • avatar