Node.js Library to access utility data from Southern Company power utilities (Alabama Power, Georgia Power, Gulf Power, Mississippi Power)
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode
src
tests
.gitignore
.travis.yml
LICENSE.md
README.md
jest.config.js
package.json
tsconfig.json
tslint.json
yarn.lock

README.md

Southern Company API

Travis Coveralls npm license

Example

/* Importing Library */
import {SouthernCompanyAPI} from 'southern-company-api';

/* Instantiating API */
const SouthernCompany = new SouthernCompanyAPI({
  username: 'username',
  password: 'password',
  accounts: ['123123123']
});

/* Listening for login success */
SouthernCompany.on('connected', ()=>{
  console.info('Connected...');

  /* Getting Monthly Data */
  const monthlyData = await SouthernCompany.getMonthlyData();

  /* Printing Monthly Data */
  console.info('Monthly Data', JSON.stringify(data));

  /* Getting Daily Data */
  const startDate = new Date(2017, 05, 01);
  const endDate = new Date();
  const dailyData = await SouthernCompany.getDailyData(startDate, endDate);

  /* Printing daily data */
  console.info('Daily Data', JSON.stringify(data));
});

/* 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. This 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.