Skip to content
master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Southern Company API

Github Actions Coveralls npm license

Node.js Library to access utility data from Southern Company power utilities (Alabama Power, Georgia 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.

About

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

Resources

License

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •