API Home
Data Only Access
The Wegowise Data API end points are intended for users who wish to retrieve data from utility providers without accessing the Wegowise web interface. These end points allow managment of meters without having to connect them to structures such as buildings and apartments. Only users who have an data only account may access the end points in this section. The data only user may not access any end points in the WegoPro and WegoHome sections. Any user may access the WegoPublic end points without authentication.
Please refer to the API Access and Authentication section in the WegoPro documentation for information on how to connect your application to the Wegowise API.
Meters
List meters
/api/v1/wego_data/meters
Get a list of meters that the authorized user has access to.
[
{
"account_number": "78734039A",
"coverage": "none",
"data_type": "Gas",
"id": 1,
"notes": "Some notes",
"utility_company":
{
"id": 1,
"name": "UtilityCo1"
}
},
{
"account_number": "78734039B",
"coverage": "none",
"data_type": "Electric",
"id": 2,
"notes": "Some notes",
"utility_company":
{
"id": 2,
"name": "UtilityCo2"
}
},
{
"account_number": "3244921",
"coverage": "none",
"data_type": "Water",
"id": 3,
"notes": "Some notes",
"utility_company":
{
"id": 3,
"name": "UtilityCo3"
}
}
]
View meter
/api/v1/wego_data/meters/{id}
Get information about a meter.
{
"coverage": "none",
"account_number": "78734039A",
"data_type": "Gas",
"id": 1,
"nickname": null,
"notes": "Some notes",
"utility_company":
{
"id": 1,
"name": "UtilityCo1"
}
}
{
"errors": "Meter not found"
}
Create a meter
/api/v1/wego_data/meters
Create a meter. When a username and password are provided for a utility company that supports imports a utility login will be created automatically for the meter and data will be imported. If one utility login is specified through the parameter utility_login_id then the username and password will be ignored and the specified utility login will be used. Meter data_type must be one of the following: Water, Electric, Gas, Oil, Oil4, Oil6, Steam, Propane, Solar, Trash.
Note: Either utility_company_id or other_utility_company must be specified. A list of utility companies can be found using the public utility companies end point.
{
"account_number": "123456789",
"utility_company_id": 231,
"username": "jane_smith",
"password": "pasword123",
"data_type": "Gas"
}
{
"type": "object",
"required": true,
"properties": {
"account_number": {
"type": "string",
"required": true
},
"data_type": {
"enum": [
"Electric",
"Gas",
"Oil",
"Water",
"Steam",
"Total_energy"
]
},
"nickname": {
"type": "string",
"required": false
},
"notes": {
"type": "string",
"required": false
},
"username": {
"type": "string"
},
"password": {
"type": "string"
},
"utility_company_id": {
"type": "string"
},
"other_utility_company": {
"type": "string"
},
"utility_login_id": {
"type": "string",
"required": false
}
}
}
{
"coverage": "none",
"account_number": "78734039A",
"data_type": "Gas",
"id": 1,
"nickname": null,
"notes": "Some notes",
"utility_company":
{
"id": 1,
"name": "UtilityCo1"
}
}
{
"errors": "Account number is invalid"
}
Update meter
/api/v1/wego_data/meters/{id}
Update a meter that can be edited by the authorized user.
{
"notes": "Some notes"
}
{
"coverage": "none",
"account_number": "78734039A",
"data_type": "Gas",
"id": 1,
"nickname": null,
"notes": "Some notes",
"utility_company":
{
"id": 1,
"name": "UtilityCo1"
}
}
{
"errors": "Account number is invalid"
}
Destroy a meter
/api/v1/wego_data/meters/{id}
This will destroy a meter that the authorized user has edit access to. The server will respond with status code 204 with no body if the meter is succesfully destroyed. If the meter is not found the server will respond with a 404.
It is important to note that destroying a meter cascades. Any associated data will be destroyed as well.
Utility Logins
When a username and password are provided for a utility company website, the login credentials are saved as a "utility login" which can be used by the application for automated importing of utility usage and cost data.
View login
/api/v1/wego_data/utility_logins/{id}
Get information about a utility login.
{
"id": 1,
"status": "success",
"username": "abcproperties",
"utility_company":
{
"name": "NSTAR"
},
"account_numbers": ["abc123", "xyz987"]
}
{
"errors": "UtilityLogin not found"
}
Possible statuse codes
- awaiting_import: Waiting to be imported.
- bad_login: Login doesn't work on utility company site.
- deferred: Waiting to retry import.
- in_progress: Import is running.
- inactive: Utility company flagged as inactive.
- no_accounts: No account numbers found on import.
- site_error: Utility site was down.
- success: Last import was successful.
Update utility login credentials
/api/v1/wego_data/utility_logins/{id}
Change credentials of an utility login.
{
type: "object",
required: true,
properties: {
username: {
type: "string",
required: false
},
password: {
type: "string",
required: false
}
}
}
{
"id": 11,
"status": "success",
"username": "new username",
"utility_company": {
"name": "utility company name"
},
"account_numbers": []
}
{
"errors": "Utility Login not found"
}
{
"username": [
"can't be blank"
]
}
Create an utility login
/api/v1/wego_data/utility_companies/{id}/utility_logins
A utility login is used by WegoWise to automatically import utility usage and cost data for any meters it is connected to.
Note: utility_company_id must be specified. A list of utility companies can be found using the public utility companies end point.
{
"username": "jane_smith",
"password": "pasword123"
}
{
"type": "object",
"required": true,
"properties": {
"username": {
"type": "string",
"required": true
},
"password": {
"type": "string",
"required": true
}
}
}
{
"id": 1,
"status": "success",
"username": "abcproperties",
"utility_company":
{
"name": "NSTAR"
},
"account_numbers": ["abc123", "xyz987"]
}
Delete an utility login
/api/v1/wego_data/utility_logins/{id}
Deletes utility login with the specified id.
{}
{
error: "UtilityLogin not found"
}
Raw Data
Raw data for a meter
/api/v1/wego_data/meters/{id}/raw_data
Retrieve a collection of datapoints for a given meter. This will return all raw data for a given meter, including datapoints manually added by users, as well as those imported from the utility company website where applicable. Data returned includes start and end dates, usage and cost figures.
[
{
"id": 1000,
"delivery_charge": null,
"end_date": "2014-01-31",
"fuel_charge": null,
"total_charge": "10.0",
"start_date": "2014-01-01",
"gallons": null,
"kwh": "0.292997363023733",
"btu": 1000,
"demand_charge": null,
"demand_kw": null,
"fixed_charge": null,
"late_charge": null,
"off_peak_charge": null,
"off_peak_kwh": null,
"peak_charge": null,
"peak_kwh": null
},
{
"id": 1001,
"delivery_charge": null,
"end_date": "2013-12-31",
"fuel_charge": null,
"total_charge": "10.0",
"start_date": "2013-12-01",
"gallons": null,
"kwh": "0.292997363023733",
"btu": 1000,
"demand_charge": null,
"demand_kw": null,
"fixed_charge": null,
"late_charge": null,
"off_peak_charge": null,
"off_peak_kwh": null,
"peak_charge": null,
"peak_kwh": null
}
]
{
"errors": "Meter not found"
}
Show a raw datapoint for a meter
/api/v1/wego_data/meters/{id}/raw_data/{id}
Show a single raw datapoint for a meter.
{
"id": 1,
"delivery_charge": "100.0",
"end_date": "2012-03-04",
"fuel_charge": null,
"total_charge": "500.0",
"start_date": "2012-02-01",
"gallons": null,
"kwh": "29.2997363023733",
"btu": 100000,
"demand_charge": null,
"demand_kw": null,
"fixed_charge": "80.0",
"late_charge": null,
"off_peak_charge": null,
"off_peak_kwh": null,
"peak_charge": null,
"peak_kwh": null
}
Show the latest raw datum for a meter
/api/v1/wego_data/meters/{id}/latest_datum
Show the latest raw datapoint for a meter.
{
"id": 1,
"delivery_charge": "100.0",
"end_date": "2012-03-04",
"fuel_charge": null,
"total_charge": "500.0",
"start_date": "2012-02-01",
"gallons": null,
"kwh": "29.2997363023733",
"btu": 100000,
"demand_charge": null,
"demand_kw": null,
"fixed_charge": "80.0",
"late_charge": null,
"off_peak_charge": null,
"off_peak_kwh": null,
"peak_charge": null,
"peak_kwh": null
}
Create a raw datapoint for a meter
/api/v1/wego_data/meters/{id}/raw_data
You create a raw datapoint by specifying a meter in the url and posting to the raw data end point as a user that is authorized to edit the meter.
Each type of meter (electric, gas, oil, propane, steam, and water) has its own raw datapoint type with common and specific fields. A request is listed for gas. Schemas for each of the different types of raw datapoint are listed below.
{
"start_date": "2012-02-01",
"end_date": "2012-03-04",
"btu": "100000",
"total_charge": "300.0",
"delivery_charge": "100.0",
"fixed_charge": "80.0"
}
[
{
"title": "Electric raw datum",
"type": "object",
"required": true,
"properties": {
"start_date": {
"type": "string",
"required": true
},
"end_date": {
"type": "string",
"required": true
},
"kwh": {
"type": "string",
"required": true
},
"total_charge": {
"type": "string",
"required": true
},
"delivery_charge": {
"type": "string",
"required": false
},
"fixed_charge": {
"type": "string",
"required": false
},
"fuel_charge": {
"type": "string",
"required": false
},
"demand_charge": {
"type": "string",
"required": false
},
"peak_charge": {
"type": "string",
"required": false
},
"late_charge": {
"type": "string",
"required": false
},
"off_peak_charge": {
"type": "string",
"required": false
},
"peak_kwh": {
"type": "string",
"required": false
},
"off_peak_kwh": {
"type": "string",
"required": false
},
"demand_kw": {
"type": "string",
"required": false
}
}
},
{
"title": "Gas raw datum",
"type": "object",
"required": true,
"properties": {
"start_date": {
"type": "string",
"required": true
},
"end_date": {
"type": "string",
"required": true
},
"btu": {
"type": "string",
"required": true
},
"total_charge": {
"type": "string",
"required": true
},
"delivery_charge": {
"type": "string",
"required": false
},
"fixed_charge": {
"type": "string",
"required": false
},
"fuel_charge": {
"type": "string",
"required": false
}
}
},
{
"title": "Oil raw datum",
"type": "object",
"required": true,
"properties": {
"start_date": {
"type": "string",
"required": true
},
"end_date": {
"type": "string",
"required": true
},
"btu": {
"type": "string",
"required": true
},
"total_charge": {
"type": "string",
"required": true
},
"delivery_charge": {
"type": "string",
"required": false
},
"fixed_charge": {
"type": "string",
"required": false
},
"fuel_charge": {
"type": "string",
"required": false
},
"gallons": {
"type": "string",
"required": false
}
}
},
{
"title": "Steam raw datum",
"type": "object",
"required": true,
"properties": {
"start_date": {
"type": "string",
"required": true
},
"end_date": {
"type": "string",
"required": true
},
"btu": {
"type": "string",
"required": true
},
"total_charge": {
"type": "string",
"required": true
},
"delivery_charge": {
"type": "string",
"required": false
},
"fixed_charge": {
"type": "string",
"required": false
},
"fuel_charge": {
"type": "string",
"required": false
},
"gallons": {
"type": "string",
"required": false
}
}
},
{
"title": "Water raw datum",
"type": "object",
"required": true,
"properties": {
"start_date": {
"type": "string",
"required": true
},
"end_date": {
"type": "string",
"required": true
},
"total_charge": {
"type": "string",
"required": true
},
"delivery_charge": {
"type": "string",
"required": false
},
"fixed_charge": {
"type": "string",
"required": false
},
"fuel_charge": {
"type": "string",
"required": false
},
"gallons": {
"type": "string",
"required": false
}
}
},
{
"title": "Propane raw datum",
"type": "object",
"required": true,
"properties": {
"start_date": {
"type": "string",
"required": true
},
"end_date": {
"type": "string",
"required": true
},
"btu": {
"type": "string",
"required": true
},
"total_charge": {
"type": "string",
"required": true
},
"delivery_charge": {
"type": "string",
"required": false
},
"fixed_charge": {
"type": "string",
"required": false
},
"fuel_charge": {
"type": "string",
"required": false
},
"gallons": {
"type": "string",
"required": false
}
}
}
]
{
"id": 1,
"delivery_charge": "100.0",
"end_date": "2012-03-04",
"fuel_charge": null,
"total_charge": "500.0",
"start_date": "2012-02-01",
"gallons": null,
"kwh": "29.2997363023733",
"btu": 100000,
"demand_charge": null,
"demand_kw": null,
"fixed_charge": "80.0",
"late_charge": null,
"off_peak_charge": null,
"off_peak_kwh": null,
"peak_charge": null,
"peak_kwh": null
}
{
"errors": "Must specify usage or total cost"
}
Update a raw datapoint for a meter
/api/v1/wego_data/meters/{id}/raw_data/{id}
In order to update a datapoint datapoint it is necessary to specify both the meter id and raw datapoint id in the PUT request url. The schema is the same for creating and updating a raw datapoint. Manually entered raw data may be updated by the automatic importer if a utility login has been created for a meter.
{
"start_date": "2012-02-01",
"end_date": "2012-03-04",
"btu": "100000",
"total_charge": "300.0",
"delivery_charge": "100.0",
"fixed_charge": "80.0"
}
[
{
"title": "Electric raw datum",
"type": "object",
"required": true,
"properties": {
"start_date": {
"type": "string",
"required": true
},
"end_date": {
"type": "string",
"required": true
},
"kwh": {
"type": "string",
"required": true
},
"total_charge": {
"type": "string",
"required": true
},
"delivery_charge": {
"type": "string",
"required": false
},
"fixed_charge": {
"type": "string",
"required": false
},
"fuel_charge": {
"type": "string",
"required": false
},
"demand_charge": {
"type": "string",
"required": false
},
"peak_charge": {
"type": "string",
"required": false
},
"late_charge": {
"type": "string",
"required": false
},
"off_peak_charge": {
"type": "string",
"required": false
},
"peak_kwh": {
"type": "string",
"required": false
},
"off_peak_kwh": {
"type": "string",
"required": false
},
"demand_kw": {
"type": "string",
"required": false
}
}
},
{
"title": "Gas raw datum",
"type": "object",
"required": true,
"properties": {
"start_date": {
"type": "string",
"required": true
},
"end_date": {
"type": "string",
"required": true
},
"btu": {
"type": "string",
"required": true
},
"total_charge": {
"type": "string",
"required": true
},
"delivery_charge": {
"type": "string",
"required": false
},
"fixed_charge": {
"type": "string",
"required": false
},
"fuel_charge": {
"type": "string",
"required": false
}
}
},
{
"title": "Oil raw datum",
"type": "object",
"required": true,
"properties": {
"start_date": {
"type": "string",
"required": true
},
"end_date": {
"type": "string",
"required": true
},
"btu": {
"type": "string",
"required": true
},
"total_charge": {
"type": "string",
"required": true
},
"delivery_charge": {
"type": "string",
"required": false
},
"fixed_charge": {
"type": "string",
"required": false
},
"fuel_charge": {
"type": "string",
"required": false
},
"gallons": {
"type": "string",
"required": false
}
}
},
{
"title": "Steam raw datum",
"type": "object",
"required": true,
"properties": {
"start_date": {
"type": "string",
"required": true
},
"end_date": {
"type": "string",
"required": true
},
"btu": {
"type": "string",
"required": true
},
"total_charge": {
"type": "string",
"required": true
},
"delivery_charge": {
"type": "string",
"required": false
},
"fixed_charge": {
"type": "string",
"required": false
},
"fuel_charge": {
"type": "string",
"required": false
},
"gallons": {
"type": "string",
"required": false
}
}
},
{
"title": "Water raw datum",
"type": "object",
"required": true,
"properties": {
"start_date": {
"type": "string",
"required": true
},
"end_date": {
"type": "string",
"required": true
},
"total_charge": {
"type": "string",
"required": true
},
"delivery_charge": {
"type": "string",
"required": false
},
"fixed_charge": {
"type": "string",
"required": false
},
"fuel_charge": {
"type": "string",
"required": false
},
"gallons": {
"type": "string",
"required": false
}
}
},
{
"title": "Propane raw datum",
"type": "object",
"required": true,
"properties": {
"start_date": {
"type": "string",
"required": true
},
"end_date": {
"type": "string",
"required": true
},
"btu": {
"type": "string",
"required": true
},
"total_charge": {
"type": "string",
"required": true
},
"delivery_charge": {
"type": "string",
"required": false
},
"fixed_charge": {
"type": "string",
"required": false
},
"fuel_charge": {
"type": "string",
"required": false
},
"gallons": {
"type": "string",
"required": false
}
}
}
]
{
"id": 1,
"delivery_charge": "100.0",
"end_date": "2012-03-04",
"fuel_charge": null,
"total_charge": "500.0",
"start_date": "2012-02-01",
"gallons": null,
"kwh": "29.2997363023733",
"btu": 100000,
"demand_charge": null,
"demand_kw": null,
"fixed_charge": "80.0",
"late_charge": null,
"off_peak_charge": null,
"off_peak_kwh": null,
"peak_charge": null,
"peak_kwh": null
}
{
"errors": "Must specify usage or total cost"
}
Destroy a raw datapoint
/api/v1/wego_data/meters/{id}/raw_data/{id}
This will destroy a raw datapoint for a meter that the authorized user has edit access to. The server will respond with status code 204 with no body if the datapoint is succesfully destroyed. If the datapoint is not found the server will respond with a 404.