API Home

API Access & Authentication

With the exception of public API endpoints, requests to the WegoWise API must be authenticated. WegoWise authenticates these requests using the OAuth 1.0 protocol. OAuth client libraries are available for numerous programming languages.

Step 1: Register App

To make authenticated requests to the WegoWise API, you must first register your app with WegoWise. You must have an active WegoWise user account to register an app. Registered apps are given authentication credentials consisting of a consumer key and a consumer secret, which will be used in subsequent steps when generating OAuth headers.

Consumer Credentials

Step 2: Request Temporary Credentials

Your app will need to send a POST request to https://www.wegowise.com/oauth/request_token which includes the appropriate OAuth authorization header . An example header is shown below. 


Authorization:
OAuth oauth_consumer_key="17547cfc0b45bf1f7ca17eee86318af35103b4ce",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1395088838",
oauth_nonce="867c4716a81e236c4671e3f82098b6f8",
oauth_version="1.0",
oauth_callback="http%3A%2F%2Fexample.com%2Fcallback",
oauth_signature="Mc%2B2WEdHD5AsbDP5NsgVRYVwKXo%3D"

WegoWise will return a url-encoded response with the temporary token credentials in the response body

oauth_token=a5f5e9d2a3911a048b467bce3ad577a5cb64402c&oauth_token_secret=cfe39d9b5fb6b8617e5c633da1ec23c9f993c676&oauth_callback_confirmed=true

Step 3: Obtain User Authorization

Access token credentials are specific to the WegoWise user who is using your app. After successfully obtaining temporary credentials, your app should direct users to WegoWise so they can grant permission for your app to access their resources. Given the above temporary credential response, you would send the user to https://www.wegowise.com/oauth/authorize?oauth_token=a5f5e9d2a3911a048b467bce3ad577a5cb64402c , where they will be prompted to authorize your app. Ensure that you attach the oauth_token parameter to the URL as shown above as well as the authorization header.

Authorize app

After the user authorizes the app, WegoWise will redirect the user to the callback URL you established when the app was registered with WegoWise. An oauth_verifier string will have been appended to the URL. Your app will include that verifier in the next step.

Step 4: Request Access Token Credentials

The final step involves sending a POST request to https://www.wegowise.com/oauth/access_token. This request will include the appropriate OAuth authorization header for an OAuth token credential request. An example header is shown below. 


Authorization:
OAuth oauth_consumer_key="17547cfc0b45bf1f7ca17eee86318af35103b4ce",
oauth_token="a5f5e9d2a3911a048b467bce3ad577a5cb64402c",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1395087547",
oauth_nonce="b4c399fb4d05bd186895e0ee1c886271",
oauth_verifier="d830f350d1d0099e6fc6",
oauth_version="1.0",
oauth_signature="NrHElhluZZSRjXOPC6uaRHZvkVM%3D"

WegoWise will return a url-encoded response with the token credentials in the response body.

oauth_token=d01533fc7c157566aa53cb3b8f80bbfa85bec356&oauth_token_secret=e6592fe3c77653a5d6d1112c51d2edac0b694340

Once you have the access token credentials you will be able to request protected resources using the access token credentials for the user who granted access. You will need to repeat steps 2 through 4 for each WegoWise user your app needs to access resources for.

Examples

Node.js Example


var oauth = require('oauth-client');

var consumer = oauth.createConsumer('CONSUMER_KEY', 'CONSUMER_SECRET');
var token = oauth.createToken('ACCESS_TOKEN_KEY', 'ACCESS_TOKEN_SECRET');
var signature = oauth.createHmac(consumer, token);

var request_options = {
    port: '443',
    host: 'www.wegowise.com',
    https: true,
    path: '/api/v1/users/USERNAME/buildings/ID?sqft=194000&has_elevator=false',
    oauth_signature: signature,
    method: 'PUT',
    headers: { 'content-type': 'application/json' }
}

var request = oauth.request(request_options, function(response) {
    response.setEncoding('utf8');
    response.on('data', function (chunk) {
        console.log(chunk);
    });
});

request.end();

OAuth

View OAuth User

GET
/oauth/user

Get information about the user whose access token is being used to request authenticated resources

200 response

{
  "id": "1",
  "username": "johndoe"
}

Users

Create a single family home user

post
/api/v1/wego_home/users

You will create the new user using your own OAuth-authorized WegoWise user account. Because the developer is acting on behalf of the user, the new user is created with an OAuth secret and key already generated. The secret and key are passed back in the successful response message. You must store the secret and key in your system and use these to make subsequent requests affecting this user.

Developers may wish to use the JSON Schema Lint website to validate requests against the schema defined below.

Request body

{
  "email": "newuser@example.com",
  "first_name": "New",
  "last_name": "User",
  "username": "newuser",
  "password": "s3kr3+"
}
Schema

{
  "type": "object",
  "required": true,
  "properties": {
    "email": {
      "type": "string",
      "required": true
    },
    "first_name": {
      "type": "string",
      "required": true
    },
    "last_name": {
      "type": "string",
      "required": true
    },
    "username": {
      "type": "string",
      "required": true
    },
    "password": {
      "type": "string",
      "required": true
    }
  }
}
200 response

{
    "id": 123,
    "oauth_token_secret": "{string of characters}",
    "oauth_token_key": "{string of characters}"
}
400 response

{
    "errors": "Username can't be blank"
}

Destroy home user

DELETE
/api/v1/wego_home/user

This will destroy the current OAuth-authorized user. The server will respond with status code 204 with no body.

Building

Create a building for a user

POST
/api/v1/wego_home/buildings

One building can be created for each home user. The building is created by doing a POST request to the homes/buildings end point using the building owners authorization information.

Request body

{
  "address": "123 Main St, Boston, MA 02118",
  "nickname": "Main Street Apartments",
  "building_type": "sf_detached",
  "year_built": "2000",
  "construction": "wood_steel",
  "sqft": "1000",
  "has_basement": true,
  "basement_sqft": "200",
  "basement_conditioned": false,
  "n_stories": 2,
  "n_bedrooms": 12,
  "green_certified": false,
  "n_electric_general_meters": 1,
  "n_water_general_meters": 1,
  "n_gas_general_meters": 1,
  "n_oil_general_meters": 0,
  "heating_system": "furnace",
  "heating_fuel": "Gas",
  "cooling_system": "window_ac",
  "hot_water_fuel": "Solar",
  "hot_water_system": "other",
  "has_pool": false,
  "has_laundry": false,
  "notes": "notes",
  "draft": false
}
Schema

{
  "type": "object",
  "required": true,
  "properties": {
    "address": {
      "type": "string",
      "required": true
    },
    "nickname": {
      "type": "string",
      "required": true
    },
    "building_type": {
      "enum": [
      "sf_detached",
      "sf_attached",
      "apt_condo",
      "mobile_home"
      ],
      "required": true
    },
    "year_built": {
      "type": "string",
      "required": true
    },
    "construction": {
      "enum": [
      "wood_steel",
      "concrete",
      "masonry",
      "modular",
      "sips",
      "other"
      ],
      "required": true
    },
    "sqft": {
      "type": "integer",
      "required": true
    },
    "has_basement": {
      "type": "boolean",
      "required": true
    },
    "basement_sqft": {
      "type": "integer",
      "required": true
    },
    "basement_conditioned": {
      "type": "boolean",
      "required": true
    },
    "n_stories": {
      "type": "integer",
      "required": true
    },
    "n_bedrooms": {
      "type": "integer",
      "required": true
    },
    "green_certified": {
      "type": "boolean",
      "required": true
    },
    "leed_certified": {
      "type": "boolean",
      "required": true
    },
    "epa_certified": {
      "type": "boolean",
      "required": true
    },
    "nahb_certified": {
      "type": "boolean",
      "required": true
    },
    "other_certified": {
      "type": "boolean",
      "required": true
    },
    "leed_level": {
      "type": "integer",
      "required": true
    },
    "n_water_general_meters": {
      "type": "integer",
      "required": true
    },
    "n_electric_general_meters": {
      "type": "integer",
      "required": true
    },
    "n_gas_general_meters": {
      "type": "integer",
      "required": true
    },
    "n_oil_general_meters": {
      "type": "integer",
      "required": true
    },
    "heating_system": {
      "enum": [
      "furnace",
      "h_e_furnace",
      "steam_boiler",
      "hot_water_boiler",
      "h_e_boiler",
      "apt_heat_pumps",
      "ground_heat_pump",
      "air_heat_pump",
      "hot_water",
      "h_e_hot_water",
      "baseboard",
      "ptac",
      "other"
      ],
      "required": true
    },
    "heating_fuel": {
      "enum": [
      "Electric",
      "Gas",
      "Oil"
      ],
      "required": true
    },
    "cooling_system": {
      "enum": [
      "window_ac",
      "sleeve",
      "mini_split",
      "ptac",
      "central",
      "rooftop",
      "ground_heat_pump",
      "tower_heat_pump",
      "air_chiller",
      "water_chiller",
      "none",
      "other"
      ],
      "required": true
    },
    "hot_water_fuel": {
      "enum": [
      "Electric",
      "Gas",
      "Oil"
      ],
      "required": true
    },
    "hot_water_system": {
      "enum": [
      "indirect_with_heat",
      "indirect_boiler",
      "tankless_coil",
      "stand_alone",
      "on_demand",
      "cogen",
      "other"
      ],
      "required": true
    },
    "has_laundry": {
      "type": "boolean",
      "required": true
    },
    "dryer_fuel": {
      "enum": [
      "Electric",
      "Gas"
      ],
      "required": false
    },
    "has_pool": {
      "type": "boolean",
      "required": true
    },
    "pool_year_round": {
      "type": "boolean",
      "required": false
    },
    "pool_fuel": {
      "enum": [
      "none",
      "electric",
      "gas",
      "solar"
      ],
      "required": false
    },
    "notes": {
      "type": "string",
      "required": false
    }
  }
}
200 response

{
  "conditioned_sqft": 800,
  "id": 1,
  "nickname": "Main Street Apartments",
  "n_stories": 2,
  "n_apartments": 1,
  "sqft": 1000,
  "year_built": "2000",
  "notes": "notes",
  "type": "sf_detached",
  "basement":
    {
      "sqft": 200,
      "conditioned": false
    },
  "cooling":
    {
      "system": "window_ac"
    },
  "heating":
    {
      "fuel": "Gas",
      "system": "furnace"
    },
  "hot_water":
    {
      "fuel": "Solar",
      "system": "other"
    },
  "location":
    {
      "city": "Boston",
      "climate_zone": null,
      "country": "United States",
      "county": "Suffolk",
      "state": "MA",
      "street_address": "123 Main St",
      "zip_code": "02118"
    }
}
400 response

{
  "errors": "Home users may only have one building"
}

Show details for building

GET
/api/v1/wego_home/building

Show details for current user's building, if it exists.

200 response

{
  "conditioned_sqft": 12000,
  "id": 1,
  "nickname": "The Big Building",
  "n_stories": 3,
  "sqft": 13000,
  "year_built": 1950,
  "type": "Low-rise / garden-style apartment building",
  "basement":
    {
      "sqft": 1000,
      "conditioned": false
    },
  "cooling":
    {
      "system": "Window AC"
    },
  "heating":
    {
      "fuel": "Gas",
      "system": "Boiler (High-efficiency condensing)"
    },
  "hot_water":
    {
      "fuel": "Gas",
      "system": "Indirect hot water tank off boiler (Heat & DHW)"
    },
  "location":
    {
      "city": "Boston",
      "climate_zone": "cold",
      "country": "United States",
      "county": "Suffolk",
      "state": "MA",
      "street_address": "1 Example Street",
      "zip_code": "02201"
    }
}
404 response

{
  "errors": "Building not found"
}

Delete a user's building

DELETE
/api/v1/wego_home/buildings

Deletes a user's building as well as any associated meters and raw data.

204 response

{}
404 response

{
  "errors": "Building not found"
}

Meters

Create a home user meter

post
/api/v1/wego_home/meters

You can create a meter capable of automated importing from our system by passing a valid utility_company_id or you can provide the name of a non-supported utility company using other_utility_company.

If you use a non-supported utility company the meter will not be capable of automated importing but you will still be able to create raw data points using our Raw Data API.

If you provide a utility_company_id but do not provide a username and password the meter will not be capable of automated importing.

To find a valid utility_company_id see our Utility Companies API. Note that the data_type of the meter must match the data_type of the utility company.

Developers may wish to use the JSON Schema Lint website to validate requests against the schema defined below.

Request body

{
  "account_number": "ABCD123",
  "utility_company_id": 42,
  "data_type": "electric",
  "username": "foo",
  "password": "bar"
}
Schema

{
  "type": "object",
  "required": true,
  "properties": {
    "account_number": {
      "type": "string",
      "required": true
    },
    "data_type": {
      "enum": [
        "electric",
        "gas",
        "oil",
        "water",
        "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"
    }
  }
}
200 response

{
  "id": 1
}
400 response

{
  "errors": "Account number can't be blank"
}

Destroy home user meter

delete
/api/v1/wego_home/meters/{id}

This will destroy the specified meter. The server will respond with status code 204 with no body, or with status code 400 if the meter was not found.

Get a list of meters

GET
/api/v1/wego_home/meters

Get a list of meters owned by the current user.

200 response

[
  {
    "id": 1,
    "account_number": "12345",
    "buildings_count": 1,
    "coverage": "all",
    "data_type": "Gas",
    "notes": "Some notes",
    "nickname": null,
    "notes": "Some notes",
    "scope": "HomeMeter",
    "utility_company": {
      "id": 23,
      "name": "Con Edison"
    }
  },

  {
    "id": 2,
    "account_number": "67890",
    "buildings_count": 1,
    "coverage": "all",
    "data_type": "Gas",
    "notes": "Some notes",
    "nickname": null,
    "notes": "Some notes",
    "scope": "HomeMeter",
    "utility_company": {
      "id": null,
      "name": "My Very Own Custom Utility Company"
    }
  }
]

Raw Data

Create a raw datum for a meter

post
/api/v1/wego_home/meters/{id}/raw_data

You create a raw datum by specifying a meter in the url and posting to the raw data end point using the token of the user that owns the meter.

Each type of meter (electric, gas, oil, propane, steam, and water) has its own raw datum type with common and specific fields. A request is listed for gas. Schemas for each of the different types of raw datum are listed below.

Developers may wish to use the JSON Schema Lint website to validate requests against one of the schemas defined 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"
}

Raw data by meter

get
/api/v1/wego_home/meters/{id}/raw_data

Get a list of raw data for a meter.

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
  }
]

Delete a raw datum

delete
/api/v1/wego_home/meters/{meter_id}/raw_data/{id}

Deletes a raw datum associated with a meter.

204 response

{}
404 response

{
  "errors": "Raw datum not found"
}