JESS Web Service API
Version 1.0, ©2020 Energy Simulation Solutions Ltd
The JEplus Simulation Service (JESS) is an online server for running EnergyPlus and Radiance simulations on the ENSIMS' hybrid-cloud. Most of the jobs are executed on our on-premise cluster using the best computing nodes that are most suitable for the types of jobs. For large parametric simulations, additional cloud computing resources may be employed. In this way, JESS can deliver the best turn-around time for the users.
Key features
JESS offers some unique features to run E+ simulations online using ENSIMS' high-performance computing facilities.
- Support both EnergyPlus simulations and jEPlus projects
- Transparently support all E+ versions from V7.0 and above, with new versions added as soon as they are released
- Unique run period-split method, delivering 5x acceleration on average while maintaining compatibility and accuracy in most use cases
- Accessible using either a small client program for drop-in replacement of EnergyPlus.exe, or using the web API
- Additional data access and viewer support through the web service
How to access
You will need an account on the ENSIMS web platform first, and request or link a separate JESS account to it. First, go to https://app.ensims.com and create an account. After log on, go to “My Account”, fill in your contact details (for invoicing) and then request a JESS account. The whole process takes only a few minutes.
Here is a video showing the process: https://youtu.be/LQmx2BiET70
API
Here is a summary of the available REST API functions.
User Authentication
| Command | OP | URL | Cookie | Data | Return |
|---|---|---|---|---|---|
| Log on with credentials | POST | https://api.ensims.com/users/api/auth | none | User credential | Auth return |
| Check in with existing keys | POST | https://api.ensims.com/users/api/checkin | JWT | none | Auth return |
JESS Operations
- End point URL: https://api.ensims.com/jess_web/api
| Group | Command | OP | URL | Cookie | Data | Return |
|---|---|---|---|---|---|---|
| General | Version info inquiry | GET | /info | none | none | Version info |
| JESS Account | Set/Update JESS Session | POST | /session | JWT | JESS credential | Response |
| Verify JESS Session | GET | /session | JWT | none | Response | |
| Get JESS Account Info | GET | /account | JWT | none | Account Info Object | |
| Get Usage Info | GET | /usage | JWT | none | Usage Summary Object | |
| Get Jobs List | POST | /jobs | JWT | Filter | Job list report | |
| Jobs | Upload and Run | POST | /job | JWT | Form data | Response |
| Run uploaded files | POST | /job | JWT | Command | Response | |
| Rerun an existing job | POST | /job | JWT | Command | Response | |
| Cancel job | POST | /job/<job ID> | JWT | Command | Response | |
| Get Job Status | GET | /job/status/<job ID> | JWT | none | Job status object | |
| Get result directory | GET | /job/dir/<job ID> | JWT | none | Result directory object | |
| Download results | GET | /job/file/<job ID>[ext=???] | JWT | none | Zipped folder contents | |
| Download a result file/folder | GET | /job/file/<job ID>/<file name> | JWT | none | File stream | |
| Get a file in text mode | GET | /job/text/<job ID>/<file name> | JWT | none | File contents | |
| Utilities | ESO - get indexes | GET | /eso/<job ID>/<case id>/<file name> | JWT | none | ESO variable tree object |
| ESO - get variable | GET | /eso/var/<job ID>/<case id>/<file name>/<period>/<vars> | JWT | none | ESO variable data | |
| IDF - get tree | GET | /idf/<job ID>/<case id>/<file name> | JWT | none | IDF object tree | |
| IDF - get objects | GET | /idf/<job ID>/<case id>/<file name>/<type>/<obj id> | JWT | none | IDF object contents | |
| DXF - get 3D model ref | GET | /dxf/<job ID>/<case id>/<file name> | JWT | none | 3D model reference | |
| Other | IDD - Get tree | GET | /idd/<version> | none | none | IDD Type Tree |
| IDD - Get tree (alt) | GET | /idd/alt/<version> | none | none | IDD Type Tree | |
| IDD - Get definition | GET | /idd/<version>/<type> | none | none | IDD Type Definition | |
| IDD - Get reference | GET | /idd/<version>/doc/<type> | none | none | Ref URL | |
| EPW - Get data (epw) | GET | /epw/<name> | none | none | File contents | |
| EPW - Get stats (json) | GET | /epw/json/<name> | none | none | Stats object |
Accessing the API
The REST API is accessible with any HTTP client that allows you to assign data to the header and the body of each request. JEA uses only the GET and the POST methods. In general, when a data object is sent in the request's body, the POST method is used. To experiment and test the API commands, we recommend Postman. A Postman collection of transactions showing all the commands is available to download here.
Depending on the programming language you are using, there are numerous HTTP client to choose from. In this document, the examples of using curl and Requests for Python are provided in the descriptions of each transaction. Here is a quick example using the get version info command.
Browser
Since this command does not require authentication, you can try it in a web browser by typing in the following URL:
https://api.ensims.com/jess_web/api/info
If the service is accessible, you will receive a page containing the following text:
{
"Title" : "JESS Web API",
"Description" : "JESS online simulation services API provided by ENSIMS Ltd.",
"Major" : 1,
"Minor" : 0,
"Revision" : 0,
"Release" : "beta",
"Update" : 1,
"Notice" : "(C) 2020, Energy Simulation Solutions Ltd. All rights reserved."
}
curl
Send the same command using curl:
curl https://api.ensims.com/jess_web/api/info
The same text will be return with successful execution.
Requests
Make sure Requests is correctly installed in your Python environment, and run the following the lines:
>>> import requests
>>> r = requests.get('https://api.ensims.com/jess_web/api/info')
>>> r.json