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

GET
/api/v1/wego_data/meters

Get a list of meters that the authorized user has access to.

200 response

[
  {
    "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

GET
/api/v1/wego_data/meters/{id}

Get information about a meter.

200 response

{
  "coverage": "none",
  "account_number": "78734039A",
  "data_type": "Gas",
  "id": 1,
  "nickname": null,
  "notes": "Some notes",
  "utility_company":
    {
      "id": 1,
      "name": "UtilityCo1"
    }
}

404 response

{
  "errors": "Meter not found"
}

Create a meter

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

Request body

{
  "account_number": "123456789",
  "utility_company_id": 231,
  "username": "jane_smith",
  "password": "pasword123",
  "data_type": "Gas"
}

Schema

{
  "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
    }
  }
}

200 response

{
  "coverage": "none",
  "account_number": "78734039A",
  "data_type": "Gas",
  "id": 1,
  "nickname": null,
  "notes": "Some notes",
  "utility_company":
    {
      "id": 1,
      "name": "UtilityCo1"
    }
}

400 response

{
  "errors": "Account number is invalid"
}

Update meter

PUT
/api/v1/wego_data/meters/{id}

Update a meter that can be edited by the authorized user.

Request body

{
  "notes": "Some notes"
}

200 response

{
  "coverage": "none",
  "account_number": "78734039A",
  "data_type": "Gas",
  "id": 1,
  "nickname": null,
  "notes": "Some notes",
  "utility_company":
    {
      "id": 1,
      "name": "UtilityCo1"
    }
}

400 response

{
  "errors": "Account number is invalid"
}

Destroy a meter

DELETE
/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

GET
/api/v1/wego_data/utility_logins/{id}

Get information about a utility login.

200 response

{
  "id": 1,
  "status": "success",
  "username": "abcproperties",
  "utility_company":
    {
      "name": "NSTAR"
    },
  "account_numbers": ["abc123", "xyz987"]
}

404 response

{
  "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

PATCH
/api/v1/wego_data/utility_logins/{id}

Change credentials of an utility login.

Schema

{
  type: "object",
  required: true,
  properties: {
    username: {
      type: "string",
      required: false
    },
    password: {
      type: "string",
      required: false
    }
  }
}
200 response

{
    "id": 11,
    "status": "success",
    "username": "new username",
    "utility_company": {
        "name": "utility company name"
    },
    "account_numbers": []
}
404 response

{
  "errors": "Utility Login not found"
}
422 response

{
  "username": [
    "can't be blank"
  ]
}

Create an utility login

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

Request body

{
  "username": "jane_smith",
  "password": "pasword123"
}

Schema

{
  "type": "object",
  "required": true,
  "properties": {
    "username": {
      "type": "string",
      "required": true
    },
    "password": {
      "type": "string",
      "required": true
    }
  }
}

200 response

{
  "id": 1,
  "status": "success",
  "username": "abcproperties",
  "utility_company":
    {
      "name": "NSTAR"
    },
  "account_numbers": ["abc123", "xyz987"]
}

Delete an utility login

POST
/api/v1/wego_data/utility_logins/{id}

Deletes utility login with the specified id.

204 response

{}

404 response

{
  error: "UtilityLogin not found"
}

Raw Data

Raw data for a meter

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

200 response

[
  {
    "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
  }
]

404 response

{
  "errors": "Meter not found"
}

Show a raw datapoint for a meter

GET
/api/v1/wego_data/meters/{id}/raw_data/{id}

Show a single raw datapoint for a meter.

200 response

{
  "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

GET
/api/v1/wego_data/meters/{id}/latest_datum

Show the latest raw datapoint for a meter.

200 response

{
  "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

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

Request body

{
  "start_date": "2012-02-01",
  "end_date": "2012-03-04",
  "btu": "100000",
  "total_charge": "300.0",
  "delivery_charge": "100.0",
  "fixed_charge": "80.0"
}

Schema

[
  {
    "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
      }
    }
  }
]

200 response

{
  "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
}

400 response

{
  "errors": "Must specify usage or total cost"
}

Update a raw datapoint for a meter

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

Request body

{
  "start_date": "2012-02-01",
  "end_date": "2012-03-04",
  "btu": "100000",
  "total_charge": "300.0",
  "delivery_charge": "100.0",
  "fixed_charge": "80.0"
}

Schema

[
  {
    "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
      }
    }
  }
]

200 response

{
  "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
}

400 response

{
  "errors": "Must specify usage or total cost"
}

Destroy a raw datapoint

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