Wattzon Link API 4.0 Documentation

WattzOn Link API Documentation

WattzOn Link is a software-as-a-service (SaaS) platform for retrieving billing and usage data from utility providers. This document describes the individual Link API calls and their features.

Definitions

Agent
The WattzOn software tailored to one particular utility provider that performs data extraction.
Client
The software interacting with the WattzOn Link API.
LSE ID
Load Serving Entity (electricity provider) identification number.
Job
One particular data-extraction run.
Profile
A data record corresponding to one customer of a utility provider.
Sensitive Field
The mechanism used to store account credentials.
Provider
A utility provider.

Service Introduction

Typical API use is a multistep process. For any desired data extraction, the client performs the following steps:

Look up the target utility provider.
Create a profile for the utility provider's customer.
Initiate data extraction job and wait for completion (or for there to be enough data available).
Fetch data.

Each one of these steps may involve multiple API calls. Therefore, the Link API is broken into the following service categories that correspond to the above steps:

ZIP Information Service
Look up ZIP code information based on the ID, see location information, such as latitude, longitude, city, county, etc.
Utility and Agent Information Service
Look up utility providers based on ZIP code, see utility provider information, and check agent availability.
Profile Service
Create, modify, and delete profiles for customers of utility providers.
Extraction Service
Initiates data extraction jobs and checks status of these jobs.
Data Retrieval Service
Looks up usage and billing data for a profile or particular job.

Profiles

A profile is a record for one account login on a utility provider. It includes indexing and identifying information as well as account credentials.

Basic profile information includes the following:

Profile ID: A unique integer (much like a primary key in a database). The API assigns a new Profile ID upon profile creation.
Utility Provider ID: The utility provider for this profile (acquired with Utility and Agent Information service API calls).
Label: An arbitrary text field. This is available for profile lookup, so clients can use this field to reference profiles based on their own internal tracking system (such as a Salesforce case ID). The label can be empty.
Tags: An arbitrary list of text strings for grouping and searching. Examples could include "solar" and "budget billing".
ZIP Code: ZIP code of the service location. Can be empty, and does not necessarily need to be correct (for example, one utility site login can have more than one service line in multiple ZIP codes; this will not be important).

A profile's account credentials are stored in sensitive fields, which are key-value pairs. These fields are write-only in the API: Clients can set and delete keys and values, and read keys, but are unable to read values. The agents for most utility providers require these two sensitive fields:

username: The username on the utility site.
password: The password on the utility site.

There are separate API calls for working with sensitive fields in a profile.

Authentication

All client identification and authorization is through a client-side TLS certificate. You do not need to purchase a certificate; WattzOn will act as a certificate authority for its own application. The procedure is as follows:

Generate a CSR (certificate signing request). Here's how to do it with openssl:

openssl req -new -newkey rsa:2048 -nodes -keyout client.key -out client.csr

Don't enter a challenge password. This creates two files: client.csr (the CSR) and client.key (the private key).

Send the CSR to your WattzOn technical or sales contact. Do NOT send the private key; keep it secret.
WattzOn will sign the CSR and send you a certificate named client.crt. You can now use this in conjunction with your private key (client.key) to connect to the Link API. However, depending on your client software, you may need to perform another step to create a combined certificate-key file.

The WattzOn Python reference client needs no additional steps; it can use client.crt and client.key directly.
Some HTTPS clients may require a .pfx/.pf12 file, a DER file, or another format. OpenSSL can convert to these formats.

Use Implications of Authentication

The core Link API is designed to be accessed by systems under the direct control of the customer; it is not meant to be consumed directly by web browsers. Client-side certificates are the practical means to enforce this; they are essential to the security of the system.

As such, the core Link API does not authenticate at the individual profile ("end user") level; this is the responsibility of the customer (and indeed, each customer has their own form of authentication and identification for their own end users). However, WattzOn can assist in developing user interface products that build upon the core API to integrate with a customer's end-user authentication.

Getting Started

Typical use of WattzOn Link involves of the following steps:

Create a profile for a utility provider customer.
Initiate a data extraction job.
Wait for the extraction job to complete, or until the agent has extracted enough utility data.
Retrieve the utility data.

For steps 1-3, many WattzOn Link customers opt to use the WattzOn 3in1 product to create profiles and start extraction jobs. This greatly simplifies implementation, because you need only implement step 4; retrieving data after an extraction is a single Link API call.

Let's go through the process of creating a profile with the WattzOn Mock Utility Provider and Mock Agent, a tool for testing your implementation without accessing a true utility provider.

If you need to test your API connection, see Testing API Connectivity.

Creating a Profile

For WattzOn 3in1 customers, choose the "Link Your Data" button in the 3in1 interface to bring up the linking user interface, then:

For ZIP code, enter 00007. You'll get a list of utility providers.
Choose "Mock Utility Provider (electric+gas)" from the list.
Enter anything you like for username and password.
Review your information, then link the account.
You're done! Skim the few sections for a quick look behind the scenes, and pick up again at Retrieving Data.

Note: The Mock Agent includes special diagnostic features that you can enable by entering specific values for the username; we can provide Mock Agent documentation for details.

To create a profile with the API, you need to enter a ZIP code and a utility provider. You can look up utility providers by ZIP code or name using the Find Utility Provider endpoint. In this case, we'll use the ZIP code 00007 and the utility provider ID 3149, which is the WattzOn Mock Utility Provider.

Create the profile with the following request:

Method: POST; Endpoint: /link/4.0/profiles/

Data:

{
    "provider_id": 3150,
    "zipcode": "00007",
    "label": "your label"
}

Result:

{
  "id": 516,
  "label": "this is optional",
  "utility_provider": "Mock Utility (electric only)",
  "utility_provider_id": 3150,
  "zipcode": "00007"
}

A successful profile creation like this returns a profile_id field; you'll need to know that later. In this example, the ID of the new profile is 516.

Setting Credentials with Sensitive Fields

Most utility agents need credentials (specifically, username and password) for a user's account in order to function. These are known as sensitive fields in the Link API. Using these is one of the more complicated pieces of the API, because you must first get an encryption key through the API (even though the service runs over TLS), and then encrypt the data before sending.

Note: Remember that if you're using WattzOn 3in1, you don't need to use the API for this! You can skip ahead to the data extraction.

For example, to set sensitive field, get a public encryption key with this API call:

Method: GET; Endpoint: /link/4.0/profiles/keys/

Result:

{
  "expires": 1476901022,
  "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBI [bytes omitted] QAB\n-----END PUBLIC KEY-----"
}

Now, using this public encryption key, use PKCS1/OAEP to encrypt the actual value that you're transmitting, and base64-encode the encrypted value. Here's the API call to set the username sensitive field for the profile_id from the previous example (516):

Method: POST; Endpoint: /link/4.0/profiles/516/sensitive/

Data:

{
    "field": "username",
    "value": "BIKJ3IkC1B [bytes omitted] SYxi8boLMX7QQ5K47GI+AQirwg=="
}

Result:

{
  "message": "Success"
}

This endpoint is fairly restrictive; it will not allow encrypted values with expired keys (a 403 error), and will not overwrite an existing key-value pair (a 409 error). If you need to change a field, remove the old one first.

Most profiles require two sensitive fields in order for their agents to function correctly: username and password. Sensitive fields are write-only; you cannot retrieve their values through the API.

Initiating a Data Extraction Job

For WattzOn 3in1 customers, the interface starts a data extraction job immediately after the user clicks the Link button after entering their utility provider information. When the job completes, 3in1 sends a notification (see the Retrieving Data section).

In our ongoing example using the profile ID 516, use the following API call to start a data extraction job with the API.

Method: POST; Endpoint: /link/4.0/jobs/

Data:

{
    "profile_id": 516,
    "mode": "bill"
}

Result:

{
  "job_id": "3b7471eb-7e35-4a45-b081-e9cfa9d71e75",
  "profile_id": 1
}

Note the job ID return value. You can check up on the job with the following API call:

Method: GET; Endpoint: /link/4.0/jobs/3b7471eb-7e35-4a45-b081-e9cfa9d71e75/

Result:

{
  "finished": true,
  "job_id": "3b7471eb-7e35-4a45-b081-e9cfa9d71e75",
  "job_status": "AgentState.success"
}

You can make this call periodically to see how an agent is progressing. When the agent has completed, the endpoint's finished field will be true. (Note that many agents can make data available before finishing.)

Retrieving Data

You need a profile ID in order to retrieve data. WattzOn 3in1 customers typically get a notification of profile creation through SQS or another system; this notification includes the profile ID.

Here's the API call to fetch the utility data for profile ID 516:

Endpoint: /link/4.0/data/bills/516/

Result:

[
  {
    "account_number": "42626522-7",
    "bill_id": "580167d10640fd48ff1960bf",
    "cost": 21.25,
    "currency": "USD",
    "end_date": "2016-10-31T23:59:59",
    "meter_number": "67563764",
    "name": "J. Random Person",
    "pdf": "/link/4.0/data/bills/1/580167d10640fd48ff1960bf/pdf",
    "service_address": "123 J. Random Road, Randomtown, RI 00007",
    "service_id": "353267363254",
    "start_date": "2016-10-01T00:00:00",
    "type": "gas",
    "units": "therms",
    "usage": 13.72
  }
]

By default, the data retrieval call returns all utility data for a profile, regardless of the job that extracted the data.

Testing API Connectivity

The WattzOn Link API includes an echo service for testing API connectivity. The service simply repeats anything sent to it. You can either send the request using POST parameters or GET query parameters.

Endpoint: /link/4.0/echo?string=value

Data:

{
    "string": "value"
}

Result:

{
    "string": "value"
}

API Resource Specifications

General Requirements

The Link API uses JSON as a serialization format. As such, it requires no specific software to use. Authentication and communication proceed over TLS; clients must present a certificate.

One step in creating a profile requires transmission of sensitive information to the API. Clients must encrypt this information using a public-key algorithm before transmission.

Rate limit

The Link API enforces a rate limit on resource intensive endpoints in order to keep our servers responsive at all times. The current rate limit is set at 400 requests per hour.

Rate limiting works in a sliding-window fashion, i.e., it considers the amount of requests made in the last hour at any given moment. For example, suppose you make 400 requests in the first minute of a given hour (0:00), you won't able to make more requests until you hit the 1:01 mark.

Any rate limited endpoint will be highlighted across the documentation.

Base URL

For most customers, the base URL for the Link is:

https://api.wattzon.com/

About the Examples

This document contains a number of curl command line examples to assist in understanding the API parameters. However, these are useful only to a certain degree, as some parts (in particular, the sensitive parameter endpoints) are too lengthy to show with a short command line.

An alternative for experimenting with the API is a scripting language with a command line interface. For instance, WattzOn uses the interactive Python interpreter with the requests library to develop the reference client.

Basic Services

Base path: /link/4.0/

Echo

path: /link/4.0/echo/

methods: POST, GET

Query Parameters

string: any string

Body Parameters

string: any string

Output

string: the string that was on the original request