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
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
- Login Page is loaded
-
Method
GET -
URL
https://webauth.southernco.com/account/login
- Grab the
RequestVerificationToken
from the login Page
-
RequestVerificationToken
can be found at the bottom of the page in a script tag. Inside the tag theRequestVerificationToken
is assigned towebauth.aft
- 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'
-
-
- Grab the
ScWebToken
from the JSON response. Can be found in theresponse.data.html
as a value on a hidden input with the name ScWebToken - Grab the new
ScWebToken
from the set cookies from a secondary LoginComplete request. - 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.
-
Method
GET -
URL
https://customerservice2.southerncompany.com/Account/LoginValidated/JwtToken -
Headers
-
Cookie
ScWebToken=ScWebToken
-
- 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.