Southern Company API

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

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