RESTful Web Service
The Asset Score API is a RESTful style web service. For more information about REST, please visit: http://en.wikipedia.org/wiki/Representational_state_transfer
API Organization Token
In order to create an account to authenticate and utilize the API, users must first get an API Organization Token. The token must be passed along with the parameters used when creating a new account.
Once the organization token is received the API can be utilized to create a user account. A user account is used to obtain an API Access Token, described below. Follow the API documentation for details of the parameters needed: POST /api/v2/users
Organization token request
To request an organization token, please send an email with the subject line "Request API Token" to: asset.score@ee.doe.gov. For our records, please include the name of the organization you are working with (or 'personal' if not associated with an organization), and a brief description of the intent of your use of the API with your request.
API Use Protocol
Once an organization token request has been approved and generated, the token will be sent via email, which will appear as a 20-digit code consisting entirely of upper alpha, lower alpha and numeric digits. The API code will be installed on our API test server which exists for you to develop and test your application. The API test server is located at https://api.labworks.org.
Once you have completed your development, please contact us again so that we may install your API code on the production server if desired.
API Access Token
Once a user account has been created the user can authenticate against the API to generate a user-specific access token. All subsequent interactions with the API must include the authenticated user's API token. Follow the API documentation for details of authentication method: POST /api/v2/users/authenticate
The API Access Token is specific to an individual user and is distinct from the API Organization Token. The API Organization Token is used only to create user accounts and to authenticate those accounts in order to receive the API Access Token.
To use your API access token, simply pass the key as a URL parameter when making requests. For example:
GET https://api.labworks.org/api/v2/preview_buildings?token=YOUR_UNIQUE_TOKEN
API Documentation
All API documentation can be found at: API Documentation
Summary of Steps
- Request an API Organization Token. Send email with subject line "Request API Token" to: asset.score@ee.doe.gov
- Use the API Organization Token to create a user account: POST /api/v2/users
- Authenticate the user account using the API Organization Token to receive an API Access Token: POST /api/v2/users/authenticate
- Use the API Access Token in further API requests.
Data Documentation
Download a description of the data elements as described in: EnergyAssetScoreDataModel.v1.pdf